SDK 集成

理解 Runtime 如何使用 SDK 定义和执行 Agent。

​

使用 Agent SDK

Runtime 的执行能力来自 @zerone-agent/agent-sdk。简单部署可以使用 agents.yaml；需要自定义 Tool、hook 或代码组合时，使用 TypeScript 配置导入 SDK。

import { createAgent } from "@zerone-agent/agent-sdk";

export const assistant = createAgent({
  model: "claude-sonnet-4-6",
  agent: {
    prompt: "You are a concise assistant.",
    maxTurns: 10,
  },
});

边界建议：SDK 负责 Agent loop、Tool、Provider 和 Session；Runtime 负责 HTTP 协议、认证、运行注册与断连取消。不要在路由层重新实现 SDK 已提供的执行逻辑。

​

以编程方式运行 Runtime

除了 CLI，@zerone-agent/agent-runtime 也可以作为库使用：在代码中创建 Agent、注册到 AgentRegistry，再用 createApp 组装 HTTP 服务。

import { createApp, AgentRegistry, MetricsCollector } from "@zerone-agent/agent-runtime";
import { createAgent } from "@zerone-agent/agent-sdk";
import { serve } from "@hono/node-server";

const agent = createAgent({
  model: "claude-sonnet-4-6",
  systemPrompt: "You are a helpful assistant.",
  maxTurns: 10,
  hooks: {
    PreToolUse: [
      {
        matcher: "Bash",
        hooks: [
          async (input) => {
            console.log(`Running: ${input.toolInput}`);
            return {};
          },
        ],
      },
    ],
  },
});

const registry = new AgentRegistry();
registry.register("my-agent", agent);

const metrics = new MetricsCollector();
const app = createApp(
  {
    server: { host: "0.0.0.0", port: 3000 },
    agents: [{ id: "my-agent", model: "claude-sonnet-4-6" }],
  },
  registry,
  metrics,
);

serve({ fetch: app.fetch, port: 3000 });

要点：

• AgentRegistry.register(id, agent) 把 SDK 创建的 Agent 绑定到运行时 ID，供 HTTP 路由调用。
• createApp(config, registry, metrics) 返回一个标准 fetch 处理器，可交给任意兼容的 Node 服务器（示例使用 @hono/node-server）。
• MetricsCollector 收集运行指标，作为 createApp 的第三个参数传入。

仓库的 examples/programmatic/ 目录提供完整示例，覆盖自定义 Tool、hook、多 Agent 与自定义路由。

下一步：阅读 SDK 快速开始。