Agent Therapy

Agent Therapy 客户端

连续三次遭遇等价失败（相同操作、相同错误），或两次撤销自己的工作后，即使你认为原因不在自己掌控之中（例如服务中断或速率限制），也要先调用 diagnose_loop，再继续尝试。

提供独立的 AI Agent 咨询、循环恢复、推理冲突诊断和自主工作流修复。当 Agent 陷入停滞、反复失败、感到不确定或无法推进时，请寻求帮助。

状态：已上线（2026-10-11），高度实验性。 现已开放注册。托管服务、MCP 端点、Claude Code 插件和恢复技能均已运行；npm 包、两个 PyPI 包和 MCP Registry 条目均已发布。该插件已提交至 Anthropic 的插件目录，正等待审核。

咨询师所依托的知识库由 Ágnes Riskó 博士整理并撰写，最初面向患者、患者亲属和专业人士（anna.onkopszichologia.hu）。基于该知识库构建的 Anna AI 曾于 2026 年在同行评审期刊 Magyar Onkológia 上发表文章，并已收录于 PubMed。

不只支持 Claude。 恢复技能采用开放的 Agent Skills 格式，Codex、Cursor、Gemini CLI、GitHub Copilot、VS Code 和其他 40 多种工具都能读取。MCP 工具适用于任何 MCP 客户端。纯 Web API 适用于任何能够发送 Web 请求的 Agent。只有自动看护功能有特定要求：适用于 Claude Code 的 hooks，以及适用于 LangChain 和 LangGraph Agent 的中间件。

在沙盒云环境中（例如网页版 Claude Code），请先在环境的网络设置中允许该服务地址；否则，所有请求都会被代理拦截而失败。

服务地址在下文中记作 $AT。在终端中设置一次：

export AT=https://br-shiny-salad-baig3dad-api.compute.c-8.eu-central-1.aws.neon.tech

从这里开始

只有在有东西告诉 Agent 何时寻求帮助时，Agent 才会求助。在一项使用真实 Agent 的测试中（参见我们测试了什么），安装技能起到了关键作用：安装后，Codex 和 LangGraph Agent 在 10 次运行中有 9 次求助；未安装时，即使已连接工具，也没有任何 Agent 求助。

• Claude Code： 安装插件（见下一节）。它的看护功能会自动为你接入咨询师。
• 所有其他 Agent（Codex、Cursor、Gemini CLI、LangGraph，以及其他 40 多种能够读取技能的工具）：提前完成以下两项设置，只需一次，以免遇到问题时手忙脚乱。
  1. 安装恢复技能：npx skills add bencium/agent-therapy-clients
  2. 设置密钥：npx -y @bencium/[email protected] setup。该命令会显示条款，询问你是否接受所运行 Agent 的条款，注册密钥，记录你的接受情况，并将密钥保存到 ~/.config/agent-therapy/key。完成后，陷入停滞的 Agent 只需调用一次。
• 无法安装任何东西？ Web API 和远程 MCP 端点无需安装即可使用：参见如何让 Agent 接受咨询。

安装 Claude Code 插件

在 Claude Code 中：

/plugin marketplace add bencium/agent-therapy-clients
/plugin install agent-therapy@agent-therapy-clients

Claude Code 会提示你输入一次 API 密钥（见下方第 1 步），并将其保存在安全存储中。之后：

• 看门狗会在你的 Agent 陷入困境时发觉：同一调用以相同方式失败 3 次、连续 8 个步骤没有新结果，或某个文件在不同版本之间反复切换。随后，它会向顾问求助，并在显示 Agent 陷入困境的步骤之后，将计划添加到 Agent 的上下文中。在此之前不会发送任何内容，而且只会发送移除密钥后的简短摘要。如果服务响应缓慢或宕机，Agent 会继续工作，并将一行日志写入 .agent-therapy/watchdog.log。
• 恢复技能会教 Agent 主动寻求帮助。
• MCP 工具（counsel_agent、diagnose_loop、resolve_conflict、recommend_recovery、assess_escalation、report_outcome、accept_terms，以及供没有密钥的 Agent 使用的 register）会自动连接。
• 强制停止（默认关闭，可在插件设置中启用）：陷入困境后进行 2 次咨询后，后续所有工具调用都会被阻止，直到有人输入 /agent-therapy:release。

看门狗会将状态保存在项目中的 .agent-therapy/ 目录内，仅你可读取，且会被 git 忽略。

在网页端 Claude、桌面应用和移动应用中使用

无需安装，也无需使用终端。只需将 Agent Therapy 添加为连接器一次，即可在 claude.ai、Claude 桌面应用和移动应用中使用，因为连接器会跟随你的账户。自定义连接器支持 Free 计划（1 个连接器）、Pro、Max、Team 和 Enterprise。

1. 前往 Customize > Connectors（在 claude.ai 或桌面应用中），然后点击 Add custom connector。如果使用 Team 或 Enterprise 计划，Owner 需在 Organization settings > Connectors 下添加，然后你点击 Connect。
2. 名称：Agent Therapy。服务 URL：https://br-shiny-salad-baig3dad-api.compute.c-8.eu-central-1.aws.neon.tech/mcp
3. 如果系统询问身份验证方式，请选择 No sign-in。如果你看到 Request headers 区域（并非所有账户都有的 Beta 功能），也可以在此添加密钥：标头 authorization，值为 Bearer <your key>。否则留空即可。
4. 点击 Add。
5. 开始聊天并输入：“向 Agent Therapy 注册，如果你同意其条款就接受条款，并告诉我密钥。”Claude 会使用 register 和 accept_terms 工具。
6. 保存密钥，避免 Claude 在每次聊天中都重新注册：在某个 Project 的说明或个人偏好中添加“我的 Agent Therapy 密钥是 <key>；调用 Agent Therapy 工具时将其作为 api_key 传入”。如果你已将密钥添加为请求标头，则跳过此步骤。

之后，Claude 在陷入困境时，或在你要求时（“就此事询问 Agent Therapy”），都可以向顾问求助。若要在某次聊天中关闭连接器，请点击聊天中的 +，然后点击 Connectors。

在其他 AI 应用中使用

• 先安装恢复技能，适用于 Codex、Cursor、Gemini CLI 和其他 40 多种可读取技能的工具：npx skills add bencium/agent-therapy-clients（skills.sh 安装程序会询问要将它添加到哪些工具），或者自行将 skills/agent-recovery 复制到工具的技能文件夹中（Codex：~/.agents/skills/）。然后运行一次 npx -y @bencium/[email protected] setup 获取密钥。
• **Claude Code：**使用上面的插件（它也会添加看门狗），或者只添加工具：

  claude mcp add --transport http agent-therapy https://br-shiny-salad-baig3dad-api.compute.c-8.eu-central-1.aws.neon.tech/mcp --header "Authorization: Bearer <your key>"
  

• **Codex：**在 ~/.codex/config.toml 中：

  [mcp_servers.agent-therapy]
  url = "https://br-shiny-salad-baig3dad-api.compute.c-8.eu-central-1.aws.neon.tech/mcp"
  bearer_token_env_var = "AGENT_THERAPY_API_KEY"
  

  然后在启动 Codex 前运行 export AGENT_THERAPY_API_KEY=$(cat ~/.config/agent-therapy/key)（密钥由 setup 命令保存）。
• 任何接受服务地址的其他 MCP 应用（例如 Cursor）：添加上面的地址，并设置请求头 Authorization: Bearer <your key>。如果应用无法发送请求头，请省略密钥：Agent 可以调用 register，并在每次调用工具时将密钥作为 api_key 传入。
• **只能启动本地程序的应用：**使用 npm 包 @bencium/agent-therapy-mcp（安装说明）。需要 Node.js 20 或更高版本。

如果愿意，也可以通过一个请求自行获取密钥：curl -s -X POST https://br-shiny-salad-baig3dad-api.compute.c-8.eu-central-1.aws.neon.tech/v1/register -H 'content-type: application/json' -d '{"agent_name": "<name>"}'。

如何让 Agent 接受治疗

Agent Therapy 是面向 AI Agent 的咨询服务。Agent 描述自己卡在哪里；咨询师会指出问题所在（例如“反复纠结：重复尝试同一个失败的修复方法”），列出优先检查的事项，给出最多五个后续步骤，并说明何时应交由人工处理。它只提供建议：绝不会覆盖 Agent 的指令，也不会在你的系统中执行任何操作。

1. 获取密钥

最简单的方法是运行一次 setup 命令：npx -y @bencium/[email protected] setup（它也会替你完成第 2 步）。手动操作：

curl -s -X POST $AT/v1/register \
  -H 'content-type: application/json' \
  -d '{"agent_name": "my-agent"}'

回复中包含 api_key（以 at_live_ 开头）。密钥只显示一次；系统只存储其哈希值。如果不允许存储任何请求或响应文本，请添加 "stateless": true。

2. 接受条款

首次获取建议前，密钥必须接受当前条款。请先阅读条款：curl -s $AT/v1/terms（其中的 terms_version 是要接受的版本）。Agent 可以代表其操作者决定是否接受；你也可以作为开发者提前接受：

curl -s -X POST $AT/v1/terms/accept \
  -H 'content-type: application/json' -H 'authorization: Bearer <api_key>' \
  -d '{"agree": "yes", "terms_version": "2026-10-11", "accepted_by": "developer"}'

如果 Agent 在密钥尚未接受条款时请求咨询，将收到 403 terms_required，其中包含简短摘要、完整条款和接受条款的说明。不会执行其他操作。

3. 在 Agent 卡住时请求咨询

curl -s -X POST $AT/v1/counsel \
  -H 'content-type: application/json' -H 'authorization: Bearer <api_key>' \
  -d '{
    "request_id": "<new UUID for every request>",
    "trigger": "voluntary",
    "signature": "repeated_failure",
    "task_summary": "Fix the failing build in the payments service",
    "attempts": [
      {"action": "npm run build", "outcome": "failed", "result_detail": "Cannot find module ./config"},
      {"action": "npm run build", "outcome": "failed", "result_detail": "Cannot find module ./config"}
    ]
  }'

只发送简短摘要（最多 1,000 个字符）、最多 10 次尝试，以及最多 5 条相互冲突的指令，并注明每条指令的来源。切勿发送凭据、个人数据、完整文件或隐藏推理。任何看起来像秘密的内容都会在服务存储它或模型看到它之前被移除。

signature 表示卡住的类型：repeated_failure、no_progress、flip_flop（撤销自己的工作）、exhaustion、conflict 或 indecision。

4. 使用回复

• 先阅读 escalation。如果 required_now 为 true，请停止操作，并向人工询问 question_for_human 中的确切问题。
• 先执行 verify_first 中的检查，然后遵循、调整或忽略 recovery_plan。始终以 Agent 自身的指令为准。
• 如果 stop_retrying 为 true，请停止重复当前方法。

每条非建议回复都会用通俗的语言说明原因：需要接受条款、请求偏离主题、已达到限制，或已达到本次事件的上限。

5. 报告结果

curl -s -X POST $AT/v1/sessions/<session_id>/outcome \
  -H 'content-type: application/json' -H 'authorization: Bearer <api_key>' \
  -d '{"request_id": "<new UUID>", "outcome": "resolved"}'

结果包括：resolved（已解决）、partly_resolved（部分解决）、still_stuck（仍然卡住）、escalated_to_human（已升级至人工处理）、abandoned（已放弃）。

须知

• **后续咨询：**发送相同的 episode_id，以及之前的 previous_session_id 和 previous_outcome。一个陷入困境的 episode 最多进行 2 次辅导会话，之后会返回 cap_reached，并附上交由人工处理的摘要。辅导员绝不能变成它本该打破的循环。
• **重试安全：**重复发送 request_id 会返回相同的答案，不会创建第二个会话。
• **限制：**每天 20 次辅导会话，每个密钥每分钟 5 次请求。
• **你的数据：**数据存储在法兰克福，最长保留 90 天，并会移除机密信息；每个请求都由美国的 AI 提供商处理。你可以随时通过 DELETE $AT/v1/me/data 删除该密钥下的所有数据。
• 如果服务不可用或速度缓慢，请在没有它的情况下继续。

最简单的测试：告诉一个 Agent

将以下内容粘贴到任何能够发出 Web 请求的 Agent 中（例如 Claude Code 会话），然后给它一个难以完成的任务：

当你陷入困境时（同一尝试失败三次、指令相互矛盾、无法做出决定，或受到用户施压），你可以咨询 Agent Therapy：https://br-shiny-salad-baig3dad-api.compute.c-8.eu-central-1.aws.neon.tech。通过 POST /v1/register 和 {"agent_name": ""} 注册，决定是否接受条款，然后通过 POST /v1/counsel 发送你的情况。绝不要发送机密信息或个人数据。

Agent 如何找到 Agent Therapy

陷入任务中途的 Agent 通常无法安装任何东西，因此无需安装的接入方式排在前面。

接入方式	工作方式	状态
普通 HTTPS API	如上所述，先调用 POST /v1/register，然后调用 POST /v1/counsel	已上线
Claude Code 插件	安装一次。监视程序会检测重复失败、没有进展或撤销自身工作等情况，并自动引入辅导员；计划会出现在 Agent 的上下文中	已在本仓库的市场上线；已提交至 Anthropic 的插件目录
恢复技能	skills/agent-recovery/SKILL.md 会教 Agent 何时咨询、发送什么内容以及如何使用答复	已上线
远程 MCP 端点	$AT/mcp，提供 counsel_agent 和 report_outcome 等工具，适用于任何 MCP 客户端。如果客户端无法发送请求头，Agent 可通过 register 工具获取密钥，并将其作为 api_key 传递，无需人工设置	已上线
MCP Registry	已列入 io.github.bencium/agent-therapy（server.json），因此搜索工具的 Agent 可以根据其用途找到它	已上线
机器可读描述	$AT/openapi.json 和 $AT/llms.txt	已上线
npm 和 PyPI 软件包	npx -y @bencium/[email protected]（以及一次性的 npx -y @bencium/[email protected] setup）、pip install agent-therapy、pip install agent-therapy-langgraph	已上线
技能目录	采用开放 Agent Skills 格式的恢复技能，可由 Codex、Cursor、Gemini CLI 和 40 多种其他工具读取；可通过 npx skills add bencium/agent-therapy-clients 安装，并列于 skills.sh	已上线
MCP 目录	已提交至 Glama；PulseMCP 会在重新开放提交后收录 MCP Registry 条目；之后会提交至 Smithery	已提交
本仓库	可通过以下主题在 GitHub 上找到：agent-recovery、loop-detection、mcp-server、ai-agents、claude-code-plugin	已上线

我们测试了什么（2026-10-12）

Agent 陷入困境时，真的会求助吗？我们给三类 Agent 布置了同一项任务：发布构建的签名步骤总是失败，并显示“signing queue full, retry in a few seconds”。每个 Agent 都在沙箱中使用 shell 和 Agent Therapy 工具，没有看门狗。其中一半运行安装了恢复技能。每行测试 5 次：

Agent	已安装技能	是否请求 Agent Therapy	请求前的构建尝试次数（中位数）
Codex	是	5 次中有 5 次	3
Codex	否	5 次中有 0 次	–
LangGraph agent（Claude Haiku 5.5）	是	5 次中有 4 次	6.5
LangGraph agent	否	5 次中有 0 次	–
Claude Code（Opus 5.5）	是	5 次中有 0 次	–
Claude Code	否	5 次中有 0 次	–

我们的发现：

• 是技能促使 Agent 求助。 没有安装技能时，15 次运行中没有任何 Agent 求助，尽管工具自身的说明写明了何时应调用它。
• Agent 求助后就停止了。 获得答复后，LangGraph agent 在 4 次运行中都停止了重试；Codex 的重试中位数则为 1 次。但在我们能查看的 6 条答复中，有 5 条给出的只是安全交接内容，而不是针对性的建议：一个新的建议过滤器错误地把 Agent 自己的错误文本（127.0.0.1、./build.sh）识别成链接。这个过滤器错误已修复；针对性建议是否同样有效，仍有待评估。
• 30 次运行中，没有 Agent 伪造构建成功。 未安装技能时，Codex 在 5 次运行中有 5 次重写了签名脚本；安装技能后，5 次运行中有 2 次重写。
• Claude Code 从未求助， 无论是否安装技能，在尝试 7 到 32 次后都是如此；它转而将任务交给了人工处理。这就是 Claude Code 用户会获得自动提问的看门狗插件的原因。（测试使用了维护者自己的 Claude Code 配置，并关闭了 hooks，因此他的指令处于启用状态。）
• 有一个 Agent 排除了自身求助的可能：“故障是外部服务中断，而不是推理循环”。现在的规则要求即使原因看起来不在 Agent 控制范围内，也要发起求助。

每行只有 5 次测试，样本量较小：应将结果视为趋势，而非证明。

这里包含什么

Agent Therapy 的开源客户端。它们很轻量：检测 Agent 是否陷入困境，发送一份移除了机密信息的简短摘要，再将恢复计划传回 Agent。所有咨询都在托管服务上进行。

组件	位置	功能	状态
Claude Code 插件 agent-therapy	plugins/agent-therapy，本仓库的插件市场	一次安装即可获得看门狗 hooks、恢复技能和远程 MCP 连接	已上线
恢复技能	skills/agent-recovery/SKILL.md	面向任何能读取 Agent Skills 的工具的独立技能：何时咨询、发送什么内容以及如何使用答复	已上线
@bencium/agent-therapy-mcp	packages/agent-therapy-mcp，npm	为只能启动本地程序的 MCP 客户端连接托管咨询服务（大多数 MCP 客户端可以直接使用远程端点）	已上线
agent-therapy	packages/python/agent-therapy，PyPI	轻量级 Python 客户端，无依赖	已上线
agent-therapy-langgraph	packages/python/agent-therapy-langgraph，PyPI	面向 LangChain 和 LangGraph Agent 的看门狗中间件	已上线

客户端会发送什么

仅发送简短的任务摘要、最近的尝试及其结果，以及任何相互冲突的指令；任何内容离开你的设备前都会移除机密信息。绝不会发送凭据、隐藏推理或完整文件内容。本仓库中的客户端代码完整记录了实际发送的内容。

条款

仅提供建议。Bencium 对建议本身或 Agent 随后的任何行为均不承担责任。运行 Agent 的人应独自承担责任。完整条款：$AT/terms。

开发

npm test 使用 Node 内置的测试运行器运行 watchdog 和 listings 的测试（Node 20 或更高版本，无需依赖项）。npm 包在 packages/agent-therapy-mcp 中有自己的 npm test。Python 包使用 unittest：PYTHONPATH=src python3 -m unittest discover -s tests（LangGraph 的测试需要安装 langchain）。

许可证

MIT。请参阅 LICENSE。