创建 Agent

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

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
`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，全部配置选项见 API Reference。