agentica-server - SKILL.md Agent Skill

name: agentica-server

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

allowed-tools: [Bash, Read]

user-invocable: false

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

|----------|--------|---------|---------|

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_URL set for client scripts
INFERENCE_ENDPOINT_URL set for server
Both health checks return 200