Open Agent API

开源 · 自托管 · Apache-2.0 · v0.0.70

Open Agent API

把智能体变成 API。

你调度的不是裸模型,而是自带工具、项目记忆与权限边界的完整智能体——一次调用,交付一个任务。原生兼容 OpenAI、Claude、Gemini 官方 SDK 与 MCP,业务代码只需换上 Base URL 和 API Key。

协议入口
OpenAI · Claude · Gemini · MCP
引擎与运行器预设
32+ CLI / ACP / 本地模型
自动化门禁
1,305 项跨三端 CI 测试
兼容性实验室
14 套 SDK · 456 项实连验证
点击截图可高清放大 · 明暗双主题视频按需加载
Open Agent API 控制台概览:左侧涵盖概览、对话工作台、智能体、工作流、连接与用量导航,右侧展示待审批任务、24 小时成功率、耗时分布与已发布智能体状态

两行接入

业务代码不用重写,换个地址就能调度智能体

沿用项目里现成的官方 SDK,把 base_url 指向你的网关、把 model 换成智能体调用名,原本的单轮补全就升级为带工具循环的完整任务。

Python · openai SDK
from openai import OpenAI client = OpenAI(    base_url="https://api.openai.com/v1",    api_key=OPENAI_API_KEY,    base_url="http://127.0.0.1:8787/v1",  # 指向你的本地或私有网关    api_key="sk-oaa-…",                   # 控制台签发的专属密钥) resp = client.chat.completions.create(    model="gpt-4.1",    model="agent/research",               # 填写智能体的调用名    messages=[{"role": "user", "content": "核对这三份供应商报价单并标出差异项"}],)print(resp.choices[0].message.content)
Node.js · openai SDK(Responses 多轮续接)
import OpenAI from 'openai'; const client = new OpenAI({  baseURL: 'https://api.openai.com/v1',  apiKey: process.env.OPENAI_API_KEY,  baseURL: 'http://127.0.0.1:8787/v1',    // 指向你的网关  apiKey: process.env.OAA_API_KEY,        // 控制台创建的密钥}); const resp = await client.responses.create({  model: 'gpt-4.1',  model: 'agent/coder@best',              // 支持 @fast / @best / @eco 选路  input: '跑一遍鉴权模块单测,定位偶发超时原因',});console.log(resp.output_text);

对调用方只暴露三个要素

服务地址(Base URL)、API 密钥与智能体调用名。在控制台签发密钥后,结果弹窗会将三项整齐列出,支持逐项复制或一键复制为环境变量。

model 字段填写的是 agent/research 这类智能体标识;底层走哪条模型线路、挂载哪些技能、允许读写哪个工作区目录,均在发布端统一配置。

  • 01 Base URL http://127.0.0.1:8787/v1
  • 02 API Key sk-oaa-…
  • 03 model agent/research
创建 API 密钥后的结果弹窗:展示网关 Base URL、一次性密钥与智能体调用名 agent/research,各项均有一键复制按钮
签发密钥后的就绪弹窗,直接粘贴进任意客户端或业务服务即可调用。

快速部署

选一种趁手的方式装上,一条命令跑通首调

所有安装路径最终都汇聚到 oaa quickstart:在本地 127.0.0.1:8787 启动网关、发布离线示例智能体并跑完第一次调用,全程无需预先配置云端模型密钥。

跨平台桌面应用

macOS · Windows · Linux

统一基于 Electron 安全沙箱外壳构建,内置 Node.js 24 运行时、控制台、实时审批角标与系统托盘快捷审批小窗。

Linux 一键安装

x64 · arm64 · 免 root

自动核验发布页同批次的 SHA256SUMS,自带独立运行时并安装至 ~/.local:

curl -fsSL https://github.com/jiangxingfan1-coder/Open-Agent-API/releases/latest/download/install.sh | sh

Docker 容器

amd64 · arm64 · 回环绑定

非 root 运行,状态持久化在 /data 卷且仅绑定宿主机回环端口,适合托管内置智能体与远程节点:

docker compose up --build -d

源码目录与 npm 包

Node.js 24 / 26

支持从发布页全局安装 .tgz 归档包,或在克隆仓库后一键启动离线快速体验:

npm run oaa -- quickstart

各平台安装包结构、首次打开未签名包的系统放行提示以及完整卸载步骤,见 安装指南。准备接入自有模型时,运行 oaa connect <预设> 即可一键连通主流云厂商或本地运行器。

核心机制

调度完整执行单元,而非转发单次补全

01

智能体状态机,而非无状态代理

分发的是封装好工具链、项目记忆、模型选路与权限边界的完整执行体。单次请求对应一个可追踪任务:包含多轮工具循环、流式思考进度与最高 256 MiB 的流式文件产物,支持幂等键、取消与断点恢复。

02

双层工具桥接与严格结构化契约

面向 OpenAI、Claude、Gemini 原生下推 JSON Schema 与 tool_choice 强制工具契约,输出失格自动触发修正轮。当调用方(如 Cursor、Cline 或业务服务)自带 tools 时,网关可通过 oaa-caller 将调用透明桥接回调用方执行。

03

持久化的「人在回路」检查点

涉及写文件或执行命令的操作会让任务精准停在「待审批」状态,而非转瞬即逝的弹窗。你在控制台、桌面托盘、CLI 或自有系统的签名 Webhook 里拍板后,同一个任务从挂起点接着往下跑。

交互演示 agent/coder POST /v1/responses · run_8f2a91c0
待审批
  1. 01

    读取工作区与鉴权模块变更

    定位 src/auth/login.ts 中的 3 处提示文案并生成单测草稿 · 120 ms

  2. 02

    检索项目记忆(SQLite FTS5)

    命中「错误码返回规范」与「鉴权测试隔离约定」2 条记忆条目 · 48 ms

  3. 03

    工具审批:npm test -- --run auth

    请求在工作区执行 shell.exec · 等待人工确认

  4. 04

    任务挂起在检查点,点击上方「批准并继续」或「拒绝」查看后续流转…

控制台任务检查器:代码智能体的任务停在待审批状态,清晰展开待执行命令详情与右下角的拒绝、批准按钮
控制台任务检查器实景:每一步工具输入、耗时时间线、审批上下文与输出产物均可随时回溯审查。

工作台与编排

从单次接口联调,到多智能体协同工作站

除了充当无头 API 网关,0.0.70 还内置了完整的交互调试台、双通道本机生态注入、跨智能体自动选路与持久化工作流引擎。

#workbench

交互对话与调试工作台

在控制台直接开展多轮续接会话(previous_response_id),支持传图、实时折叠展示思考进度、会话内直接审批、自定义 Schema 模拟外层桥接工具,并一键导出四协议 SDK 代码。

API + MCP

双通道本机客户端一键互联

自动检测本机工具链,支持向 OpenCode、Codex、DSH 注入自定义 API 提供方,或向 Cursor、Windsurf、Claude Desktop、Claude Code 一键配置 MCP 桥——统一引用 0600 私有密钥文件,零明文落盘且支持无损回滚。

Orchestration · FTS5

全引擎智能编排与记忆工作流

支持 @fast / @best / @eco 与 recommend 自动选路,通过 helpers 编排多智能体分工流水线并传递阶段产物;内置零依赖 SQLite FTS5 项目记忆检索,支持时区级 Cron 与入站 Webhook 触发器。

Desktop · Local LLM

三端沙箱桌面壳与本地模型发现

macOS、Windows 与 Linux 共享统一 Electron 安全沙箱桌面端,无需呼出主窗口即可在系统托盘小窗一键审批;自动扫描识别 Ollama、LM Studio、llama.cpp、vLLM 等 7 类本地运行器并发布为智能体。

生态连接

本机 CLI、本地模型与主流协议同席协作

无论是用 OAA-Lang 编写的内置智能体,还是机器上已装好的编程智能体,都能保留原有技能与登录态,统一映射为标准 API。

执行引擎与智能体

  • 内置内核智能体 OAA-Lang 2.5 或 JSON 定义;支持逐 Token 流式、持久审批、工具桥接与多路故障转移
  • Codex CLI 原生 app-server 通道;支持逐 Token 流式、oaa-caller 工具桥接、turn/interrupt 优雅中断与无工具规划
  • Claude Code 官方 Agent SDK 驱动;支持逐 Token 增量流式、运行中审批与调用方工具桥接
  • Antigravity 原生引擎与 agy acp 双路径;支持真实模型目录发现、工具桥接与 ACP 审批
  • ACP 智能体预设 内置 Qoder、OpenCode、Grok、DeepSeek Harness 等 32+ 预设,支持审批与工具桥接
  • 本地模型运行器 自动发现 Ollama、LM Studio、llama.cpp、Jan、LocalAI、vLLM,免改运行器配置直接发布
  • A2A 与自写适配器 支持 oaa/1(stdio / 流式 / HTTP)与 A2A 远程 contextId 续接,远程节点画像自动同步

调用协议与可观测性

  • OpenAI Chat & Responses 官方 SDK 常驻回归测试;支持流式思考进度、previous_response_id 续接、传图与原生 JSON Schema
  • Claude Messages 官方 Python 与 Node SDK 实连验证,完整支持工具桥接与结构化输出契约
  • Gemini 兼容 generateContent、流式 thought 进度块与原生 responseSchema 下推
  • MCP 双向上下文 供主流 IDE 发现并调度智能体;遵循最小权限设计,将审批放行权留在控制面
  • oaa/1 与事件回调 原生异步任务接口,配合 HMAC-SHA256 签名与持久重试队列的 HTTPS Webhook
  • 指标与全链路追踪 原生提供 Prometheus GET /metrics,跨委托全链路派生透传 W3C traceparent

各引擎在流式粒度、工具隔离与 POSIX 多槽位并发沙箱上的完整能力对照,见 接入外部智能体 与 双层 Harness 指南。

团队与分发

按需开启自助门户,向团队分发智能体服务

在控制台一键开启「开发者平台」,团队成员或外部调用方即可在独立门户自助注册、管理个人密钥,并按任务配额调用你上架的智能体。

  • 多租户隔离与自助密钥:每位开发者独立创建和吊销密钥,调用记录、文件产物与额度彼此严格隔离。
  • 启动预扣与混合计量:支持按次计点或叠加 Token 单价;任务开始时原子预扣,未完成自动退回,消除并发超支。
  • 外部引擎逐项审计开放:默认仅开放内置智能体;管理员可按条目显式授权 host_execution 并全程留存审计记录。
  • 纯粹配额核算与防枚举保护:门户限流状态持久化至 SQLite 并支持异步验证回调;点数专注内部配额记账,与外部收银及邮件系统保持清晰解耦。
开发者门户首页:展示调用地址、上架智能体目录与面向调用方的自助接入指引
独立开发者门户视图:按需开启,与管理控制台共享同一套设计语言。

工程基线

实测验证与架构取舍

用可复现的自动化门禁与真机验收记录说明当前能力基线,同时保持克制、透明的系统边界。

已验证的工程基线

  • 1,305 项跨平台自动化测试:在 Linux、macOS 与 Windows(Node.js 24 与 26)CI 持续运行,配合单向架构分层守卫与零 any 类型门禁。
  • 兼容性实验室实连回归:14 套官方 Python / Node SDK 与主流框架(Vercel AI SDK、LangChain、LlamaIndex、OpenAI Agents 等)实连网关跑通 456 个场景,并覆盖 12 款客户端请求回放。
  • 多引擎真机端到端验收:已在隔离环境实测通过 Qoder CLI(oaa verify 全 11 场景与平台计费闭环)、Antigravity 1.5.10(原生与 agy acp 强制工具桥接及链路追踪)与 Codex 0.167.0(流式、优雅中断与自动编排)。
  • 长稳压测与多槽位沙箱:完成 62 分钟高并发连续压测及多次 SIGKILL 崩溃恢复核验;POSIX 环境内置按调用方隔离的多槽位 srt 沙箱并发池。

架构定位与当前边界

  • 单机轻量存储定位:专为个人工作站与私有团队网关打造,采用单网关实例 + 内置 SQLite(含 FTS5)零外部依赖架构,不涉及多实例横向集群。
  • 账本与外部收银解耦:门户点数用于内部配额核算与成本归集,不内置在线支付网关或邮件发送服务,方便按需对接自有业务系统。
  • 宿主权限与平台沙箱差异:外部 CLI 智能体默认沿用当前系统用户权限(macOS 与 Linux 可开启 srt 沙箱策略,Windows 暂不含本地沙箱);桌面安装包默认未附商业签名公证。
  • 开放扩展的真机验证:可通过 oaa verify <agent> 在本机对自有智能体与云端模型运行标准验收,生成脱敏报告以持续扩充实测矩阵。

带日期、版本号与原始测量数据的完整记录,见 验证证据档案 与 稳定性与数据保留说明。

现在就在本机跑通第一个智能体接口

默认仅监听本地回环端口,零外部基础设施依赖,无需预先准备云端模型密钥即可体验完整调用链路。

npm run oaa -- quickstart
快速上手指南