agentica-server
starsforks
How to install agentica-server?
vibeeval/vibecosystem/agentica-server
$npx -y skills add vibeeval/vibecosystem --skill agentica-server--- name: agentica-server description: Agentica server + Claude proxy setup - architecture, startup sequence, debugging allowed-tools: [Bash, Read] user-invocable: false ---
SKILL.md
| 1 | # Agentica Server + Claude Proxy Setup |
| 2 | |
| 3 | Complete reference for running Agentica SDK with a local Claude proxy. This enables Python agents to use Claude CLI as their inference backend. |
| 4 | |
| 5 | ## When to Use |
| 6 | |
| 7 | Use this skill when: |
| 8 | - Starting Agentica development with Claude proxy |
| 9 | - Debugging connection issues between SDK, server, and proxy |
| 10 | - Setting up a fresh Agentica environment |
| 11 | - Troubleshooting agent tool access or hallucination issues |
| 12 | |
| 13 | ## Architecture |
| 14 | |
| 15 | ``` |
| 16 | Agentica SDK (client code) |
| 17 | | S_M_BASE_URL=http://localhost:2345 |
| 18 | v |
| 19 | ClientSessionManager |
| 20 | | |
| 21 | v |
| 22 | Agentica Server (agentica-server) |
| 23 | | INFERENCE_ENDPOINT_URL=http://localhost:8080/v1/chat/completions |
| 24 | v |
| 25 | Claude Proxy (claude_proxy.py) |
| 26 | | |
| 27 | v |
| 28 | Claude CLI (claude -p) |
| 29 | ``` |
| 30 | |
| 31 | ## Environment Variables |
| 32 | |
| 33 | | Variable | Set By | Used By | Purpose | |
| 34 | |----------|--------|---------|---------| |
| 35 | | `INFERENCE_ENDPOINT_URL` | Human | agentica-server | Where server sends LLM inference requests | |
| 36 | | `S_M_BASE_URL` | Human | Agentica SDK client | Where SDK connects to session manager | |
| 37 | |
| 38 | **KEY:** These are NOT the same endpoint! |
| 39 | - SDK connects to server (port 2345) |
| 40 | - Server connects to proxy (port 8080) |
| 41 | |
| 42 | ## Startup Sequence |
| 43 | |
| 44 | Must start in this order (each in a separate terminal): |
| 45 | |
| 46 | ### Terminal 1: Claude Proxy |
| 47 | |
| 48 | ```bash |
| 49 | uv run python scripts/agentica/claude_proxy.py --port 8080 |
| 50 | ``` |
| 51 | |
| 52 | ### Terminal 2: Agentica Server |
| 53 | |
| 54 | **MUST run from its directory:** |
| 55 | |
| 56 | ```bash |
| 57 | cd workspace/agentica-research/agentica-server |
| 58 | INFERENCE_ENDPOINT_URL=http://localhost:8080/v1/chat/completions uv run agentica-server --port 2345 |
| 59 | ``` |
| 60 | |
| 61 | ### Terminal 3: Your Agent Script |
| 62 | |
| 63 | ```bash |
| 64 | S_M_BASE_URL=http://localhost:2345 uv run python scripts/agentica/your_script.py |
| 65 | ``` |
| 66 | |
| 67 | ## Health Checks |
| 68 | |
| 69 | ```bash |
| 70 | # Claude proxy health |
| 71 | curl http://localhost:8080/health |
| 72 | |
| 73 | # Agentica server health |
| 74 | curl http://localhost:2345/health |
| 75 | ``` |
| 76 | |
| 77 | ## Common Errors & Fixes |
| 78 | |
| 79 | ### 1. APIConnectionError after agent spawn |
| 80 | |
| 81 | **Symptom:** Agent spawns successfully but fails on first call with connection error. |
| 82 | |
| 83 | **Cause:** Claude proxy returning plain JSON instead of SSE format. |
| 84 | |
| 85 | **Fix:** Proxy must return Server-Sent Events format: |
| 86 | ``` |
| 87 | data: {"choices": [...]}\n\n |
| 88 | ``` |
| 89 | |
| 90 | ### 2. ModuleNotFoundError for agentica-server |
| 91 | |
| 92 | **Symptom:** `ModuleNotFoundError: No module named 'agentica_server'` |
| 93 | |
| 94 | **Cause:** Running `uv run agentica-server` from wrong directory. |
| 95 | |
| 96 | **Fix:** Must `cd workspace/agentica-research/agentica-server` first. |
| 97 | |
| 98 | ### 3. Agent can't use Read/Write/Edit tools |
| 99 | |
| 100 | **Symptom:** Agent asks for file contents instead of reading them. |
| 101 | |
| 102 | **Cause:** Missing `--allowedTools` in claude_proxy.py CLI call. |
| 103 | |
| 104 | **Fix:** Proxy must pass tool permissions: |
| 105 | ```bash |
| 106 | claude -p ... --allowedTools Read Write Edit Bash |
| 107 | ``` |
| 108 | |
| 109 | ### 4. Agent claims success but didn't do task |
| 110 | |
| 111 | **Symptom:** Agent says "I've created the file" but file doesn't exist. |
| 112 | |
| 113 | **Cause:** Hallucination - agent describing intended actions without executing. |
| 114 | |
| 115 | **Fix:** Added emphatic anti-hallucination prompt in REPL_BASELINE: |
| 116 | ``` |
| 117 | CRITICAL: Use ACTUAL tools. Never DESCRIBE using tools. |
| 118 | ``` |
| 119 | |
| 120 | ### 5. Timeout on agent.call() |
| 121 | |
| 122 | **Symptom:** Call hangs for 30+ seconds then times out. |
| 123 | |
| 124 | **Cause:** Claude CLI taking too long or stuck in a loop. |
| 125 | |
| 126 | **Fix:** Check proxy logs for the actual CLI output. May need to simplify prompt. |
| 127 | |
| 128 | ## Key Files |
| 129 | |
| 130 | | File | Purpose | |
| 131 | |------|---------| |
| 132 | | `scripts/agentica/claude_proxy.py` | OpenAI-compatible proxy with SSE streaming | |
| 133 | | `workspace/agentica-research/agentica-server/` | Local agentica-server installation | |
| 134 | | `scripts/agentica/PATTERNS.md` | Multi-agent pattern documentation | |
| 135 | |
| 136 | ## Quick Verification |
| 137 | |
| 138 | Test the full stack: |
| 139 | |
| 140 | ```bash |
| 141 | # 1. Verify proxy responds |
| 142 | curl http://localhost:8080/health |
| 143 | |
| 144 | # 2. Verify server responds |
| 145 | curl http://localhost:2345/health |
| 146 | |
| 147 | # 3. Test inference through proxy |
| 148 | curl http://localhost:8080/v1/chat/completions \ |
| 149 | -H "Content-Type: application/json" \ |
| 150 | -d '{"model":"claude","messages":[{"role":"user","content":"Say hello"}]}' |
| 151 | ``` |
| 152 | |
| 153 | ## Checklist |
| 154 | |
| 155 | Before running agents: |
| 156 | - [ ] Claude proxy running on port 8080 |
| 157 | - [ ] Agentica server running on port 2345 (from its directory) |
| 158 | - [ ] `S_M_BASE_URL` set for client scripts |
| 159 | - [ ] `INFERENCE_ENDPOINT_URL` set for server |
| 160 | - [ ] Both health checks return 200 |
People who liked this also viewed
6 picksType
- microsoft-foundryDeploy, evaluate, fine-tune, and manage Foundry agents end-to-end with azd: hosted agent scaffold/run/deploy, prompt agent create, batch eval, continuous eval, prompt optimizer, Agent Optimizer scaffoSkillsJul 2026
- azure-deployExecute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application SkillsJul 2026
- azure-preparePrepare azd-based Azure projects for deployment: generates azure.yaml, infrastructure (Bicep/Terraform), and Dockerfiles for the Azure Developer CLI (azd) workflow. USE ONLY when the user explicitly wSkillsJul 2026
- azure-validate--- name: azure-validate description: "Pre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), RBAC role assignments, managed identity pSkillsJul 2026
- azure-aigatewayConfigure Azure API Management as an AI Gateway for AI models, MCP tools, and agents. WHEN: semantic caching, token limit, content safety, load balancing, AI model governance, MCP rate limiting, jailbSkillsJul 2026
- azure-hosted-copilot-sdkOfficial agent plugin providing skills and MCP server configurations for Azure scenarios.SkillsJul 2026
