用途
agentica-claude-proxy 是一份用于开发和调试 Agentica SDK 与 Claude Code CLI 代理集成的技能指南。当需要让 Agentica 代理使用 Claude Code 工具、排查代理幻觉问题、修复文件操作权限错误，或理解 REPL 响应格式时，可使用本技能。
架构概览
整体调用链路为：
Agentica Agent → S_M_BASE_URL → Claude Proxy → claude -p → Claude CLI（带工具）
其中 Claude Proxy 默认运行在 localhost:8080，Agentica 服务默认运行在 localhost:2345。
关键要求
1. --allowedTools 标志（必需）
Claude CLI 在 -p 模式下会限制文件操作，必须显式添加允许的工具：
subprocess.run([
"claude", "-p", prompt,
"--append-system-prompt", system_prompt,
"--allowedTools", "Read", "Write", "Edit", "Bash", # REQUIRED
])
若不添加该标志，代理在执行 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 响应格式（必需）
代理必须以带 return 语句的 Python 代码块返回结果：
return "your result here"
Agentica 的 REPL 解析器会提取 python 与 之间的代码。
防幻觉提示工程
除非明确警告，代理会在未实际使用工具的情况下幻觉出成功结果。文档建议加入如下警告：
## 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/。
调试
查看代理日志
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 |
| 代理声称成功但文件未创建 | 幻觉 | 添加防幻觉提示段落 |
| "Cannot access /tmp/..." | 沙箱限制 | 使用项目相对路径 |
| "APIConnectionError" | 响应格式错误 | 使用 SSE 流式（data: {...}\n\n） |
| "NameError: view_file" | 代理使用了 REPL 函数 | 添加带原生工具示例的 REPL_BASELINE |
适用场景与限制
本技能适用于开发或调试 Agentica 与 Claude Code 代理集成的场景，尤其是涉及工具调用、文件操作、流式响应和沙箱路径问题时。文档未提供关于收费、价格、平台支持范围或性能效果的信息，这些内容暂未提供。