agentica-server
Agentica server + Claude proxy setup - architecture, startup sequence, debugging
- License 许可
- MIT
- 最近更新
- 2026-06-09
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- agentica-server
- description
- Agentica server + Claude proxy setup - architecture, startup sequence, debugging
- allowed-tools
- [ "Bash", "Read" ]
- user-invocable
- false
03 SKILL.md 正文
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
Agentica SDK (client code)
| S_M_BASE_URL=http://localhost:2345
v
ClientSessionManager
|
v
Agentica Server (agentica-server)
| INFERENCE_ENDPOINT_URL=http://localhost:8080/v1/chat/completions
v
Claude Proxy (claude_proxy.py)
|
v
Claude CLI (claude -p)
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
uv run python scripts/agentica/claude_proxy.py --port 8080
Terminal 2: Agentica Server
MUST run from its directory:
cd workspace/agentica-research/agentica-server
INFERENCE_ENDPOINT_URL=http://localhost:8080/v1/chat/completions uv run agentica-server --port 2345
Terminal 3: Your Agent Script
S_M_BASE_URL=http://localhost:2345 uv run python scripts/agentica/your_script.py
Health Checks
# Claude proxy health
curl http://localhost:8080/health
# Agentica server health
curl http://localhost:2345/health
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:
data: {"choices": [...]}\n\n
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:
claude -p ... --allowedTools Read Write Edit Bash
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:
CRITICAL: Use ACTUAL tools. Never DESCRIBE using tools.
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:
# 1. Verify proxy responds
curl http://localhost:8080/health
# 2. Verify server responds
curl http://localhost:2345/health
# 3. Test inference through proxy
curl http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"claude","messages":[{"role":"user","content":"Say hello"}]}'
Checklist
Before running agents:
- [ ] Claude proxy running on port 8080
- [ ] Agentica server running on port 2345 (from its directory)
- [ ]
S_M_BASE_URLset for client scripts - [ ]
INFERENCE_ENDPOINT_URLset for server - [ ] Both health checks return 200
04 同仓库更多 Skills
workflow-router
Goal-based workflow orchestration - routes tasks to specialist agents based on user goals
wiring
Wiring Verification
websocket-patterns
Connection management, room patterns, reconnection strategies, message buffering, and binary protocol design.
visual-verdict
Screenshot comparison QA for frontend development. Takes a screenshot of the current implementation, scores it across multiple visual dimensions, and returns a structured PASS/REVISE/FAIL verdict with concrete fixes. Use when implementing UI from a design reference or verifying visual correctness.
verification-loop
Comprehensive verification system covering build, types, lint, tests, security, and diff review before a PR.
vector-db-patterns
Embedding strategies, ANN algorithms, hybrid search, RAG chunking strategies, and reranking for semantic search and retrieval.