返回资讯中心
外部精选
软件工程
#开发者实时流

Agent-bridge – an OpenAI-compatible API for headless coding-agent CLIs

agent-bridge is an HTTP server written in Go that exposes an OpenAI-compatible

Hacker News 最新paolorusso2026/10/18 · 2026/10/1830 分钟阅读

以下正文同步自 Hacker News 最新,版权归原站所有,已转换为易读排版。

agent-bridge is an HTTP server written in Go that exposes an OpenAI-compatible API (/v1/chat/completions, /v1/models) and fulfils every request by running the official Claude Code CLI in headless mode (claude -p --output-format stream-json).

It can also run the OpenAI Codex CLI (codex exec --json) or the Kimi Code CLI (kimi acp, over the Agent Client Protocol) instead, with the same API: see the Codex backend and the Kimi backend.

Any client or framework that speaks OpenAI can use it by changing only base_url, api_key and model: chat, streaming, function calling (tool calling) and image input work with the official SDKs unchanged.

In short: an OpenAI-compatible API server, proxy and gateway for Claude Code. It lets OpenAI-based multi-agent systems, ReAct orchestrators and frameworks that accept a custom OpenAI base_url (for example LangChain, LlamaIndex, CrewAI, AutoGen or the OpenAI SDKs for Python, Node and Go) use Claude Code headless as a drop-in chat completions model or as a coding agent, with tool calling, MCP servers, sessions, streaming (SSE) and per-agent models. The same server is an OpenAI-compatible API, proxy and gateway for the OpenAI Codex CLI and for the Kimi Code CLI (Moonshot AI, Kimi K2), and an ACP (Agent Client Protocol) client.

Independent project. agent-bridge is not developed, endorsed or supported by Anthropic. It runs the official claude binary installed on the machine, without modifying it, and never accesses its credentials.

As a model As an agent on the server

Who defines the agent Your client or platform: system, tools, model choice The bridge configuration file

Available tools Only the functions the client sends in tools, executed by the client CLI tools on the server machine (files, commands, search, MCP servers), plus any client functions

model bridge/opus, bridge/sonnet, bridge/haiku, bridge/<model name> The name of the configured agent

Configuration None JSON file

Section Using it as a model Agents on the server

"Tools" therefore come in two kinds, both supported:

Prerequisite: the claude CLI installed, version 2.1.128 or later, and one interactive login (claude).

go install github.com/r3n3r0/agent-bridge/cmd/agent-bridge@latest AGENT_BRIDGE_AUTH_MODE=subscription agent-bridge curl -s http://127.0.0.1:8787/v1/chat/completions
-d '{"model":"bridge/haiku","messages":[{"role":"user","content":"Hello!"}]}'

Without a configuration file the server listens on 127.0.0.1:8787 and accepts the models bridge/opus, bridge/sonnet, bridge/haiku and bridge/<model name> (the name after the prefix is passed to the CLI as is; the bridge/ prefix can be changed with builtin_prefix). They are chat-only models: no server tools, an empty temporary working directory, but they accept client functions and images.

Alternatively, download a binary from the releases page (archives and checksums.txt for every platform).

This is the scenario of a platform that already has its own agents, graph and lifecycle (for example a ReAct system): the bridge behaves like an OpenAI model and the agent is the one defined in the platform.

Two options make the bridge stateless and make the platform's agent the only agent. Set them in the configuration, or per request with a header:

Recommended configuration for this scenario:

{ "client_tools": { "mode": "stateless" }, "system_messages": "replace" }

In this scenario do not send X-Session-Id: every request starts a new process with the full history. It costs some latency per step, in exchange for no hidden state in the bridge.

Functions defined by the client with tools work as with the OpenAI API: the model answers with tool_calls and finish_reason: "tool_calls", the client runs the functions and sends the results back as role: "tool" messages, and the model continues. It also works when streaming (delta.tool_calls) and without session headers.

r = client.chat.completions.create(model="bridge/sonnet", messages=messages, tools=tools) while r.choices[0].finish_reason == "tool_calls": messages.append(r.choices[0].message) for call in r.choices[0].message.tool_calls: messages.append({"role": "tool", "tool_call_id": call.id, "content": run(call.function.name, call.function.arguments)}) r = client.chat.completions.create(model="bridge/sonnet", messages=messages, tools=tools)

Complete example: examples/python/tools.py.

Supported: tools (type function), tool_choice (auto, none, required, a specific function), parallel_tool_calls (parallel calls returned together) and the deprecated functions/function_call format.

How it works. Client functions are offered to the CLI as tools of a standard MCP server, served by the bridge itself (internal mcp-tools subcommand). When the model calls one, the bridge returns the call to the client. Then, depending on client_tools.mode:

Messages can contain image_url parts, as in the OpenAI API, with any model:

r = client.chat.completions.create(model="bridge/sonnet", messages=[{"role": "user", "content": [ {"type": "text", "text": "What is in this picture?"}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}, ]}])

Sources: data: URLs (base64) and http(s) URLs, which the bridge downloads. Downloads from non-public addresses (loopback, private networks, cloud metadata) are refused unless images.allow_private_networks is set; images.fetch_urls: false accepts only data: URLs.

Formats: PNG, JPEG, GIF, WebP, recognized from the content. Up to images.max_count images per request (default 20) and images.max_bytes each (default 5 MB); the whole input, images included, must stay within 9 MB.

How: images are sent to the CLI as image blocks of a structured message (--input-format stream-json); the text refers to them as [image 1], [image 2]… in order. Requests without images keep plain-text input.

