Agent SDK
Go API 导航
按任务查找公开入口、消息类型和配置方法，定位完整 GoDoc 与源码。
调用与会话
| 入口 | 返回或用途 | 关键约束 |
|---|---|---|
Prompt(ctx, PromptRequest) | ResultMessage, error | 内部消费到首个结果 |
Query(ctx, QueryRequest) | *Stream, error | 调用者负责关闭 |
NewSession(ctx, Options) | *Session, error | 初始化持续连接 |
ResumeSession(ctx, id, Options) | *Session, error | id 不能为空，数据需要可访问 |
ForkSession(ctx, id, messageID, Options) | *Session, error | 完成消息边界，不同时指定目标 ID |
Session.Send / SendWithOptions | 本轮 Stream | 输出通道由 Session 共用 |
Session.SendMessage | 发送结构化消息 | 使用 protocol 内容块 |
Stream.Recv | 下一条 ReceivedMessage | 不与 Result 并发读取 |
Stream.Result | 首个最终结果 | 没有终态时返回错误 |
Session.Interrupt / Close | 停止执行 / 关闭连接 | 用于不同生命周期阶段 |
完整签名见 client GoDoc。
运行期控制
Session.Control() 集中提供 SetModel、SetPermissionMode、SetMaxThinkingTokens、ContextUsage、SupportedModels、SupportedAgents、SupportedCommands、InitializationResult 和 GetSettings 等入口。
扩展控制包括 UpdateEnvironment、TryAutoDream、StopTask、SendTaskMessage、SetNextTurnContext、RemoveMessages 和 RewindFiles。先检查对应能力和运行时支持，再处理返回错误。
RewindFiles 用于指定用户消息的文件回滚，可先 dry run；它不恢复数据库、网络服务或任意外部副作用。RemoveMessages 修改消息记录，不等于回滚文件。
配置入口
| 配置域 | 常用方法 | 指南 |
|---|---|---|
| 运行环境 | WithRuntime、WithCLIPath、WithCWD、WithEnv | 运行时 |
| 提示词 | WithSystemPrompt、WithAppendSystemPrompt | 配置 |
| 模型与预算 | WithModel、WithMaxTurns、WithMaxBudgetUSD | 用量 |
| 工具与权限 | WithTools、WithAllowedTools、WithPermissionHandler | 权限 |
| 扩展 | WithCustomTools、WithMCPServer、AddHookMatcher | 工具、Hooks |
| 输出 | WithOutputFormat、WithIncludePartialMessages | 结构化输出、消息流 |
| 会话 | WithSessionID、WithResume、WithPersistSession | 会话 |
| 诊断 | WithStderr、WithDiagnostics、WithInitializeTimeout | 排错 |
消息和结果类型
接收类型使用 protocol.ReceivedMessage，最终结果使用 protocol.ResultMessage。文本块通过 AsTextBlock 获取，发送结构化内容用 NewUserBlocksMessage、NewTextContent、NewImageContent 等构造函数。
协议含有 mixed-casing 字段，不要对工具输入、Hook 数据或控制消息整体做 snake_case/camelCase 转换。优先用公开类型序列化；兼容未知字段时保留原样，并限制其传播范围。
完整类型见 protocol GoDoc。
版本核对
go list -m github.com/nexus-research-lab/nexus-agent-sdk-bridge
go doc github.com/nexus-research-lab/nexus-agent-sdk-bridge/client.Session
go doc github.com/nexus-research-lab/nexus-agent-sdk-bridge/client.Options
文档描述当前公开接口。若 GoDoc 或编译器提示方法不存在，先核对项目实际依赖的版本与运行时版本，阅读 bridge 变更记录。不要通过导入 internal 包绕过缺失的公开能力。