Back to Details

agentica-server

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agentica Server + Claude Proxy Setup

Agentica Server + Claude Proxy 搭建指南

Complete reference for running Agentica SDK with a local Claude proxy. This enables Python agents to use Claude CLI as their inference backend.
这是一份使用本地Claude Proxy运行Agentica SDK的完整参考文档，它能让Python Agent将Claude CLI作为推理后端。

When to Use

使用场景

Use this skill when:
  • Starting Agentica development with Claude proxy
  • Debugging connection issues between SDK, server, and proxy
  • Setting up a fresh Agentica environment
  • Troubleshooting agent tool access or hallucination issues
在以下场景中使用本指南：
  • 开始基于Claude Proxy的Agentica开发
  • 调试SDK、服务器与Proxy之间的连接问题
  • 搭建全新的Agentica环境
  • 排查Agent工具访问或幻觉问题

Architecture

架构设计

Agentica SDK (client code)
    | 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)
Agentica SDK (client code)
    | 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)

Environment Variables

环境变量

VariableSet ByUsed ByPurpose
INFERENCE_ENDPOINT_URL
Humanagentica-serverWhere server sends LLM inference requests
S_M_BASE_URL
HumanAgentica SDK clientWhere SDK connects to session manager
KEY: These are NOT the same endpoint!
  • SDK connects to server (port 2345)
  • Server connects to proxy (port 8080)
变量名设置方使用方用途
INFERENCE_ENDPOINT_URL
人工配置agentica-server服务器发送LLM推理请求的地址
S_M_BASE_URL
人工配置Agentica SDK客户端SDK连接会话管理器的地址
**重点提示：**这两个端点并不相同！
  • SDK连接服务器（端口2345）
  • 服务器连接Proxy（端口8080）

Startup Sequence

启动流程

Must start in this order (each in a separate terminal):
必须按以下顺序启动（每个步骤在单独终端中执行）：

Terminal 1: Claude Proxy

终端1：启动Claude Proxy

bash
uv run python scripts/agentica/claude_proxy.py --port 8080
bash
uv run python scripts/agentica/claude_proxy.py --port 8080

Terminal 2: Agentica Server

终端2：启动Agentica Server

MUST run from its directory:
bash
cd workspace/agentica-research/agentica-server
INFERENCE_ENDPOINT_URL=http://localhost:8080/v1/chat/completions uv run agentica-server --port 2345
必须在其所在目录下运行：
bash
cd workspace/agentica-research/agentica-server
INFERENCE_ENDPOINT_URL=http://localhost:8080/v1/chat/completions uv run agentica-server --port 2345

Terminal 3: Your Agent Script

终端3：运行你的Agent脚本

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

Health Checks

健康检查

bash
undefined
bash
undefined

Claude proxy health

检查Claude Proxy健康状态

curl http://localhost:8080/health
curl http://localhost:8080/health

Agentica server health

检查Agentica Server健康状态

curl http://localhost:2345/health
undefined
curl http://localhost:2345/health
undefined

Common Errors & Fixes

常见错误与修复方案

1. APIConnectionError after agent spawn

1. Agent启动后出现APIConnectionError

Symptom: Agent spawns successfully but fails on first call with connection error.
Cause: Claude proxy returning plain JSON instead of SSE format.
Fix: Proxy must return Server-Sent Events format:
data: {"choices": [...]}\n\n
**症状：**Agent成功启动，但首次调用时出现连接错误。
**原因：**Claude Proxy返回的是普通JSON格式，而非SSE格式。
**修复：**Proxy必须返回Server-Sent Events格式：
data: {"choices": [...]}\n\n

2. ModuleNotFoundError for agentica-server

2. agentica-server模块找不到（ModuleNotFoundError）

