名称: agentica-server 描述: Agentica服务器 + Claude代理设置 - 架构, 启动序列, 调试允许工具: [Bash, Read] 用户可调用: false

Agentica 服务器 + Claude 代理设置

运行Agentica SDK与本地Claude代理的完整参考。这使得Python代理能够使用Claude CLI作为其推理后端。

何时使用

使用此技能当：

开始使用Claude代理进行Agentica开发
调试SDK、服务器和代理之间的连接问题
设置新的Agentica环境
解决代理工具访问或幻觉问题

架构

Agentica SDK (客户端代码)
    | S_M_BASE_URL=http://localhost:2345
    v
ClientSessionManager
    |
    v
Agentica Server (agentica-server)
    | INFERENCE_ENDPOINT_URL=http://localhost:8080/v1/chat/completions
    v
Claude Proxy (claude_proxy.py)
    |
    v
Claude CLI (claude -p)

环境变量

变量	设置者	使用者	目的
`INFERENCE_ENDPOINT_URL`	用户	agentica-server	服务器发送LLM推理请求的位置
`S_M_BASE_URL`	用户	Agentica SDK客户端	SDK连接到会话管理器的位置

关键点: 这些不是相同的端点！

SDK连接到服务器 (端口2345)
服务器连接到代理 (端口8080)

启动序列

必须按此顺序启动（每个在单独终端中）：

终端1: Claude代理

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

终端3: 您的代理脚本

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

健康检查

# Claude代理健康检查
curl http://localhost:8080/health

# Agentica服务器健康检查
curl http://localhost:2345/health

常见错误与修复

1. 代理生成后出现APIConnectionError

症状: 代理成功生成，但在第一次调用时失败并出现连接错误。

原因: Claude代理返回纯JSON而非SSE格式。

修复: 代理必须返回服务器发送事件格式：

data: {"choices": [...]}

2. agentica-server的ModuleNotFoundError

症状: ModuleNotFoundError: No module named 'agentica_server'

原因: 从错误目录运行uv run agentica-server。

修复: 必须先cd workspace/agentica-research/agentica-server。

3. 代理无法使用Read/Write/Edit工具

症状: 代理请求文件内容而不是读取它们。

原因: 在claude_proxy.py CLI调用中缺少--allowedTools。

修复: 代理必须传递工具权限：

claude -p ... --allowedTools Read Write Edit Bash

4. 代理声称成功但未执行任务

症状: 代理说“我已创建文件”但文件不存在。

原因: 幻觉 - 代理描述预期操作而未执行。

修复: 在REPL_BASELINE中添加强调的反幻觉提示：

关键: 使用实际工具。永远不要描述使用工具。

5. agent.call()超时

症状: 调用挂起30+秒后超时。

原因: Claude CLI耗时过长或卡在循环中。

修复: 检查代理日志以查看实际CLI输出。可能需要简化提示。

关键文件

文件	目的
`scripts/agentica/claude_proxy.py`	具有SSE流式的OpenAI兼容代理
`workspace/agentica-research/agentica-server/`	本地agentica-server安装
`scripts/agentica/PATTERNS.md`	多代理模式文档

快速验证

测试完整堆栈：

# 1. 验证代理响应
curl http://localhost:8080/health

# 2. 验证服务器响应
curl http://localhost:2345/health

# 3. 通过代理测试推理
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"claude","messages":[{"role":"user","content":"Say hello"}]}'

清单

运行代理前：

[ ] Claude代理在端口8080上运行
[ ] Agentica服务器在端口2345上运行（从其目录）
[ ] 为客户端脚本设置S_M_BASE_URL
[ ] 为服务器设置INFERENCE_ENDPOINT_URL
[ ] 两个健康检查都返回200

名称: agentica-server 描述: Agentica服务器 + Claude代理设置 - 架构, 启动序列, 调试 允许工具: [Bash, Read] 用户可调用: false