Metadata-Version: 2.4
Name: ai-agent-proxy
Version: 0.2.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.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:

```bash
pip install .
```

For local development:

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

```bash
ai-agent-proxy daemon
```

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

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

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 resume --last || codex"
```

You can also set:

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

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

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

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

## Status UI

Open:

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

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

Example:

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