Symptom: 
ModuleNotFoundError: No module named 'agentica_server'
Cause: Running 
uv run agentica-server
from wrong directory.
Fix: Must 
cd workspace/agentica-research/agentica-server
first.
**症状：**出现错误 
ModuleNotFoundError: No module named 'agentica_server'
**原因：**在错误的目录下执行
uv run agentica-server
命令。
**修复：**必须先进入目录
workspace/agentica-research/agentica-server

3. Agent can't use Read/Write/Edit tools

3. Agent无法使用读/写/编辑工具

Symptom: Agent asks for file contents instead of reading them.
Cause: Missing 
--allowedTools
in claude_proxy.py CLI call.
Fix: Proxy must pass tool permissions:
bash
claude -p ... --allowedTools Read Write Edit Bash
**症状：**Agent询问文件内容而非直接读取。
**原因：**claude_proxy.py的CLI调用中缺少
--allowedTools
参数。
**修复：**Proxy必须传递工具权限：
bash
claude -p ... --allowedTools Read Write Edit Bash

4. Agent claims success but didn't do task

4. Agent声称任务成功但未实际执行

Symptom: Agent says "I've created the file" but file doesn't exist.
Cause: Hallucination - agent describing intended actions without executing.
Fix: Added emphatic anti-hallucination prompt in REPL_BASELINE:
CRITICAL: Use ACTUAL tools. Never DESCRIBE using tools.
**症状：**Agent说“我已创建文件”但文件实际不存在。
**原因：**幻觉问题 - Agent描述了预期操作但并未实际执行。
**修复：**在REPL_BASELINE中添加明确的反幻觉提示：
CRITICAL: Use ACTUAL tools. Never DESCRIBE using tools.

5. Timeout on agent.call()

5. agent.call()请求超时

Symptom: Call hangs for 30+ seconds then times out.
Cause: Claude CLI taking too long or stuck in a loop.
Fix: Check proxy logs for the actual CLI output. May need to simplify prompt.
**症状：**调用卡住30秒以上后超时。
**原因：**Claude CLI处理时间过长或陷入循环。
**修复：**查看Proxy日志中的CLI实际输出，可能需要简化提示词。

Key Files

关键文件

FilePurpose
scripts/agentica/claude_proxy.py
OpenAI-compatible proxy with SSE streaming
workspace/agentica-research/agentica-server/
Local agentica-server installation
scripts/agentica/PATTERNS.md
Multi-agent pattern documentation
文件路径用途
scripts/agentica/claude_proxy.py
支持SSE流式传输的OpenAI兼容Proxy
workspace/agentica-research/agentica-server/
本地agentica-server安装目录
scripts/agentica/PATTERNS.md
多Agent模式文档

Quick Verification

快速验证

Test the full stack:
bash
undefined
测试完整链路：
bash
undefined

1. Verify proxy responds

1. 验证Proxy响应

curl http://localhost:8080/health
curl http://localhost:8080/health

2. Verify server responds

2. 验证Server响应

curl http://localhost:2345/health
curl http://localhost:2345/health

3. Test inference through proxy

3. 通过Proxy测试推理功能

curl http://localhost:8080/v1/chat/completions
-H "Content-Type: application/json"
-d '{"model":"claude","messages":[{"role":"user","content":"Say hello"}]}'
undefined
curl http://localhost:8080/v1/chat/completions
-H "Content-Type: application/json"
-d '{"model":"claude","messages":[{"role":"user","content":"Say hello"}]}'
undefined

Checklist

检查清单

Before running agents:
  • Claude proxy running on port 8080
  • Agentica server running on port 2345 (from its directory)
  • S_M_BASE_URL
    set for client scripts
  • INFERENCE_ENDPOINT_URL
    set for server
  • Both health checks return 200
运行Agent前请确认：
  • Claude Proxy已在端口8080启动
  • Agentica Server已在端口2345启动（需在对应目录下运行）
  • 客户端脚本已设置
    S_M_BASE_URL
  • 服务器已设置
    INFERENCE_ENDPOINT_URL
  • 两项健康检查均返回200状态码