> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zerone.run/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK 集成

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

# 使用 Agent SDK

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

```typescript theme={null}
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 服务。

```typescript theme={null}
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` 的第三个参数传入。

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

下一步：[阅读 SDK 快速开始](/zh/sdk/quickstart)。