后台工作

const result = await api.runtime.hooks.dispatchHookAgentTurn({
  name: "IMAP inbox",
  agentId: "mail",
  sessionKey: "hook:imap:account:123:456",
  message: "Summarize the new email and identify any requested actions.",
  externalContentSource: "email",
  deliver: true,
  thinking: "low", // optional
  timeoutSeconds: 60, // optional
  idempotencyKey: "account:123:456", // optional
});

if (!result.ok) {
  api.logger.warn(`Hook agent turn was rejected: ${result.reason}`);
}

启动并管理后台子代理运行。

对于无需保留会话或回复投递的无工具完成，请使用 `complete(...)`：

```typescript
const { text } = await api.runtime.subagent.complete({
  agentId: "research", // required configured agent that owns this work
  message: "Summarize these notes.",
  extraSystemPrompt: "Return a concise summary.", // optional
  timeoutMs: 30_000, // optional; defaults to 30 seconds
  // model: "openai/gpt-5.6-luna", // optional authorized override
  // signal: abortController.signal, // optional cancellation
});
```

`agentId` 和 `message` 是必填项。`extraSystemPrompt`、`model`、`timeoutMs` 和 `signal` 是可选的。当省略 `model` 时，所选代理提供其配置的默认模型和凭据所有者。结果是 `{ text: string }`；无需创建会话、轮询消息、删除或投递完成。配置的运行时必须支持全新的、无工具的隔离推理；不支持的运行时会在推理前失败。

完成使用 [共享后台队列](../../concepts/queue.md#background-work)，在三次运行的总预算内，每个插件最多三次运行。取消会立即移除排队中的工作。正在运行的工作会保留其槽位，直到底层运行时清理完成，然后拒绝；在取消、超时或运行时退役之后，迟到的输出不会返回。调用需要活动的 Gateway 绑定和插件身份。请求范围内的调用保留调用者的操作员范围和代理访问权限；在操作员工具调用内启动的完成会在该调用结束时取消。模型覆盖保留
现有的子代理授权和下文中的 `allowedModels` 策略。

当你需要会话或代理工具界面时，请使用 `run(...)`：

```typescript
// Start a subagent run
const { runId, sessionKey } = await api.runtime.subagent.run({
  sessionKey: "agent:main:subagent:search-helper",
  message: "Expand this query into focused follow-up searches.",
  toolsAlsoAllow: ["my_plugin_progress"],
  promptMode: "minimal", // optional bounded subagent prompt
  provider: "openai", // optional override
  model: "gpt-6-astra", // optional override
  deliver: false,
  completionDelivery: "current-requester", // optional, before_dispatch hooks only
});

// Wait for completion
const result = await api.runtime.subagent.waitForRun({ runId, timeoutMs: 30000 });

// Read session messages
const { messages } = await api.runtime.subagent.getSessionMessages({
  sessionKey: "agent:main:subagent:search-helper",
  limit: 10,
});

// Delete a session
await api.runtime.subagent.deleteSession({
  sessionKey: "agent:main:subagent:search-helper",
});
```

由 Gateway 支持的运行会返回规范接受的 `sessionKey` 以及 `runId`。该字段在 TypeScript 结果中仅为可选，以便显式自定义运行时保持兼容。

`waitForRun(...)` 返回规范的 Gateway 等待结果。`status` 为 `"ok"`、`"error"`、`"timeout"` 或 `"pending"`；pending 是正常的非终态观察，而不是异常。可选的 `error`、`startedAt`、`endedAt`、`stopReason`、`livenessState`、`yielded`、`pendingError`、`timeoutPhase`、`providerStarted` 和 `terminalReply` 元数据会被保留，以便调用者区分观察超时和终态结果。`timeoutMs` 限定等待调用；它不会取消运行。