@astravia/coding-agent/sdk 是进程内集成入口。它提供类型化 Session、Host 和离线会话目录，不要求通过 CLI 或解析 stdout。
创建最小会话
import { createCodingAgentSession } from "@astravia/coding-agent/sdk";
const { session, diagnostics, modelFallbackMessage } =
await createCodingAgentSession({
cwd: process.cwd(),
storage: { kind: "memory" },
});
for (const diagnostic of diagnostics) {
console.error(diagnostic.code, diagnostic.message);
}
if (modelFallbackMessage) console.warn(modelFallbackMessage);
const unsubscribe = session.subscribe((event) => {
if (event.type === "message_update") {
// Consume typed session events in your own UI or logger.
}
});
try {
await session.prompt("检查当前目录并总结项目结构");
console.log(session.getLastAssistantText());
} finally {
unsubscribe();
await session.close();
}如果没有通过参数、配置或宿主服务得到可用模型，创建会话会抛出带稳定错误码的 CodingAgentSessionCreateError。
选择存储意图
storage.kind | 语义 | 必要参数 |
|---|---|---|
memory | 会话不落盘 | 无 |
file-create | 创建新的会话文件 | conversationDir |
file-resume | 恢复指定会话 | conversationDir、sessionPath |
存储意图应在创建时明确。不要让多个活动 Session 同时写同一个会话文件。
核心生命周期
create→subscribe→prompt / steer / followUp→abort or complete→close
prompt()启动一个正常用户回合。steer()在当前执行中加入引导消息。followUp()将消息放入后续队列。abort()中止当前执行，但仍需调用close()释放会话资源。subscribe()返回取消订阅函数，宿主销毁时必须调用。
Session、Host 与 Catalog
| API | 使用场景 |
|---|---|
createCodingAgentSession() | 单个明确生命周期的活动会话 |
createCodingAgentHost() | 批量持有和关闭多个配置彼此隔离的 Coding Agent Session |
createCodingAgentSessionCatalog() | 离线列出、查询和管理会话元数据 |
Catalog 与活动 Session 分离，不应为了展示会话列表而打开所有会话。
这里的 CodingAgentHost 是 SDK 便利所有权组，不是多主 Agent Registry。每个成员可以有独立 cwd、Storage、Tool、MCP、
Extension Source 和模型资源；若要在一个进程内动态安装、替换或退役不同 agentId，应使用
@astravia/runtime-core 的 RuntimeHost.installAgent()。
可选产品能力
Session 还提供模型和思考档位、工具开关、上下文压缩、自动重试、会话命名、后台任务、子 Agent、待办、MCP 重载、资源重载和 HTML 导出等能力。按需调用，不要在宿主层复制同一状态机。
创建参数可提供：
resources、skillSources、extensionSources：静态或动态能力来源。customTools：类型化自定义工具。askUserQuestion：把模型提问交给宿主 UI。enableBackgroundTasks、enableSubagents、enableMcp：显式启用对应能力。observationHub：把 Agent、RuntimeHost、Tool、MCP、Prompt 与活动 Session 生命周期事件接到本地 Adapter 或上层应用 Hub；Adapter 由调用方持有。env：传入受控环境变量，而不是修改进程全局状态。
错误与关闭
- 在创建阶段读取
diagnostics，不要静默忽略扩展加载失败。 - 订阅 Agent、turn、message、tool、compaction 和 retry 事件，向用户保留终止语义。
- 宿主取消时先
abort()，再等待或关闭会话。 - 将
close()放进finally或宿主生命周期钩子。 - 不从实现目录导入管理器来绕过公共合同。
完整类型以 @astravia/coding-agent/sdk 的声明为准。