> ## 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.

# Agent

> 选择可复用 Agent、流式 Query 和阻塞 Prompt。

# 创建 Agent

`createAgent(options)` 创建带 Session 持久化的可复用 Agent。`agent.query()` 返回异步事件流，`agent.prompt()` 等待任务完成并返回聚合结果。

```typescript theme={null}
import { createAgent } from "@zerone-agent/agent-sdk";

const agent = createAgent({
  agent: {
    prompt: "You are a precise coding assistant.",
    maxTurns: 8,
  },
});

const result = await agent.prompt("解释这个项目的入口。" );
console.log(result.text, result.num_turns);
await agent.close();
```

## Agent 定义

`agent` 选项接受一个 `AgentDefinition`，描述主 Agent 的行为与能力：

| 字段                | 说明                                                                                                                                 |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `prompt`          | 系统提示词                                                                                                                              |
| `appendPrompt`    | 追加到系统提示词的内容                                                                                                                        |
| `maxTurns`        | 最大轮次（默认 `10`）                                                                                                                      |
| `capabilities`    | Agent-local 能力包（`connectionTools` / `customTools` / `skills` / `allowedTools` / `disallowedTools`），见 [Subagent](/zh/sdk/subagents) |
| `availableSkills` | 仅根 Agent 生效、作用于运行时 Skill 注册表的 allowlist                                                                                            |

失效的通配符、零匹配 allowlist 和零 Tool 的 Agent 都会记录警告。

## Agent 方法

| 方法                              | 说明                                           |
| ------------------------------- | -------------------------------------------- |
| `agent.query(prompt)`           | 流式查询，返回 `AsyncGenerator<SDKMessage>`         |
| `agent.prompt(text)`            | 阻塞查询，返回 `Promise<QueryResult>`               |
| `agent.getMessageLog()`         | 所有已发出消息的追加式审计日志                              |
| `agent.compactStream()`         | 手动压缩当前历史（保留尾部），流式发出 `compact` 事件并持久化 Session |
| `agent.compact()`               | `compactStream()` 的非流式封装                     |
| `agent.getMessageHistory()`     | engine 的持久历史（压缩后视图）                          |
| `agent.clear()`                 | 重置 Session                                   |
| `agent.interrupt()`             | 中止当前查询                                       |
| `agent.setModel(model)`         | 在会话中切换模型                                     |
| `agent.setPermissionMode(mode)` | 切换权限模式                                       |
| `agent.getApiType()`            | 获取当前 API 类型                                  |
| `agent.close()`                 | 关闭 MCP 连接并持久化 Session                        |

Agent 使用完后调用 `close()`，让 MCP 连接和 Session 正常收尾。请求方式见 [Query](/zh/sdk/query)，全部配置选项见 [API Reference](/zh/sdk/api-reference)。