In a resumed session only the images of the new messages are sent; earlier ones are already in the session. images.enabled: false rejects images with 400 unsupported_content.

Generation parameters

The bridge drives the CLI, not the model API directly, so it supports the OpenAI parameters the CLI can express, and emulates two more:

If response_format cannot be satisfied (the CLI gives up after its retries, or ends without structured output), the request fails with 502.

A JSON file maps a model name to an agent: model, system prompt, CLI tools, permissions and working directory. Use it when the agent must work on the server machine, for example on a repository.

{ "agents": { "reviewer": { "model": "opus", "system_prompt": "You are a strict reviewer. Do not modify files.", "allowed_tools": ["Read", "Grep", "Glob"], "cwd": "/srv/project" }, "coder": { "model": "sonnet", "allowed_tools": ["Read", "Edit", "Write", "Bash(go test *)"], "permission_mode": "acceptEdits", "cwd": "/srv/project" } } }

agent-bridge check-config -config agents.json # validate and print the resolved agents AGENT_BRIDGE_AUTH_MODE=subscription agent-bridge -config agents.json

The client picks the agent with the model field:

from openai import OpenAI client = OpenAI(base_url="http://127.0.0.1:8787/v1", api_key="unused") r = client.chat.completions.create( model="reviewer", messages=[{"role": "user", "content": "Review the error handling."}], extra_headers={"X-Session-Id": "review-42"}, ) print(r.choices[0].message.content)

An agent on the server can also receive client functions in tools: it will use both its own tools and those.

Full reference: docs/configuration.md. Annotated example: examples/agents.example.json.

Without X-Session-Id (OpenAI behavior): every request starts a new process; the history sent by the client is turned into a single prompt.

With X-Session-Id (or the user field): the same key resumes the CLI session with --resume, and the CLI receives only the new messages (user messages and tool results) after the assistant's last answer. Faster in long conversations. The key, generated when missing, is always returned in the X-Session-Id response header.

system messages are placed at the top of the prompt (system_messages: "prompt", default): in a resumed session only those of the first turn count. With append or replace they are passed as the system prompt and apply to every turn.

Answers to tool_calls in stateful mode resume the waiting process through the tool_call_ids, regardless of the session.

Development with a subscription, production with an API key

The mode is chosen only by configuration, with the mandatory AGENT_BRIDGE_AUTH_MODE variable:

The server refuses to start if the mode and the environment are inconsistent. In subscription mode the API key variables are removed from the child process environment anyway, and if the CLI reports using an API key the server logs an error on every turn.

Every turn records tokens and cost (logs, optional usage_log file, /stats, /metrics). In subscription mode cost_usd is an estimate computed by the CLI at API prices, not a charge: it helps forecast what production with an API key will cost.

compose.yaml runs the bridge with all three CLIs, one service per backend (ports 8787, 8788 and 8789 on the host's loopback), sharing one home volume for the CLIs' logins:

make up # creates .env with a random API key, builds, starts, prints the addresses make admin # opens the login page make smoke # one request to every service

make help lists the other targets (logs, doctor, terminal logins, update, reset). Without make: cp .env.example .env, set AGENT_BRIDGE_API_KEY, docker compose up -d.

Then log in to the CLIs from the admin page, http://127.0.0.1:8787/admin: it runs each CLI's official login flow on the server and shows its link and one-time code (or a box to paste the code back). The CLIs keep the credentials; the bridge never reads them. Details: docs/docker.md.

With backend: "codex" (or -backend codex, AGENT_BRIDGE_BACKEND=codex) every turn runs codex exec --json instead of the default CLI. The API, sessions, function calling, images, structured output and reasoning effort work the same way; built-in models become bridge/default (the model configured in Codex) and bridge/<model>; agents with tools use a sandbox (read-only, workspace-write, danger-full-access) instead of permission_mode and allowed_tools. Authentication: codex login in subscription mode, CODEX_API_KEY in api mode.

codex login AGENT_BRIDGE_AUTH_MODE=subscription agent-bridge -backend codex

Full mapping, agent fields and differences: docs/codex.md.

With backend: "kimi" (or -backend kimi, AGENT_BRIDGE_BACKEND=kimi) every turn runs kimi acp, the Kimi Code CLI as an Agent Client Protocol agent, with the bridge as the ACP client. The API, sessions, function calling, images, structured output and reasoning effort work the same way; built-in models become bridge/default (the default model of Kimi Code) and bridge/<model>; the bridge answers the CLI's permission requests from allowed_tools, disallowed_tools and permission_mode (default, plan, auto, yolo). Authentication: kimi login in subscription mode, KIMI_MODEL_NAME and KIMI_MODEL_API_KEY in api mode. ACP reports no token usage or cost.

kimi login --region global # kimi.ai; mainland-cn for kimi.com AGENT_BRIDGE_AUTH_MODE=subscription agent-bridge -backend kimi

Full mapping, agent fields and differences: docs/kimi.md.

agent-bridge is a tool: whoever uses it remains responsible for complying with the terms of their plan. In short:

References, to be checked again because the rules may change:

An agent on the server with tools enabled can read, write and run commands: whoever reaches the server has the equivalent of a restricted shell. Defaults are closed and every opening is explicit.

Response headers: X-Session-Id, X-Request-Id and, in non-stream responses, X-Agent-Bridge-Turns, X-Agent-Bridge-Cost-USD, X-Agent-Bridge-Duration-Ms.

Admin page (with admin: true or AGENT_BRIDGE_ADMIN=1): GET /admin and /admin/api/logins to log in to the CLIs (docs/docker.md).

Commands: agent-bridge serve (def

正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。

打开原文
去社区讨论 →