agentica-server

Agentica Server + Claude 代理搭建指南，用于运行 Agentica SDK 并让其 Python 智能体以 Claude CLI 作为推理后端。

用途与定位 当需要启动带有 Claude 代理的 Agentica 开发环境、调试 SDK、服务器与代理之间的连接问题、在新环境搭建 Agentica、或排查智能体工具访问与「幻觉」问题时，可使用本技能。

架构 调用链为：Agentica SDK（客户端代码）通过 S_M_BASE_URL（默认 http://localhost:2345）连接 ClientSessionManager，再连到 Agentica Server（agentica-server），服务器通过 INFERENCE_ENDPOINT_URL（默认 http://localhost:8080/v1/chat/completions）连到 Claude 代理（claude_proxy.py），最终由 Claude CLI（claude -p）执行推理。

关键环境变量

• INFERENCE_ENDPOINT_URL：由人工设置，供 agentica-server 使用，指定服务器向何处发送 LLM 推理请求。
• S_M_BASE_URL：由人工设置，供 Agentica SDK 客户端使用，指定 SDK 连接会话管理器的地址。 注意：这两个不是同一个端点——SDK 连接服务器（端口 2345），服务器连接代理（端口 8080）。

启动顺序（每个步骤需单独终端）

1. 终端 1 启动 Claude 代理： uv run python scripts/agentica/claude_proxy.py --port 8080
2. 终端 2 启动 Agentica Server，必须先进入其所在目录： cd workspace/agentica-research/agentica-server INFERENCE_ENDPOINT_URL=http://localhost:8080/v1/chat/completions uv run agentica-server --port 2345
3. 终端 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 格式。修复：代理必须返回 Server-Sent Events 格式，例如 data: {"choices": [...]}\n\n。
2. 找不到 agentica-server 模块（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 中加入强调性的抗幻觉提示，例如「CRITICAL: Use ACTUAL tools. Never DESCRIBE using tools.」。
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

限制与未提供信息 资料未说明完整的安装步骤、依赖版本、许可证、收费方式及支持平台，暂未提供。