ai-agent-proxy 0.2.0

Turn your agent CLI into an OpenAI-like service with chat and responses endpoints

AI Agent Proxy

ai-agent-proxy is a Python package that turns your agent CLI into an OpenAI-like HTTP service.

Current release: 0.2.0

It exposes both:

• the traditional chat endpoint: POST /v1/chat/completions
• the Responses API endpoint: POST /v1/responses

It also includes:

• the ai-agent-proxy CLI
• a FastAPI server with a status dashboard at GET / and GET /web
• persistent local agent workspaces
• automatic startup of the manager agent

What It Does

ai-agent-proxy runs your local agent backend behind an API shape that OpenAI-style clients can use.

You can use it to:

• point chatbot clients at an OpenAI-compatible URL
• expose a manager-backed assistant to Mattermost, Slack, or browser clients
• keep agent state in persistent local workspaces under ~/.ai_agent_proxy
• run a simple manager-first service without changing your core CLI workflow

Endpoints

The service supports:

• GET /
• GET /web
• GET /health
• POST /v1/chat/completions
• POST /v1/responses
• POST /agent-reply

GET / and GET /web show the service status dashboard.

Installation

From source:

pip install .

For local development:

make install

CLI

Main commands:

• ai-agent-proxy enable
• ai-agent-proxy restart
• ai-agent-proxy init <role>
• ai-agent-proxy hire <role> <name>
• ai-agent-proxy list
• ai-agent-proxy status
• ai-agent-proxy connect <agent> [working_dir]
• ai-agent-proxy stop <role>

The service command is:

ai-agent-proxy daemon

Start The Service

Run from source:

make debug

Install and enable as a system service:

ai-agent-proxy enable --ip 0.0.0.0 --port 7011
ai-agent-proxy restart

enable also initializes the manager workspace immediately. The daemon then starts the manager agent automatically. The manager agent uses ~/.openclaw/workspace as its default project working directory.

To create or reuse a named agent:

ai-agent-proxy hire engineer alice

When you use connect, the agent still runs from its own workspace under ~/.ai_agent_proxy/.... The optional working_dir argument is task context only.

Agent CLI Selection

By default the service uses:

codex

You can override the underlying agent CLI command with --cli:

ai-agent-proxy enable --ip 0.0.0.0 --port 7011 --api-key YOUR_KEY --cli "codex resume --last || codex"

You can also set:

AI_AGENT_PROXY_CLI

Current behavior:

• --cli controls which underlying CLI executable is used for managed agent turns
• the default is codex
• the value is carried through service install, daemon startup, and managed session startup
• managed agent turns are executed as codex exec resume --last --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox <prompt>
• if there is no resumable session, configure --cli "codex resume --last || codex" only for future tmux-style interactive startup work, not for the current request/response session path
• managed Codex sessions run without the read-only sandbox and without approval prompts

Authentication

If AI_AGENT_PROXY_API_KEY is set, API requests must send:

Authorization: Bearer <your-key>

Traditional Endpoint

OpenAI-compatible chat completions:

curl http://127.0.0.1:7011/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "manager",
    "messages": [
      {"role": "user", "content": "hello"}
    ]
  }'

Responses Endpoint

OpenAI Responses API style:

curl http://127.0.0.1:7011/v1/responses \
  -H 'Authorization: Bearer YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "manager",
    "input": "hello",
    "stream": false
  }'

Status UI

Open:

http://127.0.0.1:7011/web

This page shows service status, agent count, agent names, and health. It also tells clients to use the API with an API key when auth is enabled.

Workspace Layout

Agent state is stored under:

~/.ai_agent_proxy/

Example:

~/.ai_agent_proxy/manager/
~/.ai_agent_proxy/engineer_alice/

Each workspace can include role instructions, memory, notes, control files, and logs. The manager's default project working directory is separate from its workspace and lives at ~/.openclaw/workspace.

Notes

• the Python import package is ai_agent_proxy
• the CLI command is ai-agent-proxy
• the default systemd unit name is ai-agent-proxy.service
• the API is manager-first: inbound requests are routed through the manager agent