name: agentica-claude-proxy description: 用于整合Agentica SDK与Claude Code CLI代理的指南 allowed-tools: [Read, Bash] user-invocable: false

Agentica-Claude代码代理集成

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

何时使用

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

架构概述

Agentica代理 → S_M_BASE_URL → Claude代理 → claude -p → Claude CLI（带工具）
                 (localhost:2345)   (localhost:8080)

关键要求

1. --allowedTools标志（必需）

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

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

没有此标志，代理在写入/编辑操作时会报告“权限被拒绝”。

2. SSE流格式（必需）

Agentica期望SSE流，而不是纯JSON：

# 响应格式
yield f"data: {json.dumps(chunk)}

"
yield "data: [DONE]

"

3. REPL响应格式（必需）

代理必须将结果作为Python代码块返回，带有return语句：

return "您的结果在这里"

Agentica的RELP解析器提取\``python和```之间的代码。

反幻觉提示工程

除非您明确警告代理，否则它们会在未实际使用工具的情况下幻觉成功：

## 反幻觉警告

**停止并仔细阅读此内容：**

您可以访问这些工具：Read, Write, Edit, Bash

当任务要求您创建/修改/运行某些内容时：
1. 首先：实际调用工具（Read, Write, Edit或Bash）
2. 其次：等待工具结果
3. 第三：然后根据实际发生的情况返回您的答案

**不要**跳过工具调用并声称成功！

如果您没有调用工具，您不能声称操作成功。

路径沙箱

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": "在workspace/test.txt创建文件"}], "stream": false}'

验证文件操作

# 代理声称创建文件后
ls -la workspace/test.txt
cat workspace/test.txt

服务器命令

启动服务器

# 终端1：代理
uv run python scripts/agentica/claude_proxy.py --port 8080

# 终端2：Agentica服务器
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  # 代理
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

常见错误

错误	原因	修复
“权限被拒绝”	缺少–allowedTools	添加`--allowedTools Read Write Edit Bash`
代理声称成功但文件未创建	幻觉	添加反幻觉提示部分
“无法访问/tmp/…”	沙箱限制	使用项目相对路径
“APIConnectionError”	错误响应格式	使用SSE流（data: {…}