SDK 快速开始 | Nexus 文档

完成第一个任务

本章创建一个独立 Go 程序，让 Agent 阅读当前项目并给出摘要。先完成只读任务，确认命令路径、模型访问和结果处理都能工作，再接入写文件或外部服务。

准备环境

需要 Go 1.24 或更高版本，以及已配置模型访问的 nxs。nxs 是 Nexus 的默认 Agent 运行时；bridge 是 Go 接入库，安装它不会同时安装运行时或配置模型凭据。

先从 Nexus 发布包或已授权来源准备 nxs，设置它的可执行文件路径。下面的路径是占位示例，请换成本机实际路径。后续示例均沿用这个环境变量。

export NEXUS_NXS_COMMAND_PATH="/opt/nexus/bin/nxs"
test -x "$NEXUS_NXS_COMMAND_PATH"

确认文件可执行，并在运行程序的同一用户身份下准备好 nxs 的模型配置与凭据。模型访问由运行时负责，bridge 本身不提供模型额度。

mkdir nexus-sdk-demo
cd nexus-sdk-demo
go mod init example.com/nexus-sdk-demo
go get github.com/nexus-research-lab/nexus-agent-sdk-bridge@latest

在目录中放入一份不含敏感内容的 README.md。它是本次任务的输入材料。WithCWD(".") 以程序启动目录为工作目录，因此运行程序时应留在此目录。

编写 main.go

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "github.com/nexus-research-lab/nexus-agent-sdk-bridge/client"
)

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
    defer cancel()
    options := client.NewOptions().
        WithRuntime(client.RuntimeNXS).
        WithCWD(".").
        WithTools("Read", "Glob", "Grep").
        WithAllowedTools("Read", "Glob", "Grep").
        WithMaxTurns(5)
    result, err := client.Prompt(ctx, client.PromptRequest{
        Prompt: "阅读 README.md，用三句话说明项目用途。不要修改文件。",
        Options: options,
    })
    if err != nil {
        log.Fatal(err)
    }
    if result.IsError {
        log.Fatalf("任务未成功：%s %v", result.Subtype, result.Errors)
    }
    fmt.Println(result.Result)
}

WithTools 选择内置工具集合，WithAllowedTools 配置允许规则。这里同时设置两者，让示例只需要读取材料。权限配置不是操作系统沙箱；生产环境的隔离方法见部署。

运行与验收

go run .

程序会等待首个最终结果，再打印摘要。第一次请求可能包括初始化和模型连接时间。回答内容由模型生成，不会每次相同；验收时确认它引用了 README 中真实存在的信息，且目录没有被修改。

如果程序打印错误，先区分命令未找到、初始化失败和任务失败。不要把错误替换成空字符串后当成正常回答。详见错误处理。

在代码中指定运行时路径

如果部署环境不使用环境变量，可以在 Options 中通过 WithCLIPath 指定 nxs。其余调用代码保持不变。

options := client.NewOptions().
    WithRuntime(client.RuntimeNXS).
    WithCLIPath("/opt/nexus/bin/nxs").
    WithCWD(".").
    WithTools("Read", "Glob", "Grep").
    WithAllowedTools("Read", "Glob", "Grep")

未调用 WithRuntime 时，bridge 同样默认选择 nxs。它不会从 PATH、应用包或缓存中寻找 nxs，因此必须提供路径。需要接入 Claude Code 等第三方异构 Agent 运行时，请阅读运行时与能力协商。

接下来做什么

需要展示执行进度时，把 Prompt 换成流式调用。需要继续追问同一份材料时，使用持久会话。需要查询业务数据时，添加自定义工具，把数据访问范围放在宿主代码中检查。