{"id":"agentica-server","name":"agentica-server","summary":"Agenticaサーバー+Claudeプロキシの設定 - アーキテクチャ、起動シーケンス、デバッグ","body":"# Agentica Server + Claude Proxy Setup\n\nComplete reference for running Agentica SDK with a local Claude proxy. This enables Python agents to use Claude CLI as their inference backend.\n\n## When to Use\n\nUse this skill when:\n- Starting Agentica development with Claude proxy\n- Debugging connection issues between SDK, server, and proxy\n- Setting up a fresh Agentica environment\n- Troubleshooting agent tool access or hallucination issues\n\n## Architecture\n\n```\nAgentica SDK (client code)\n    | S_M_BASE_URL=http://localhost:2345\n    v\nClientSessionManager\n    |\n    v\nAgentica Server (agentica-server)\n    | INFERENCE_ENDPOINT_URL=http://localhost:8080/v1/chat/completions\n    v\nClaude Proxy (claude_proxy.py)\n    |\n    v\nClaude CLI (claude -p)\n```\n\n## Environment Variables\n\n| Variable | Set By | Used By | Purpose |\n|----------|--------|---------|---------|\n| `INFERENCE_ENDPOINT_URL` | Human | agentica-server | Where server sends LLM inference requests |\n| `S_M_BASE_URL` | Human | Agentica SDK client | Where SDK connects to session manager |\n\n**KEY:** These are NOT the same endpoint!\n- SDK connects to server (port 2345)\n- Server connects to proxy (port 8080)\n\n## Startup Sequence\n\nMust start in this order (each in a separate terminal):\n\n### Terminal 1: Claude Proxy\n\n```bash\nuv run python scripts/agentica/claude_proxy.py --port 8080\n```\n\n### Terminal 2: Agentica Server\n\n**MUST run from its directory:**\n\n```bash\ncd workspace/agentica-research/agentica-server\nINFERENCE_ENDPOINT_URL=http://localhost:8080/v1/chat/completions uv run agentica-server --port 2345\n```\n\n### Terminal 3: Your Agent Script\n\n```bash\nS_M_BASE_URL=http://localhost:2345 uv run python scripts/agentica/your_script.py\n```\n\n## Health Checks\n\n```bash\n# Claude proxy health\ncurl http://localhost:8080/health\n\n# Agentica server health\ncurl http://localhost:2345/health\n```\n\n## Common Errors & Fixes\n\n### 1. APIConnectionError after agent spawn\n\n**Symptom:** Agent spawns successfully but fails on first call with connection error.\n\n**Cause:** Claude proxy returning plain JSON instead of SSE format.\n\n**Fix:** Proxy must return Server-Sent Events format:\n```\ndata: {\"choices\": [...]}\\n\\n\n```\n\n### 2. ModuleNotFoundError for agentica-server\n\n**Symptom:** `ModuleNotFoundError: No module named 'agentica_server'`\n\n**Cause:** Running `uv run agentica-server` from wrong directory.\n\n**Fix:** Must `cd workspace/agentica-research/agentica-server` first.\n\n### 3. Agent can't use Read/Write/Edit tools\n\n**Symptom:** Agent asks for file contents instead of reading them.\n\n**Cause:** Missing `--allowedTools` in claude_proxy.py CLI call.\n\n**Fix:** Proxy must pass tool permissions:\n```bash\nclaude -p ... --allowedTools Read Write Edit Bash\n```\n\n### 4. Agent claims success but didn't do task\n\n**Symptom:** Agent says \"I've created the file\" but file doesn't exist.\n\n**Cause:** Hallucination - agent describing intended actions without executing.\n\n**Fix:** Added emphatic anti-hallucination prompt in REPL_BASELINE:\n```\nCRITICAL: Use ACTUAL tools. Never DESCRIBE using tools.\n```\n\n### 5. Timeout on agent.call()\n\n**Symptom:** Call hangs for 30+ seconds then times out.\n\n**Cause:** Claude CLI taking too long or stuck in a loop.\n\n**Fix:** Check proxy logs for the actual CLI output. May need to simplify prompt.\n\n## Key Files\n\n| File | Purpose |\n|------|---------|\n| `scripts/agentica/claude_proxy.py` | OpenAI-compatible proxy with SSE streaming |\n| `workspace/agentica-research/agentica-server/` | Local agentica-server installation |\n| `scripts/agentica/PATTERNS.md` | Multi-agent pattern documentation |\n\n## Quick Verification\n\nTest the full stack:\n\n```bash\n# 1. Verify proxy responds\ncurl http://localhost:8080/health\n\n# 2. Verify server responds\ncurl http://localhost:2345/health\n\n# 3. Test inference through proxy\ncurl http://localhost:8080/v1/chat/completions \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"claude\",\"messages\":[{\"role\":\"user\",\"content\":\"Say hello\"}]}'\n```\n\n## Checklist\n\nBefore running agents:\n- [ ] Claude proxy running on port 8080\n- [ ] Agentica server running on port 2345 (from its directory)\n- [ ] `S_M_BASE_URL` set for client scripts\n- [ ] `INFERENCE_ENDPOINT_URL` set for server\n- [ ] Both health checks return 200","author":"@parcadei","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/parcadei/Continuous-Claude-v3/tree/main/.claude/skills/agentica-server","license":"MIT","category":"coding","lang":"en","tokens":1066,"stars":0,"calls30d":1,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[],"requires":{"mcp":[],"tools":["Bash","Read"]},"safety":{"flags":[],"scannedAt":"2026-08-22","hasScripts":false,"networkEndpoints":[]}}