Agentica server + Claude proxy setup - architecture, startup sequence, debugging

Agentica Server + Claude Proxy Setup Complete reference for running Agentica SDK with a local Claude proxy. This enables Python agents to use Claude CLI as their inference backend. 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 Architecture Environment Variables Variable Set By Used By Purpose INFERENCE ENDPOINT URL Human agentica server Where server sends LLM inference requests S M BASE URL Human Agentica SDK client Where SDK connects to session manager KEY: These are NOT the same endpoint! SDK connects to server (port 2345) Server connects to proxy (port 8080) Startup Sequence Must start in this order (each in a separate terminal): Terminal 1: Claude Proxy Terminal 2: Agentica Server MUST run from its directory: Terminal 3: Your Agent Script Health Checks Common Errors & Fixes 1. APIConnectionError after agent spawn 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: 2. ModuleNotFoundError for agentica server 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. 3. Agent can't use Read/Write/Edit tools 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: 4. Agent claims success but didn't do task 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: 5. Timeout on 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. Key Files File Purpose 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 Quick Verification Test the full stack: 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

agentica-server