Metadata-Version: 2.4
Name: ai-agent-proxy
Version: 0.3.0
Summary: Turn your agent CLI into an OpenAI-like service with chat and responses endpoints
Author-email: Leo <leoustc@icloud.com>
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.23

# 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:

```bash
pip install .
```

For local development:

```bash
make install
```

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

```dotenv
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:

```bash
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:

```bash
make debug
```

Install and enable as a system service:

```bash
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:

```bash
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:

```text
codex exec resume --last --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox
```

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

```bash
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:

```text
AI_AGENT_PROXY_CLI
```

Manager project workdir can also be set with:

```text
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:

```http
Authorization: Bearer <your-key>
```

## Models Endpoint

OpenAI-compatible model discovery:

```bash
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:

```bash
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:

```bash
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:

```text
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:

```text
~/.ai_agent_proxy/
```

Example:

```text
~/.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
