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