ai-agent-proxy 0.3.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.3.0

It exposes both:

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

By default, both endpoints return OpenAI-style JSON and source assistant content only from a local reply file written by the managed agent and terminated with END_OF_REPLY. For long-running tasks, the agent may first write a short interim status reply terminated with END_OF_REPLY, and then continue working in its managed session.

For OpenClaw-style integrations, prefer POST /v1/chat/completions.

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
• relay final agent replies through local reply files instead of raw terminal transcript
• return OpenAI-style response bodies without exposing raw Codex session output

Endpoints

The service supports:

• GET /
• GET /web
• GET /health
• GET /v1/models
• GET /v1/models/{model}
• POST /v1/chat/completions
• POST /v1/responses

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

Installation

From source:

pip install .

For local development:

make install

Local make configuration can be stored in .env, for example:

API_KEY=your-api-key

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

ai-agent-proxy list shows initialized agent workspaces only. Internal service directories are not listed as agents.

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 --workdir ~/.openclaw/workspace
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 both its workspace and its default project working directory. You can override that with --workdir or AI_AGENT_PROXY_WORKDIR. If that manager workspace already contains AGENTS.md, SOUL.md, TOOLS.md, USER.md, HEARTBEAT.md, and memory/, the bundled manager templates are not copied into it.

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 exec resume --last --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox

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 exec resume --last --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox"

You can also set:

AI_AGENT_PROXY_CLI

Manager project workdir can also be set with:

AI_AGENT_PROXY_WORKDIR

Current behavior:

• --cli controls which underlying CLI executable is used for managed agent turns
• the default is codex exec resume --last --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox
• the value is carried through service install, daemon startup, and managed session startup
• managed agent turns execute the configured CLI command with the prompt appended as the final argument
• 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>

Models Endpoint

OpenAI-compatible model discovery:

curl http://127.0.0.1:7011/v1/models \
  -H 'Authorization: Bearer YOUR_KEY'

The models list includes:

• manager
• each initialized local agent directory name, such as engineer_alice

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"}
    ]
  }'

The returned choices[0].message.content is built only from the reply file content before END_OF_REPLY.

This is the recommended endpoint for OpenClaw-style clients.

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
  }'

The returned output and output_text fields are built only from the reply file content before END_OF_REPLY.

Use this when your client explicitly supports the OpenAI Responses API well. For OpenClaw-style integrations, prefer POST /v1/chat/completions.

Status UI

Open:

http://127.0.0.1:7011/web

This page shows service status, agent count, agent names, and health. Agents marked working are actively handling a prompt in their managed session. 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:

~/.openclaw/workspace/
~/.ai_agent_proxy/engineer_alice/

Each workspace can include role instructions, memory, notes, control files, and logs. For the manager, that workspace is ~/.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