# Agent SDK 概览

用 Go 将 Agent 接入自己的应用，理解 bridge、运行时与宿主的分工。

## 用 Go 构建自己的 Agent 应用

Nexus Agent SDK Bridge 是开源 Go 接入库。你可以把它用于桌面助手、服务端任务、代码审查和业务工具，让自己的程序发送任务、展示执行过程、处理审批，再接收结果。

安装包名为 `github.com/nexus-research-lab/nexus-agent-sdk-bridge`。本组文档中的 SDK 指这个公开接入层。它启动或连接运行时，通过 `stream-json` 交换消息；模型调用、工具执行循环和上下文管理由运行时完成。

![应用、Bridge 与默认 nxs 运行时的职责及第三方接入边界](/images/docs/sdk-runtime-architecture.svg)

因此，`go get` 安装的是接入库，还需要准备运行时。Bridge 不包含、下载或构建闭源的 nxs，也不要求你的应用导入闭源 SDK。你的 Go 应用可以独立于 Nexus 产品运行。

## 从哪一章开始

| 你要完成的工作 | 阅读章节 |
| --- | --- |
| 从零运行第一个 Go 程序 | [快速开始](/docs/sdk-quickstart) |
| 比较一次调用和持续会话 | [调用方式](/docs/sdk-query) |
| 逐步展示文本、工具和最终状态 | [消息流](/docs/sdk-streaming) |
| 保存会话并恢复任务 | [会话管理](/docs/sdk-sessions) |
| 让 Agent 调用你的 Go 函数 | [自定义工具](/docs/sdk-tools) |
| 连接现有 MCP 服务 | [MCP](/docs/sdk-mcp) |
| 控制工具权限与审批 | [权限](/docs/sdk-permissions) |
| 接入生命周期回调 | [Hooks](/docs/sdk-hooks) |
| 委派给专职 Agent | [子 Agent](/docs/sdk-subagents) |
| 获得可交给程序消费的数据 | [结构化输出](/docs/sdk-structured-output) |
| 处理取消、失败与服务端部署 | [错误处理](/docs/sdk-errors)、[部署](/docs/sdk-hosting) |

## 示例约定

快速开始、消息流和自定义工具提供完整 Go 程序。其余代码块展示函数内的接入步骤，沿用已创建的 `ctx`、`options`、`session` 或本轮 `result`；使用时导入相应公开包，并处理返回的流。路径、服务地址和业务数据均为示例，需要替换为你的配置。

## 选择运行时

nxs 是 Nexus 的默认 Agent 运行时，本组教程和业务示例均以 nxs 为起点。独立应用需要提供明确的 nxs 可执行文件路径，并准备其模型访问配置。

Bridge 也支持接入第三方异构 Agent 运行时，Claude Code 是当前已支持的一种，需要显式选择并单独配置。运行时接入边界不限定为 nxs 和 Claude Code；后续新增适配时，宿主仍通过公开契约和能力协商判断可用功能。其他运行时尚不能直接视为已支持。

不同运行时通过统一的 Go 消息与控制入口接入，但并非每项扩展都相同。例如 AutoDream、环境热更新有运行时边界，单条消息执行限制还需要协议协商。调用前使用 `session.Supports(...)`，并处理调用返回的错误。详见[运行时与能力](/docs/sdk-runtimes)。

## 一次任务包含什么

宿主创建会话后发送用户消息。运行时可能产生多段文本、调用多个工具、等待权限回调，最后发送 `result`。收到一段回答不代表任务结束；收到 `result` 也不代表业务成功，需要检查 `IsError` 和结果内容。

把两种身份分开保存：业务任务 ID 用于你的队列与页面，Session ID 用于恢复运行时对话。不要把一个全局会话共享给所有用户。

## 公开包与版本

| 包 | 用途 |
| --- | --- |
| `client` | Options、Prompt、Query、Session、能力与控制 |
| `protocol` | 收发消息、内容块、结果和协议类型 |
| `permission` | 权限模式、请求和决策 |
| `hook` | Hook 事件、匹配器和返回值 |
| `tools` | Go 自定义工具、结果和进程内 MCP 服务 |
| `mcp` | 外部服务配置与状态 |
| `agent` | 子 Agent 定义 |

业务代码只导入公开包。`internal/` 不是接入接口。上线时固定 bridge 版本，同时记录运行时版本，升级后验证自己使用的能力。

完整类型见 [GoDoc](https://pkg.go.dev/github.com/nexus-research-lab/nexus-agent-sdk-bridge/client)，运行时差异见[公开契约](https://github.com/nexus-research-lab/nexus-agent-sdk-bridge/blob/main/docs/runtime-contract.zh-CN.md)。