agentica claude proxy

AI Community

Skill notes

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 -p mode 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:

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
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.

Author source file SKILL.md

# 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 |

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.