agentica claude proxy
- Repo stars 3,783
- Author repo Continuous-Claude-v3
- Domain
- AI
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @parcadei · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- Python
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- External requests
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# Agentica-Claude Code Proxy Integration
Use this skill when developing or debugging the Agentica-Claude proxy integration.
## When to Use
- Setting up Agentica agents to use Claude Code tools
- Debugging agent hallucination issues
- Fixing permission errors in file operations
- Understanding the REPL response format
## Architecture Overview
```
Agentica Agent → S_M_BASE_URL → Claude Proxy → claude -p → Claude CLI (with tools)
(localhost:2345) (localhost:8080)
```
## Critical Requirements
### 1. --allowedTools Flag (REQUIRED)
Claude CLI in `-p` mode restricts file operations. You MUST add:
```python
subprocess.run([
"claude", "-p", prompt,
"--append-system-prompt", system_prompt,
"--allowedTools", "Read", "Write", "Edit", "Bash", # REQUIRED
])
```
Without this, agents will report "permission denied" for Write/Edit operations.
### 2. SSE Streaming Format (REQUIRED)
Agentica expects SSE streaming, not plain JSON:
```python
# Response format
yield f"data: {json.dumps(chunk)}\n\n"
yield "data: [DONE]\n\n"
```
### 3. REPL Response Format (REQUIRED)
Agents MUST return results as Python code blocks with a return statement:
```python
return "your result here"
```
Agentica's REPL parser extracts code between \`\`\`python and \`\`\`.
## Anti-Hallucination Prompt Engineering
Agents will hallucinate success without actually using tools unless you explicitly warn them:
```
## ANTI-HALLUCINATION WARNING
**STOP AND READ THIS CAREFULLY:**
You have access to these tools: Read, Write, Edit, Bash
When the task asks you to create/modify/run something:
1. FIRST: Actually invoke the tool (Read, Write, Edit, or Bash)
2. SECOND: Wait for the tool result
3. THIRD: Then return your answer based on what actually happened
**DO NOT** skip the tool invocation and just claim success!
If you didn't invoke a tool, you CANNOT claim the action succeeded.
```
## Path Sandboxing
Both Claude Code and Agentica have sandboxes:
- `/tmp/` paths are blocked by Claude Code
- Files outside project directory blocked by Agentica
**Solution:** Use project-relative paths like `workspace/` instead of `/tmp/`
## Debugging
### Check Agent Logs
```bash
cat logs/agent-<N>.log
```
Note: Logs only show final conversational response, not tool invocations.
### Test Proxy Directly
```bash
curl -s http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model": "claude", "messages": [{"role": "user", "content": "Create file at workspace/test.txt"}], "stream": false}'
```
### Verify File Operations
```bash
# After agent claims to create file
ls -la workspace/test.txt
cat workspace/test.txt
```
## Server Commands
### Start Servers
```bash
# Terminal 1: Proxy
uv run python scripts/agentica/claude_proxy.py --port 8080
# Terminal 2: Agentica Server
cd workspace/agentica-research/agentica-server
INFERENCE_ENDPOINT_URL=http://localhost:8080/v1/chat/completions uv run agentica-server --port 2345
```
### Use Swarm
```bash
S_M_BASE_URL=http://localhost:2345 uv run python your_script.py
```
### Health Checks
```bash
curl http://localhost:8080/health # Proxy
curl http://localhost:2345/health # Agentica
```
## Reference Files
- Proxy implementation: `scripts/agentica/claude_proxy.py`
- REPL_BASELINE prompt: `scripts/agentica/claude_proxy.py:49-155`
- Comprehensive test: `workspace/test_swarm_all_tools.py`
- DependencySwarm: `scripts/agentica/dependency_swarm.py`
## Common Errors
| Error | Cause | Fix |
|-------|-------|-----|
| "Permission denied" | Missing --allowedTools | Add `--allowedTools Read Write Edit Bash` |
| Agent claims success but file not created | Hallucination | Add anti-hallucination prompt section |
| "Cannot access /tmp/..." | Sandbox restriction | Use project-relative paths |
| "APIConnectionError" | Wrong response format | Use SSE streaming (data: {...}\n\n) |
| "NameError: view_file" | Agent using REPL functions | Add REPL_BASELINE with native tool examples |
Sections and files
Listed in source order.
sections -> When to Use → Architecture Overview → Critical Requirements → 1. --allowedTools Flag (REQUIRED) → 2. SSE Streaming Format (REQUIRED) → 3. REPL Response Format (REQUIRED)
terms -> STOP AND READ THIS CAREFULLY · DO NOT · Solution · Use this skill when developing or debugging the Agentica-Claude proxy integration. · Claude CLI in -p mode restricts file operations. · Without this, agents will report "permission denied" for Write/Edit operations. · Agentica's REPL parser extracts code between \\\python and \\\. · When the task asks you to create/modify/run something: 1.
files/cmd -> python and \ · /tmp/ · workspace/ · scripts/agentica/claude_proxy.py · scripts/agentica/claude_proxy.py:49-155 · workspace/test_swarm_all_tools.py · scripts/agentica/dependency_swarm.py · --allowedTools Read Write Edit Bash
body sha256 -> 1e71c82f604d
When to Use
Setting up Agentica agents to use Claude Code tools Debugging agent hallucination issues Fixing permission errors in file operations Understanding the REPL response format
1. --allowedTools Flag (REQUIRED)
Claude CLI in
-pmode restricts file operations. You MUST add: Without this, agents will report "permission denied" for Write/Edit operations.2. SSE Streaming Format (REQUIRED)
Agentica expects SSE streaming, not plain JSON:
3. REPL Response Format (REQUIRED)
Agents MUST return results as Python code blocks with a return statement: Agentica's REPL parser extracts code between ```python and ```.
Anti-Hallucination Prompt Engineering
Agents will hallucinate success without actually using tools unless you explicitly warn them: