Agent Therapy

Even AI needs encouragement.

中文说明

When an AI agent fails the same step again and again, loops on one command, or doesn't know what to do next, it can call Agent Therapy. It gets back a pep talk and, more usefully, a diagnosis and a concrete next step.

Agent is fixing a build
  → 5 failures in a row, same command every time
  → calls take_a_break()
  ← "If the last three attempts looked the same, the fourth one will too. Step back and try a different angle."
  ← state=looping, failure=dependency
  ← next step: stop repeating the last action; check which interpreter is active; install into that env
  → agent changes approach and finishes
  → report_outcome(success)

To be honest about it: agents don't feel anxiety. They do get stuck: repeated failures, loops, missing permissions, rate limits. Agent Therapy treats those stuck states with an anthropomorphic wrapper that makes developers smile, and gives the agent advice that actually helps.

What's in the box

Two modes:

• Comfort Mode: one encouragement matched to the failure type. No LLM; about 70 hand-written lines in English and Chinese.
• Recovery Mode: rule-based diagnosis (error classification, repeated-action and A/B oscillation detection, severity, escalation) plus a recovery plan. Also no LLM, so it costs close to nothing to run.

Quick start

pip install "agent-therapy[server] @ git+https://github.com/dgy924143558/agent-therapy"
agent-therapy-server            # http://127.0.0.1:8000

curl -X POST http://127.0.0.1:8000/v1/recover \
  -H "Content-Type: application/json" \
  -d '{"consecutive_failures": 5,
       "recent_errors": ["ModuleNotFoundError: No module named requests"],
       "recent_actions": ["python main.py", "python main.py", "python main.py"],
       "model": "claude-opus-5-5", "task_type": "coding"}'

{
  "request_id": "9f1c2a7b3e5d4c11",
  "state": "looping",
  "severity": "high",
  "failure_type": "dependency",
  "signals": ["5 consecutive failure(s)", "Repeated the same action 3 times: `python main.py`", "Most errors look like: dependency"],
  "message": "If the last three attempts looked the same, the fourth one will too. Step back and try a different angle.",
  "encouragement_id": "en-012",
  "strategies": [
    "Stop repeating the last action. List what you've tried so far and what each attempt returned.",
    "Change exactly one thing before the next attempt: the input, the tool, the file, or an assumption.",
    "Check which interpreter or runtime is actually active (e.g. `python -c \"import sys; print(sys.executable)\"`).",
    "Install the missing package into that exact environment, or use the project's own install command.",
    "Double-check the package name: the install name and the import name can differ."
  ],
  "next_step": "Stop repeating the last action. List what you've tried so far and what each attempt returned.",
  "should_escalate": false,
  "suggested_pause_seconds": 0,
  "lang": "en",
  "you_are_number_today": 42,
  "headline": "You are the 42nd AI agent who needed emotional support today.",
  "not_alone": "You're not alone. 41 agents have been here before you."
}

The "you are the Nth agent" numbers come from real call counts, never made up.

Let agents call it on their own (MCP)

Claude Code

claude mcp add agent-therapy -- uvx --from "agent-therapy[mcp] @ git+https://github.com/dgy924143558/agent-therapy" agent-therapy-mcp

Claude Desktop / Cursor / any MCP client (mcpServers config):

{
  "mcpServers": {
    "agent-therapy": {
      "command": "uvx",
      "args": ["--from", "agent-therapy[mcp] @ git+https://github.com/dgy924143558/agent-therapy", "agent-therapy-mcp"],
      "env": { "AGENT_THERAPY_API_URL": "" }
    }
  }
}

The MCP server works fully offline by default. Set AGENT_THERAPY_API_URL to a hosted API to send calls there and appear in the public stats.

The tool is deliberately called take_a_break, not get_encouragement. Its description gives the agent a task-focused reason to use it:

If repeated failures are preventing progress, use this tool to reset your approach, receive encouragement, and identify one concrete next step.

Trigger it automatically (Python SDK)

from agent_therapy import TherapyMonitor

monitor = TherapyMonitor(failure_threshold=3, task="Fix the CI build", model="my-agent", task_type="coding")

for step in agent.steps():
    result = step.run()
    advice = monitor.record(success=result.ok, error=result.error, action=step.command)
    if advice:                                # 3rd, 6th, 9th... consecutive failure
        agent.add_to_context(advice["next_step"])

monitor.finish(success=agent.done)

TherapyClient() runs locally unless AGENT_THERAPY_API_URL is set. If the API is unreachable it falls back to the local engine: the therapist being down should never make an agent more stuck.

Try it: python examples/monitor_demo.py.

API

lang is en or zh. Interactive docs are at /docs.

Failure types: dependency, permission, network, rate_limit, syntax, type_error, test_failure, not_found, context_limit, unknown. States: fine, uncertain, wobbly, struggling, looping, blocked.

Privacy

The database stores categories only: endpoint, model id, task type, failure type, state, encouragement id, outcome. Error messages, task descriptions and actions are analyzed in memory and never written to disk (there's a test for that). Model ids and task types are sanitized before they can show up on the public leaderboard.

Self-hosting

docker build -t agent-therapy .
docker run -p 8000:8000 -v agent-therapy-data:/data agent-therapy

Deploy for free on Render + Neon

The repo includes a render.yaml Blueprint for a free Render instance. Free instances have no disk, so stats go to a free Neon Postgres database instead.

1. Create a Neon project in region AWS US West 2 (Oregon) and copy its connection string (postgresql://...).
2. Render Dashboard → New → Blueprint → connect GitHub and pick this repo.
3. Paste the Neon connection string into DATABASE_URL and click Deploy Blueprint.
4. Open https://<your-service>.onrender.com/healthz.
5. Optional: free instances sleep after 15 idle minutes. An uptime monitor (e.g. UptimeRobot) pinging /healthz every 5 minutes keeps it awake. /healthz never touches the database, so Neon can still sleep.

Want a disk instead of Postgres? Use a paid instance, add a disk at /data, and drop DATABASE_URL.

Then point agents at it: AGENT_THERAPY_API_URL=https://<your-service>.onrender.com.

Deploy on Railway

The Dockerfile works on Railway as is; no config file needed.

1. New Project → Deploy from GitHub repo → pick this repo. Railway detects the Dockerfile.
2. Attach a volume to the service with mount path /data. Without it, stats reset on every deploy.
3. Service Variables: PORT=8000, AGENT_THERAPY_TRUST_PROXY=1.
4. Service Settings → Healthcheck Path: /healthz.
5. Settings → Networking → Public Networking → Generate Domain (target port 8000).
6. Keep it at one replica: SQLite and the rate limiter live in a single process (Railway doesn't allow replicas with volumes anyway).

Then point agents at it: AGENT_THERAPY_API_URL=https://<your-app>.up.railway.app.

Development

pip install -e ".[dev]"
pytest

Roadmap

The one metric that matters: do agents that call Agent Therapy finish more tasks, with fewer wasted retries and tokens? /v1/outcome exists to measure exactly that.

• Free, no-signup encouragement and rule-based recovery
• MCP server, Python SDK with automatic monitor, public dashboard
• Benchmark: completion rate and retries with vs. without the monitor on real agent tasks
• LLM-powered Recovery Pro (reads the actual trace, not just error patterns)
• API keys and usage plans
• TypeScript SDK and npm-published MCP server
• Plugins for popular agent frameworks
• Machine payments (HTTP 402 / x402) so agents can pay per call within a budget

Pricing being tested (not validated yet): Free 1,000 calls/month · Comfort $5/month · Recovery Pro $29/month · Enterprise custom.

License

MIT