示例集(Cookbook)
这里收录了按实际开发场景分类的、可直接复制运行的智能体调用脚本。每个脚本都是单文件:文件开头几行写明了用途、前置条件与运行命令,涵盖 curl 以及官方 openai、anthropic、google-genai SDK 的 Python 与 Node.js 写法。所有脚本均通过环境变量读取配置,不含任何硬编码密钥。
提示:除了直接运行本目录的脚本,你也可以打开控制台左侧的 「对话工作台」(
#workbench),选好智能体、图片或外层工具后点击右上角 「复制代码」,一键导出与当前会话完全一致的四协议调用代码。
本目录中的每一个可执行脚本都会在 CI 的兼容性实验室(npm run compat)中针对隔离网关自动跑通并校验退出码与输出内容(测试编排见 integrations/compat/cookbook.mjs)。
运行准备
所有示例共用以下三个环境变量:
| 环境变量 | 说明 | 默认值 |
|---|---|---|
OAA_BASE_URL | 网关根地址(不带 /v1 路径) | http://127.0.0.1:8787 |
OAA_API_KEY | 在控制台或命令行创建的调用方密钥(sk-oaa-…) | 必填 |
OAA_AGENT | 目标智能体的调用名(与 GET /v1/models 返回的 id 一致) | agent/sample |
可选变量 OAA_PROMPT(长任务脚本另支持 OAA_LONG_PROMPT)用于自定义发送给智能体的任务描述。
1. 先用离线示例智能体零配置跑通
不需要准备任何模型密钥,两条命令即可在本地跑通第一批示例:
oaa quickstart # 启动本机网关并发布离线智能体 agent/sample
export OAA_API_KEY="$(cat .oaa/keys/quickstart.key)" # 读取调用方密钥(具备调用、读取、文件与审批权限)第 3 组中的「注册事件回调 Webhook」属于网关管理操作,需要额外导出管理员令牌:
export OAA_ADMIN_KEY="$(cat .oaa/admin.token)"。
2. 切换为你发布的真实智能体
当你通过控制台或 oaa connect codex / oaa connect ollama 发布了真实智能体后,只需改一行 OAA_AGENT,同一批脚本就能直接驱动真实智能体执行任务:
export OAA_AGENT="agent/codex" # 或 agent/antigravity、agent/assistant 等3. 安装对应语言的官方 SDK
只安装你要运行的那门语言即可(curl 脚本无需额外依赖):
pip install openai anthropic google-genai
npm install openai @anthropic-ai/sdk @google/genai注意:自己新建测试脚本时,请避免将文件命名为 openai.py 或 anthropic.py,否则会与同名官方包产生导入冲突。
场景示例速查表
在 examples/cookbook 目录下直接运行任意脚本即可:
python 01-first-call/hello_openai.py
node 04-caller-tools/tools_anthropic.mjs
sh 05-structured-output/structured.sh离线 agent/sample 与真实智能体的能力对照
quickstart 默认发布的 agent/sample(源码位于 examples/sample-agent.mjs)是一个不联网、不调大模型的规则型进程,适合零成本验证链路,但部分高级协议特性需要真实模型或完整智能体才能完整走通:
| 示例分组 | 使用离线 agent/sample 时的表现 | 完整体验所需的目标智能体 |
|---|---|---|
| 01 首次调用 | 直接跑通,返回固定规则文本 | 任意智能体 |
| 02 长任务与续接 | 后台提交与轮询正常;因该示例进程未实现会话恢复,取消会记为 incomplete(effect_outcome_unknown),previous_response_id 会返回 native_resume_unsupported | 内置内核智能体,或支持会话恢复的 Codex / ACP 智能体 |
| 03 人工与自动审批 | 直接跑通:输入含 approve 时会发起写文件审批,批准即完成,拒绝则返回 permission_denied | 配置了审批拦截的智能体 |
| 04 外层工具桥接 | 示例进程不会主动发起外层函数调用(脚本以退出码 3 提示说明) | 内置内核智能体,或 Codex / Claude Code / Antigravity / ACP 智能体(详见 双层 Harness) |
| 05 结构化 JSON 输出 | 演示校验未通过分支(返回 structured_output_invalid,退出码 3) | 内置内核智能体,或支持多轮修正的真实智能体(详见 结构化输出) |
| 06 图片输入 | 可正常接收图片载荷,固定文本不会描述画面内容 | 具备视觉能力的智能体(见 GET /v1/models 中的 image_input 标记) |
| 07 错误与幂等重试 | 直接跑通 | 任意智能体 |
| 08 工具链环境接入 | 直接跑通 | 任意智能体 |
各脚本统一的退出码约定:0 表示成功跑完目标流程;2 表示请求参数或目标智能体能力不匹配(例如向纯文本智能体传图);3 表示脚本正常执行完毕,但当前离线智能体未触发该高级动作(如未发起外层 tool_calls)。
接入常用 IDE、聊天桌面端与自动化平台
- 本机客户端一键配置(推荐):对于本机已安装的 Cursor、Windsurf、Claude Desktop、Claude Code、OpenCode、Codex CLI 与 DSH,无需手工改配置文件,直接在控制台左侧打开 本地互联 页面即可一键注入 API 提供方或 MCP 桥。
- 通用三要素配置:其他兼容 OpenAI / Claude / Gemini 接口的应用只需填入 Base URL、API Key 与 智能体调用名(完整兼容细节见 客户端兼容性指南):
| 客户端 / 平台 | 配置入口 | Base URL 填法 | 模型名字段填法 | 现成配置模板 |
|---|---|---|---|---|
| Open WebUI | Admin Settings → Connections → OpenAI | http://<host>:8787/v1 | 自动拉取 /models,或填入 Model IDs | — |
| LibreChat | librechat.yaml → endpoints.custom[] | http://<host>:8787/v1 | models.default 或开启 models.fetch: true | librechat.yaml |
| Chatbox | Provider → API Host | http://<host>:8787/v1 | 拉取模型列表或手动填入智能体名 | — |
| Cherry Studio | Model Provider → Add → OpenAI → API Host | http://<host>:8787 或带 /v1 | 拉取列表或手动添加 | — |
| LobeChat | AI Service Provider → OpenAI → API Proxy URL | http://<host>:8787/v1 | 拉取模型列表或手动添加 | — |
| NextChat | Settings → Custom Endpoint → OpenAI Endpoint | http://<host>:8787(不带 /v1) | Settings → Custom Models | — |
| Dify | Model Provider → OpenAI-API-compatible | Docker 部署填 http://host.docker.internal:8787/v1 | Model Name 填智能体调用名 | — |
| n8n | Credentials → OpenAI | http://<host>:8787/v1 | 从列表选择或按 ID 填写 | — |
| Continue | config.yaml → models[] | http://<host>:8787/v1 | model: agent/sample(或真实智能体名) | continue.config.yaml |
| Cline / Roo Code | API Provider 选 OpenAI Compatible | http://<host>:8787/v1 | 智能体调用名 | — |
| Zed | settings.json → language_models.openai_compatible | http://<host>:8787/v1 | available_models[].name | zed.settings.json |
| Cursor | Override OpenAI Base URL(经云端转发,本机建议走「本地互联」MCP 桥) | 本机地址未验证 | 自定义模型名 | — |
常见配置小贴士:
注意
/v1后缀差异:OpenAI 生态 SDK 与绝大多数第三方客户端的 Base URL 以/v1结尾;Anthropic 与 Gemini 官方 SDK 的 Base URL 不带/v1:export OPENAI_BASE_URL="$OAA_BASE_URL/v1" OPENAI_API_KEY="$OAA_API_KEY" export ANTHROPIC_BASE_URL="$OAA_BASE_URL" ANTHROPIC_API_KEY="$OAA_API_KEY"容器与跨域访问:当 Dify、Open WebUI 等客户端运行在 Docker 容器内时,通过
host.docker.internal访问宿主机网关需将该主机名加入网关配置的allowedHosts;纯浏览器前端直连时需将页面源加入allowedOrigins。自带
tools的客户端:Cline、Continue Agent 模式、Zed 等客户端会在请求里附带自身工具定义。支持工具桥接的智能体(内核智能体、Codex、Claude Code、Antigravity、ACP)会自动接管并回传tool_calls;若目标适配器不支持外层工具,可改用兼容入口http://<host>:8787/v1/compat让网关忽略外层工具定义。