Agent SDK
Agent SDK 概览
用 Go 将 Agent 接入自己的应用，理解 bridge、运行时与宿主的分工。
用 Go 构建自己的 Agent 应用
Nexus Agent SDK Bridge 是开源 Go 接入库。你可以把它用于桌面助手、服务端任务、代码审查和业务工具，让自己的程序发送任务、展示执行过程、处理审批，再接收结果。
安装包名为 github.com/nexus-research-lab/nexus-agent-sdk-bridge。本组文档中的 SDK 指这个公开接入层。它启动或连接运行时，通过 stream-json 交换消息；模型调用、工具执行循环和上下文管理由运行时完成。
因此，go get 安装的是接入库，还需要准备运行时。Bridge 不包含、下载或构建闭源的 nxs，也不要求你的应用导入闭源 SDK。你的 Go 应用可以独立于 Nexus 产品运行。
从哪一章开始
| 你要完成的工作 | 阅读章节 |
|---|---|
| 从零运行第一个 Go 程序 | 快速开始 |
| 比较一次调用和持续会话 | 调用方式 |
| 逐步展示文本、工具和最终状态 | 消息流 |
| 保存会话并恢复任务 | 会话管理 |
| 让 Agent 调用你的 Go 函数 | 自定义工具 |
| 连接现有 MCP 服务 | MCP |
| 控制工具权限与审批 | 权限 |
| 接入生命周期回调 | Hooks |
| 委派给专职 Agent | 子 Agent |
| 获得可交给程序消费的数据 | 结构化输出 |
| 处理取消、失败与服务端部署 | 错误处理、部署 |
示例约定
快速开始、消息流和自定义工具提供完整 Go 程序。其余代码块展示函数内的接入步骤，沿用已创建的 ctx、options、session 或本轮 result；使用时导入相应公开包，并处理返回的流。路径、服务地址和业务数据均为示例，需要替换为你的配置。
选择运行时
nxs 是 Nexus 的默认 Agent 运行时，本组教程和业务示例均以 nxs 为起点。独立应用需要提供明确的 nxs 可执行文件路径，并准备其模型访问配置。
Bridge 也支持接入第三方异构 Agent 运行时，Claude Code 是当前已支持的一种，需要显式选择并单独配置。运行时接入边界不限定为 nxs 和 Claude Code；后续新增适配时，宿主仍通过公开契约和能力协商判断可用功能。其他运行时尚不能直接视为已支持。
不同运行时通过统一的 Go 消息与控制入口接入，但并非每项扩展都相同。例如 AutoDream、环境热更新有运行时边界，单条消息执行限制还需要协议协商。调用前使用 session.Supports(...)，并处理调用返回的错误。详见运行时与能力。
一次任务包含什么
宿主创建会话后发送用户消息。运行时可能产生多段文本、调用多个工具、等待权限回调，最后发送 result。收到一段回答不代表任务结束；收到 result 也不代表业务成功，需要检查 IsError 和结果内容。
把两种身份分开保存：业务任务 ID 用于你的队列与页面，Session ID 用于恢复运行时对话。不要把一个全局会话共享给所有用户。
公开包与版本
| 包 | 用途 |
|---|---|
client | Options、Prompt、Query、Session、能力与控制 |
protocol | 收发消息、内容块、结果和协议类型 |
permission | 权限模式、请求和决策 |
hook | Hook 事件、匹配器和返回值 |
tools | Go 自定义工具、结果和进程内 MCP 服务 |
mcp | 外部服务配置与状态 |
agent | 子 Agent 定义 |
业务代码只导入公开包。internal/ 不是接入接口。上线时固定 bridge 版本，同时记录运行时版本，升级后验证自己使用的能力。