agentica-claude-proxy

Agentica-Claude Code 代理集成

开发或调试 Agentica-Claude 代理集成时，请使用此技能。

适用场景

• 设置 Agentica Agent 以使用 Claude Code 工具
• 调试 Agent 幻觉问题
• 修复文件操作中的权限错误
• 了解 REPL 响应格式

架构概览

Agentica Agent → S_M_BASE_URL → Claude Proxy → claude -p → Claude CLI (with tools)
                 (localhost:2345)   (localhost:8080)

关键要求

1. --allowedTools 标志（必需）

Claude CLI 在 -p 模式下会限制文件操作。必须添加：

subprocess.run([
    "claude", "-p", prompt,
    "--append-system-prompt", system_prompt,
    "--allowedTools", "Read", "Write", "Edit", "Bash",  # REQUIRED
])

否则，Agent 在执行 Write/Edit 操作时会报告“permission denied”。

2. SSE 流式传输格式（必需）

Agentica 需要 SSE 流式传输，而不是普通 JSON：

# Response format
yield f"data: {json.dumps(chunk)}\n\n"
yield "data: [DONE]\n\n"

3. REPL 响应格式（必需）

Agent 必须以带有 return 语句的 Python 代码块返回结果：

return "your result here"

Agentica 的 REPL 解析器会提取 ```python 和 ``` 之间的代码。

防幻觉提示词工程

除非明确提醒，否则 Agent 可能会在未实际使用工具的情况下声称操作成功：

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

路径沙箱

Claude Code 和 Agentica 都有沙箱：

• Claude Code 会屏蔽 /tmp/ 路径
• Agentica 会屏蔽项目目录之外的文件

解决方案： 使用 workspace/ 等相对于项目的路径，而不要使用 /tmp/

调试

检查 Agent 日志

cat logs/agent-<N>.log

注意：日志只显示最终的对话响应，不显示工具调用。

直接测试代理

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}'

验证文件操作

# After agent claims to create file
ls -la workspace/test.txt
cat workspace/test.txt

服务命令

启动服务

# 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

使用 Swarm

S_M_BASE_URL=http://localhost:2345 uv run python your_script.py

健康检查

curl http://localhost:8080/health  # Proxy
curl http://localhost:2345/health  # Agentica

参考文件

• 代理实现：scripts/agentica/claude_proxy.py
• REPL_BASELINE 提示词：scripts/agentica/claude_proxy.py:49-155
• 综合测试：workspace/test_swarm_all_tools.py
• DependencySwarm：scripts/agentica/dependency_swarm.py

常见错误

错误	原因	修复方法
"Permission denied"	缺少 --allowedTools	添加 --allowedTools Read Write Edit Bash
Agent 声称操作成功，但文件未创建	幻觉	添加防幻觉提示词部分
"Cannot access /tmp/..."	沙箱限制	使用相对于项目的路径
"APIConnectionError"	响应格式错误	使用 SSE 流式传输（data: {...}\n\n）
"NameError: view_file"	Agent 使用 REPL 函数	添加包含原生工具示例的 REPL_BASELINE