mcpField
A
agentica-server

agentica-server

github.com/parcadeiAgent 工作流3.9k476 次安装39 周前更新
代码仓库

关于 agentica-server

提供 Agentica SDK、agentica-server 与本地 Claude 代理的配置和排障指南，面向开发 Python Agent 的人员。重点说明服务启动顺序、端点配置及常见调用故障。

主要功能

  1. 01配置 SDK、服务端与代理
  2. 02按序启动本地服务
  3. 03检查健康状态
  4. 04排查工具调用与超时问题

适用场景

  1. 01搭建 Agentica 与 Claude 代理环境
  2. 02诊断服务端和代理的连接问题
  3. 03排查 Agent 无法使用文件工具

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/parcadei/continuous-claude-v3 --skill agentica-server

安装后在 Claude Code 中输入/agentica-server确认已加载。

详细介绍

Agentica 服务端 + Claude 代理设置

运行 Agentica SDK 并使用本地 Claude 代理的完整参考。这样 Python Agent 就能使用 Claude CLI 作为推理后端。

适用场景

在以下情况下使用此技能：

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

架构

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)

环境变量

变量设置者使用者用途
INFERENCE_ENDPOINT_URL人工agentica-server服务端发送大模型推理请求的目标地址
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：你的 Agent 脚本
S_M_BASE_URL=http://localhost:2345 uv run python scripts/agentica/your_script.py

健康检查

# Claude proxy health
curl http://localhost:8080/health

# Agentica server health
curl http://localhost:2345/health

常见错误及修复方法

1. Agent 启动后出现 APIConnectionError

症状： Agent 成功启动，但首次调用时因连接错误而失败。

原因： Claude 代理返回的是普通 JSON，而非 SSE 格式。

修复方法： 代理必须返回 Server-Sent Events 格式：

data: {"choices": [...]}\n\n
2. agentica-server 出现 ModuleNotFoundError

症状： ModuleNotFoundError: No module named 'agentica_server'

原因： 在错误的目录中运行 uv run agentica-server。

修复方法： 必须先执行 cd workspace/agentica-research/agentica-server。

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

症状： Agent 要求提供文件内容，而不是自行读取文件。

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

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

claude -p ... --allowedTools Read Write Edit Bash
4. Agent 声称已完成任务，但实际并未完成

症状： Agent 说“我已创建文件”，但文件并不存在。

原因： 幻觉——Agent 只描述了计划执行的操作，却没有实际执行。

修复方法： 已在 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多 Agent 模式文档

快速验证

测试完整技术栈：

# 1. Verify proxy responds
curl http://localhost:8080/health

# 2. Verify server responds
curl http://localhost:2345/health

# 3. Test inference through proxy
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"claude","messages":[{"role":"user","content":"Say hello"}]}'

检查清单

运行 Agent 前：

  • Claude 代理在端口 8080 上运行
  • Agentica 服务端在端口 2345 上运行（从其目录启动）
  • 为客户端脚本设置 S_M_BASE_URL
  • 为服务端设置 INFERENCE_ENDPOINT_URL
  • 两项健康检查均返回 200

评论

支持 Markdown