深入解读 BrowserOS 的 @browseros/acpx-ai-provider:基于 acpx 运行时桥接 Vercel AI SDK 的 ACP Agent Provider
深入解读 BrowserOS 的 @browseros/acpx-ai-provider:基于 acpx 运行时桥接 Vercel AI SDK 的 ACP Agent Provider
导读
@browseros/acpx-ai-provider 是 BrowserOS(开源 Agentic 浏览器)在仓库内维护的 Vercel AI SDK Provider,它架设在 acpx/runtime 之上,将 AI SDK 的 LanguageModelV2 接口与 Agent Client Protocol(ACP)的规范化事件流连接起来:一次安装即可驱动 Claude Code、Codex、Gemini、Copilot、Cursor、Pi 等任意 ACP Agent。读完本文,你将掌握该 provider 的安装配置、会话与权限模型、工具接入(MCP)、结构化输出、生命周期控制等完整实战能力,并理解其底层事件翻译、会话复用与已知边界。
为什么需要这样一层 Provider
在 ACP 生态中,acp-ai-provider 这类方案虽然能把 Vercel AI SDK 桥接到 Agent Client Protocol,但它建立在裸的 @agentclientprotocol/sdk 之上,消费者仍需自行安装每个 Agent 的 CLI、自行编写 { command, args } 的 spawn 配置。
@browseros/acpx-ai-provider 则向上再抽象了一层,直接构建在 acpx/runtime 之上,由此获得三个关键收益(见 README 的 Why 一节):
- 零额外安装:
acpx会在首次使用时通过npx自动解析并拉起内置 Agent(Claude、Codex、Gemini、Copilot、Cursor、Pi 等),无需手工下载 CLI; - 零胶水代码:stdio 管道、初始化握手、认证重试循环、权限弹窗接线全部由运行时接管,调用方无需关心;
- 薄翻译层:Provider 只负责在 AI SDK 的
LanguageModelV2与AcpRuntime的规范化事件流之间做双向翻译。
从仓库结构看,该包是 BrowserOS 对上游 acpx-ai-provider(原 DaniAkash/acpx)的快照分支(in-repo fork),钉住的上游提交为 ffb54400(tag acpx-ai-provider-v0.0.6),并已从上游的 AI SDK v6 迁移到 AI SDK v7(@ai-sdk/provider ^4、@ai-sdk/provider-utils ^5),工作区包版本为 1.0.0,详见 PROVENANCE.md。
安装与依赖
在 BrowserOS 的 browseros-agent 工作区(使用 bun 管理)中,包本身通过 workspace 引用,acpx 与 ai 是 peer 依赖:
{
"dependencies": {
"@browseros/acpx-ai-provider": "workspace:*",
"acpx": "^0.13.0",
"ai": "^7.0.0"
}
}
依据 package.json:ai 的 peer 范围是 >=7.0.0-beta.0(README 提示使用 ai ≥ 6 亦可,但本 fork 已面向 v7 迁移),acpx 使用 0.13.x。包自身只依赖 @ai-sdk/provider 与 @ai-sdk/provider-utils,运行时依赖全部落在 acpx 上,因此它是一个相当薄的翻译层。
快速开始:两段代码跑通 generateText 与流式输出
非流式调用
import { createAcpxProvider } from '@browseros/acpx-ai-provider'
import { generateText } from 'ai'
const provider = createAcpxProvider({
agent: 'claude',
cwd: process.cwd(),
})
const { text } = await generateText({
model: provider.languageModel(),
prompt: 'Summarize this repo in 3 bullets.',
})
console.log(text)
首次运行时 acpx 会通过 npx 拉取 Claude Code 的 ACP 适配器,之后的调用即为热启动(warm)。
流式调用
import { createAcpxProvider } from '@browseros/acpx-ai-provider'
import { streamText } from 'ai'
const provider = createAcpxProvider({ agent: 'claude' })
const { textStream } = streamText({
model: provider.languageModel(),
prompt: 'Write a haiku about TypeScript.',
})
for await (const chunk of textStream) process.stdout.write(chunk)
从源码看,languageModel() 返回的是 AcpxLanguageModel 实例(language-model.ts),它实现了 AI SDK 的 LanguageModelV2 接口:specificationVersion = 'v2'、provider = 'acpx',modelId 取自 opts.agent ?? settings.agent。doStream 先确保 ACP 会话句柄,再把 AI SDK prompt 转换成纯文本与附件,交给 runtime.startTurn,最后用 EventTranslator 把运行时的 AcpRuntimeEvent 逐个翻译成 LanguageModelV2StreamPart 流;doGenerate 则是 doStream + 流累积的封装。AI SDK 的 generateText / streamText 因此无需任何自定义适配即可工作。
配置参数全景
createAcpxProvider 接受一个 AcpxProviderSettings 对象(类型定义见 types.ts):
createAcpxProvider({
agent: 'claude', // 任意 acpx 内置 id,或自定义覆盖
cwd: '/path/to/repo', // Agent 的工作目录(默认 process.cwd())
sessionKey: 'my-session', // 逻辑会话名(默认 `${agent}::${cwd}`)
sessionMode: 'persistent', // 'persistent'(默认,跨轮复用)| 'oneshot'(单轮后销毁)
permissionMode: 'approve-reads', // 'approve-all' | 'approve-reads' | 'deny-all'
nonInteractivePermissions: 'deny',
resumeSessionId: 'sid-xyz', // 恢复之前的会话
turnTimeoutMs: 60_000,
stateDir: '~/.acpx', // 会话存储位置
mcpServers: [/* … */],
agentRegistryOverrides: {
'my-agent': ['node', './bin/my-agent.js', '--acp'],
},
// 高级:注入预构建运行时(测试、多 provider 共享)
runtime: customRuntime,
})
各参数要点:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
agent |
string |
必填 | 使用的 ACP Agent id |
cwd |
string |
process.cwd() |
Agent 工作目录 |
sessionKey |
string |
`${agent}::${cwd}` |
逻辑会话名,见下方解析逻辑 |
sessionMode |
'persistent' | 'oneshot' |
'persistent' |
会话生命周期 |
permissionMode |
'approve-all' | 'approve-reads' | 'deny-all' |
'approve-reads' |
权限兜底策略 |
nonInteractivePermissions |
'deny' | 'fail' |
'deny' |
非交互场景权限处理 |
resumeSessionId |
string |
— | 恢复历史会话 |
turnTimeoutMs |
number |
300_000(5 分钟) |
单轮超时 |
stateDir |
string |
~/.acpx |
会话持久化目录 |
mcpServers |
AcpxMcpServerConfig[] |
— | MCP 工具服务器 |
agentRegistryOverrides |
Record<string, string | string[]> |
— | 自定义 Agent 注册 |
runtime |
AcpRuntime |
— | 注入预构建运行时 |
关于默认值,源码 provider.ts 中明确定义:DEFAULT_PERMISSION_MODE = 'approve-reads'、DEFAULT_NON_INTERACTIVE = 'deny',stateDir 缺省为 path.join(os.homedir(), '.acpx'),turnTimeoutMs 在语言模型侧缺省为 DEFAULT_TURN_TIMEOUT_MS = 5 * 60_000(即 5 分钟)。
sessionKey 的解析逻辑在 AcpxProvider.resolveSessionKey() 中:优先取调用级 opts.sessionKey,其次 settings.sessionKey,最后回退为 `${agent}::${cwd}`。同一个 sessionKey 在 provider 内部通过 handles Map 缓存 ACP 会话句柄(ensureHandle 中按 key 命中即复用),因此相同 key 的多个 languageModel() 实例共享底层 ACP 会话。
buildRuntimeOptions() 展示了 provider 如何把自身配置转译为运行时选项:sessionStore: createFileSessionStore({ stateDir })、agentRegistry: createAgentRegistry({ overrides })、permissionMode、nonInteractivePermissions、timeoutMs、mcpServers 与 onPermissionRequest 一一透传。
内置 Agent 注册表与自定义 Agent
acpx 内置的 Agent id 包括:pi、openclaw、codex、claude、gemini、cursor、copilot、droid、iflow、kilocode、kimi、kiro、opencode、qoder、qwen、trae。行为因 Agent 而异(详见已知限制一节)。
内置注册表只是为流行 Agent 提供便利。任何能在 stdio 上走 ACP 的二进制或脚本都可以接入——通过 agentRegistryOverrides 注册:
const provider = createAcpxProvider({
agent: 'my-acp-server',
agentRegistryOverrides: {
'my-acp-server': ['./bin/my-acp-server', '--stdio'],
// 任何能产生 ACP-over-stdio 进程的写法都行:
// 'my-acp-server': ['node', './script.js', '--acp'],
// 'my-acp-server': ['npx', '@my-org/acp-adapter@1.2.3'],
},
})
自定义 Agent 要无缝接入,必须满足:
- 通过 stdio 完成 ACP 的 JSON-RPC 握手(运行时仅支持 stdio,不支持 HTTP / SSE / WebSocket 传输);
- 处理
initialize、session/new(持久会话可选session/load)、session/prompt; - 以标准工具调用状态流转(
pending→in_progress→completed/failed)发送session/update事件; - 返回文档规定的停止原因之一——
end_turn/stop_sequence/max_tokens/tool_calls/tool_use,其余值会被映射为 AI SDK 的finishReason: 'unknown'(映射表见 convert-events.ts 的STOP_REASON_MAP)。
自定义 Agent 也意味着三件事需要自行负责:没有 npx 自动下载(命令原样执行,需保证二进制在 PATH 上或使用绝对路径)、没有官方的冒烟测试矩阵保障稳定性、凭据管理归你(Agent 读取自己的环境变量或配置文件)。
如果自定义 Agent 是公开分发的 ACP 适配器,更优路径是向 acpx 提 PR 加入内置注册表,这样所有使用者都能享受 npx 自动下载。
认证:环境变量与配置文件驱动
acpx/runtime 从环境变量或 ~/.acpx/config.json 读取凭据。本 provider 不提供程序化凭据注入,也没有认证失败时的惰性重试——凭据缺失时,首次调用就会抛出 AcpxAuthRequiredError。
# 按 Agent 需求设置对应环境变量:
export ACPX_AUTH_OPENAI_API_KEY=sk-…
export ACPX_AUTH_ANTHROPIC_API_KEY=sk-ant-…
需要外部 CLI 认证的 Agent(如 GitHub Copilot),需在构造 provider 前先完成 CLI 登录:
gh auth login
持久会话与系统提示词
默认 sessionMode: 'persistent' 会让 Agent 在多次调用间保留上下文;同一 sessionKey 下的每个 languageModel() 实例共享底层 ACP 会话:
const provider = createAcpxProvider({ agent: 'claude' })
const model = provider.languageModel()
await generateText({ model, prompt: 'Hi, my name is Alice.' })
await generateText({ model, prompt: "What's my name?" }) // 记住了
await provider.close() // 用完销毁
- 预热会话(不发送提示词即建好会话):
await provider.prepare(); - 单次隔离轮次:
createAcpxProvider({ agent: 'claude', sessionMode: 'oneshot' })。
系统提示词与按会话 Agent 选项
通过 sessionOptions 可在新会话上设置 Agent 的 systemPrompt(以及可选的 model、allowedTools、maxTurns),这些值被转发到 ACP 的 session/new _meta,在首轮之前生效:
const provider = createAcpxProvider({
agent: 'claude',
sessionOptions: {
systemPrompt: 'You are an expert Rust reviewer. Be terse.',
// model: 'claude-opus-4-7',
// allowedTools: ['read', 'edit'],
// maxTurns: 5,
},
})
使用 { append: '…' } 可追加到 Agent 默认提示词而非整体替换:
sessionOptions: {
systemPrompt: { append: 'When you finish, also propose tests.' },
}
两个必须注意的语义(README 与源码注释一致,见 types.ts 的 sessionOptions 文档):
- 系统提示词在
session/new时固定;同一工作区要切换提示词需使用不同的sessionKey。改变sessionOptions并复用同一 key 对已复用的会话记录是 no-op(有意为之)——provider.close()也不会清除持久记录,所以仅靠 close 不会强制发起新的session/new; - 并非每个 Agent 都认每个选项——Codex / Gemini 会忽略 Claude 专属字段(如
model),无法识别的选项在 ACP 层被静默丢弃。
测试用例 验证了 systemPrompt 字符串与 { append } 形式及其他选项(model、allowedTools、maxTurns)都会被原样转发到 runtime.ensureSession,未配置时则不传该字段。
推理链与计划(Reasoning & Plan Steps)
多数 ACP Agent 会流式输出思维链。provider 将其暴露为 AI SDK 的 reasoning parts,消费者用与处理其他可推理模型完全相同的代码即可渲染:
import { streamText } from 'ai'
const result = streamText({
model: provider.languageModel(),
prompt: 'Refactor user.ts to use Result<T, E>',
})
for await (const part of result.fullStream) {
if (part.type === 'reasoning-delta') {
ui.appendThinking(part.delta) // 流式 "💭…" 气泡
} else if (part.type === 'text-delta') {
ui.appendAnswer(part.delta)
}
}
当 Agent 发出计划("I will: 1. read file 2. fix bug 3. test")时,provider 通过同一通道将其作为带 [Plan] 前缀的独立 reasoning 块呈现:
reasoning-start (id-1)
reasoning-delta (id-1, "[Plan] 1. read file 2. fix bug 3. test")
reasoning-end (id-1)
实现细节见 convert-events.ts:EventTranslator.handleStatus() 对 tag === 'plan' 的事件生成独立的 reasoning-start/delta/end 三元组(trim 后为空则跳过)。计划块拥有自己的 block id,不会干扰进行中的思考块——Agent 可以一边往一个 id 里持续输出推理,一边在其他 id 上进出计划通告。
不输出推理的 Agent(如某些配置下的 Gemini CLI)则不会产生任何 reasoning-* parts,消费者代码里的 reasoning-delta 分支自然不触发,无需特判。
控制推理强度
多数支持思考的 Agent 接受 reasoning_effort 配置项,用延迟换深度——强度越高,回答前消耗的思维链 token 越多。在下一轮开始前设置:
const provider = createAcpxProvider({ agent: 'claude' })
await provider.setConfigOption('reasoning_effort', 'high')
当前已确认的支持矩阵:
| Agent | Config key | 可选值 | 默认值 |
|---|---|---|---|
claude |
reasoning_effort |
low / medium / high / xhigh |
medium |
codex |
reasoning_effort(CLI 别名 thought_level) |
low / medium / high / xhigh |
medium |
gemini、copilot、cursor 等 |
尚未有文档化确认 | — | — |
注意 thought_level 是 Codex 专属别名——acpx codex set thought_level high 在分发前会被翻译成 reasoning_effort = high,其他 Agent 原样接收 reasoning_effort。
发现某 Agent 的配置键
不在上表中的 Agent(或 acpx 新增的 Agent),其配置词汇表是逐 Agent 的,有三种发现途径:
- 运行时能力:询问 Agent 它公告了哪些键:
const handle = await provider.prepare() const caps = await provider.runtime.getCapabilities?.({ handle }) console.log(caps?.configOptionKeys) acpxCLI:全局安装 acpx 后检查 Agent 的命令树(acpx <agent>)。- 适配器源码:每个已发布的 ACP 适配器都有
session/set_config_option处理器,列出其接受的键。
注意事项
- 强度变更作用于下一轮而非进行中的一轮:流中调用
setConfigOption只对下一次streamText/generateText生效; - 切换模型不会重置强度:随后
setConfigOption('model', …)会保留此前设置的推理强度,想恢复默认需显式重置; - 对不在表中的 Agent,使用上文发现方法:无法识别的配置键会在下一轮以错误形式暴露,对着 Agent 实际能力列表做试错是安全的。
工具:通过 MCP 服务器接入
工具通过 mcpServers 传入的 MCP(Model Context Protocol)服务器定义。Agent 发现并调用它们,结果通过 provider 的流以 tool-call / tool-result parts 回流:
const provider = createAcpxProvider({
agent: 'claude',
mcpServers: [
{
type: 'stdio',
name: 'filesystem',
command: 'npx',
args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
env: { LOG_LEVEL: 'info' }, // stdio 服务器 —— env 为 Record
},
{
type: 'http',
name: 'remote',
url: 'https://example.com/mcp',
headers: { Authorization: 'Bearer …' }, // http/sse 服务器 —— headers 为 Record
},
],
})
env 与 headers 以普通 Record<string, string> 接受(类型见 types.ts 的 AcpxMcpServerStdio / AcpxMcpServerHttp),provider 在交给运行时前把它们转成 ACP 线上格式 Array<{ name, value }>——实现位于 mcp-servers.ts 的 recordToEntries()。此外还支持 type: 'sse' 的远程服务器配置。
注意:宿主侧 AI SDK 工具(
acp-ai-provider中的acpTools()/ TCP 回调方案)在 v0.1 不支持,见已知限制。
逐调用权限控制
默认情况下,Agent 发出的每个权限请求(写文件、执行 shell 命令、删除等)都由前置的 permissionMode 设置统一裁决。若要用自己的 UI 拦截单个请求,传入 onPermissionRequest 回调:
const provider = createAcpxProvider({
agent: 'codex',
cwd: '/path/to/repo',
permissionMode: 'approve-reads', // 未处理情况的兜底
onPermissionRequest: async (req, { signal }) => {
// Agent 此时暂停在轮次中间等待你的裁决。
// 尊重 `signal`,这样取消轮次不会让它挂起。
const decision = await myUi.prompt({
title: req.raw.toolCall.title,
kind: req.inferredKind, // 'edit' | 'shell' | 'delete' | …
args: req.raw.toolCall.input,
})
return decision
// 返回 `undefined` 则回退到基于模式的裁决器。
},
})
回调收到的字段:
| 字段 | 含义 |
|---|---|
req.sessionId |
ACP 会话 id(多会话宿主很实用) |
req.raw |
ACP SDK 的完整原始 RequestPermissionRequest |
req.inferredKind |
'read' | 'search' | 'edit' | 'delete' | 'move' | 'execute' | 'fetch' | 'think' | 'other' 之一——根据工具标题做的最佳努力分类 |
ctx.signal |
轮次取消或会话关闭时触发中止 |
可返回的裁决值:
{ outcome: 'allow_once' }— 批准本次单次调用{ outcome: 'allow_always' }— 批准同类调用直到本轮结束{ outcome: 'reject_once' }— 拒绝本次调用;Agent 继续其余任务{ outcome: 'reject_always' }— 拒绝并记住直到本轮结束{ outcome: 'cancel' }— Agent 视该调用为已取消(通常结束本轮)undefined— 回退到基于模式的裁决器
重要注意点:
- 回调仅当 provider 自行构建运行时(不传
runtime)时才被调用。若通过runtime传入预构建运行时,请把onPermissionRequest设置在那个运行时上; - 回调内抛错会回退到基于模式的逻辑并由运行时记录日志——别让 UI 错误拖垮整轮;
- Agent 在你的 promise 解决前是暂停的。provider 不强制超时——请自行接线(或依赖 Agent 内部超时,通常 5–10 分钟)。
列出与切换模型
部分 Agent(Claude Code、Codex)会在会话打开时公告它们可驱动的模型。用 getModels() 读取可用列表与当前选中 id:
const models = await provider.getModels()
if (models) {
console.log(models.availableModelIds) // ['claude-haiku-4-5', …]
console.log(models.currentModelId) // 'claude-opus-4-7'
}
返回 undefined 的场景:Agent 未公告任何模型(如 Gemini CLI、省略 NewSessionResponse.models 的自定义适配器);底层运行时未实现 getStatus。
getModels() 在会话未打开时会惰性拉起 ACP 会话(与 prepare() 相同)。多会话 provider 请传入与 languageModel() 相同的 { sessionKey, agent }:
const models = await provider.getModels({ sessionKey: 'codex::/repo' })
切换模型使用生命周期控制里的 setConfigOption('model', id)。源码上 getModels() 依赖 runtime.getStatus 是否存在(AcpxProvider.getModels() 先检查 getStatusImpl,无则返回 undefined)。
结构化输出(JSON)
generateObject / streamObject 通过 JSON 模式工作。provider 在 prompt 前追加结构化输出指令,并从输出流中剥离 markdown 围栏(json … ),让 AI SDK 的解析器拿到干净的 JSON:
import { generateObject } from 'ai'
import { z } from 'zod'
const { object } = await generateObject({
model: provider.languageModel(),
schema: z.object({
name: z.string(),
ingredients: z.array(z.string()),
}),
prompt: 'Give me a recipe for chocolate chip cookies.',
})
streamObject 同样可用。
实现层面(json-output.ts):doStream 在 callOptions.responseFormat?.type === 'json' 时给输出流接上 createJsonCleanupTransform();该 TransformStream 策略性地保留 text-start 直到确认前几个字节是围栏还是裸 JSON,识别到开围栏即剥离(需要换行才能确定语言标签结束位置),流式期间保留 12 字节的小后缀缓冲以去掉尾部闭合围栏,从而无需缓冲整个 payload。同时 convert-prompt.ts 的 buildJsonSchemaPrompt() 会生成 [Structured Output Instruction] 指令块,明确要求"只输出单个合法 JSON 值、不要 markdown 围栏、不要前后附加解释"。
生命周期控制
await provider.cancel('user pressed stop') // 取消进行中的轮次
await provider.setMode('plan') // 切换会话模式(若 Agent 支持)
await provider.setConfigOption('model', 'opus') // 调整 Agent 配置项
const report = await provider.doctor() // 来自运行时的诊断信息
await provider.close('done') // 释放所有会话
setMode、setConfigOption、doctor 在底层 Agent 未实现时为 no-op(源码中分别检查 runtime.setMode / setConfigOption / doctor 是否存在,不存在则直接返回)。可用 provider.runtime.getCapabilities() 查看支持情况。close() 还支持 { discardPersistentState: true } 可选地丢弃持久化状态(这是本 fork 相对上游的本地补丁之一,见 PROVENANCE)。
AcpxProvider 还额外暴露了若干运行时无关的辅助能力(源码 provider.ts):
provider.events(EventEmitter<AcpxProviderEvents>):订阅usage与availableCommands推送事件;getUsage(sessionKey?)/getAvailableCommands(sessionKey?):同步读取最近的用量快照与 Agent 公告的斜杠命令列表(返回防御性拷贝);runSlashCommand({ name, … })/compact():发送如/compact的斜杠命令——ACP 本身没有 compact 动词,斜杠由 Agent 侧解释;compact()会从已公告命令中解析compact/condense并执行。
已知限制:alpha 软件的真实边界
这是 alpha 级软件,多数粗糙边缘来自同样未到 1.0 的 acpx/runtime。以下限制在 README 中逐条列出,并结合源码给出佐证。
继承自 acpx/runtime
- 工具输入与输出共用一个文本字段:
tool-call.input与tool-result.result是同一个字符串。运行时把两者折叠进一个text字段——底层 ACP 协议里它们是分开的,但运行时的规范化器丢弃了这一区分(见 convert-events.ts 的finalizeToolCall(),input与result均取state.emittedText); - 工具输入是原始字符串而非解析后的 JSON:Agent 输出合法 JSON 时需自行
JSON.parse,否则预期会失败; - 没有输入/输出 token 拆分:只有
cachedInputTokens流入 AI SDK,inputTokens、outputTokens、totalTokens为undefined,逐 token 成本计算不可用(见EventTranslator.accumulatedUsage()——仅在有 per-turn breakdown 时填充inputTokens/outputTokens/reasoningTokens); - 无流式用量更新:只有运行时最近的
usage_update会存续到finishpart 上;上下文窗口大小通过providerMetadata.acpx.contextWindow暴露(usage_update的size字段,见finish()与测试); - 权限策略默认基于模式:未提供
onPermissionRequest回调时,请求回退到permissionMode+nonInteractivePermissions; - 认证由环境变量 / 配置文件驱动,无惰性重试:凭据缺失在首次使用时即抛错;
- 首次使用 Agent 时的
npx冷启动:内置 Agent 通过npx自动下载,全新安装后的首次调用可能耗时 10 秒以上; - 会话以文件形式持久化在
~/.acpx/sessions/:默认不是多进程安全的,必要时用stateDir覆盖; - 轮次中途的
AbortSignal尊重程度因 Agent 而异:signal 会被转发给runtime.startTurn,但 Agent 停止多快各不相同,provider.cancel()是最强信号; - 可选控制方法可能 no-op:
setMode、setConfigOption、doctor、getStatus并非每个 Agent 都实现。
AI SDK 集成层面
LanguageModelV2兼容模式警告:AI SDK v6 首次使用会打印警告("specificationVersion is used in a compatibility mode"),无害,迁移到 V3 后消失;- 无宿主侧 AI SDK 工具:v0.1 只支持 Agent 通过 MCP 服务器学到的工具;传给
streamText的 AI SDKtool({ execute })回调不会被本 provider 调用——Agent 并不知道它们; tool-call.providerExecuted恒为true:所有工具调用都被标记为已由 Agent 执行;- 多步 /
stopWhen:AI SDK 的循环在 SDK 层工作,但每一步都是全新的runtime.startTurn,请使用默认的sessionMode: 'persistent'让 Agent 跨步保留自己的上下文; generateObject/streamObject走 JSON 模式:非 JSON 严格的 Agent 可能输出畸形 JSON;围栏剥离转换只处理 markdown 包装,不处理坏 JSON;request.body与response.headers是合成的:request.body为{ agent, sessionKey },response.headers恒为{}——本 provider 没有 HTTP 层。
各 Agent 的怪癖
不同内置 Agent 行为不同,推荐起始矩阵:
| Agent | 备注 |
|---|---|
claude |
测试最充分路径,文本 + 工具干净 |
codex |
JSON 输出最受益于围栏清理 |
pi |
冒烟测试最便宜的选择 |
gemini |
需要 --experimental-acp(注册表已自动传入),能力面仍在演进 |
copilot |
需要已认证的 GitHub Copilot CLI,先执行 gh auth login |
v0.1 明确不在范围内
这些是有意为之的非目标,而非缺陷:宿主侧 AI SDK 工具;单个 streamText 调用内的流中模型切换;provider 定义的动态工具路由;实时 token 成本计算;按 languageModel() 的独立 Agent 注册表。
错误处理
provider 导出四个错误类(errors.ts):
import {
AcpxError,
AcpxAgentNotFoundError,
AcpxAuthRequiredError,
AcpxTurnTimeoutError,
} from '@browseros/acpx-ai-provider'
AcpxError:基类,携带code与retryable标志;AcpxAgentNotFoundError:code = 'agent_not_found',retryable = false;AcpxAuthRequiredError:code = 'auth_required',retryable = false,缺省消息提示设置ACPX_AUTH_<METHOD>环境变量或填充~/.acpx/config.json;AcpxTurnTimeoutError:code = 'turn_timeout',retryable = true。
用 AcpxError 捕获宽泛场景,三个子类覆盖常见可诊断原因。其余情况回退到基类并保留运行时的 code。fromRuntimeError() 会基于错误文本中的关键词(agent_not_found、auth_required / unauthenticated、timeout 等)做启发式归类。测试验证了失败轮次抛出的错误携带 Agent 的错误数据(with-generate-text.test.ts 中断言 code: 'rate'、message: 'boom')。
在 BrowserOS 中的定位与延伸阅读
@browseros/acpx-ai-provider 位于 BrowserOS 仓库 packages/browseros-agent/packages/acpx-ai-provider/ 目录,是 browseros-agent 工作区中供内部消费的 scoped workspace 包。它的使命是让 AI SDK 应用(尤其是 BrowserOS 自身的 Agent 侧产品)以统一编程模型驱动任意 ACP Agent,而无需关心具体 CLI 的安装、spawn 配置与协议细节。
想深入了解实现细节,可继续阅读:
- Provider 实现:会话句柄管理、配置转译、生命周期与斜杠命令
- LanguageModel 实现:
LanguageModelV2的doStream/doGenerate - 事件翻译器:
AcpRuntimeEvent→ AI SDK stream part 的完整映射 - Prompt 转换:多轮消息、附件与 JSON 指令的文本化
- JSON 围栏清理:流式剥离
json的 TransformStream - 错误层次:错误分类与运行时错误归一化
- 类型定义:全部设置项与类型别名
- 来源说明:上游快照、本地补丁与分叉策略
- 测试目录:单元测试(事件翻译、prompt 转换、sessionOptions、get-models、json-output、mcp-servers、provider)与集成测试(
generateText/streamText全链路、会话生命周期、消息边界等)
许可证
MIT © Dani Akash(本仓库内复制件的许可证声明见 LICENSE)。