@anvia/core 1.1.2 → 1.2.0

package/README.md

@@ -73,6 +73,189 @@ const result = await agent.generate({ prompt: "What is happening with order A123
 if (result.type === "response") console.log(result.output);
 ```
 
+## Agent teams
+
+`AgentTeam` coordinates ordinary `Agent` definitions and gives each spawned instance its own
+conversation and inbox. The coordinator chooses when to spawn members and can create multiple
+instances of the same definition. Tools keep the usual `tools: []` shape; members receive only their
+own configured tools and the runtime's communication tools.
+
+```ts
+import { Agent, AgentTeam } from "@anvia/core/agent";
+
+// model, readFileTool, and searchTool are application-owned objects.
+const researcher = new Agent({
+  id: "researcher",
+  model,
+  description: "Research a specific question and report evidence.",
+  instructions: "Ask your parent for clarification when needed.",
+  tools: [readFileTool, searchTool],
+});
+
+const reviewer = new Agent({
+  id: "reviewer",
+  model,
+  description: "Review findings for errors and unsupported claims.",
+  tools: [readFileTool],
+});
+
+const team = new AgentTeam({
+  id: "research-team",
+  model,
+  instructions: [
+    "Delegate research to researcher instances.",
+    "Send their findings to a reviewer and incorporate its feedback.",
+    "Answer the user after the work is complete.",
+  ].join("\n"),
+  members: [researcher, reviewer],
+  limits: {
+    maxDepth: 3,
+    maxConcurrentAgents: 4,
+    maxAgentInstances: 12,
+    maxTotalTurns: 100,
+    maxBufferedEvents: 1024,
+  },
+});
+
+const result = await team.generate({ prompt: "Investigate the proposed architecture." });
+if (result.type === "response") console.log(result.output);
+console.log(result.teamRunId, result.usage, result.members);
+```
+
+The coordinator supports normal Agent configuration, including `outputSchema`, context, tools,
+guardrails, middleware, and lifecycle callbacks. Its schema determines the team's output type.
+Each member preserves its own configuration. Run-level options apply to the coordinator; the
+abort signal, interaction resolver, and team limits apply to the whole execution.
+
+The runtime adds these model-callable tools:
+
+| Tool                | Available to                      | Input                         |
+| ------------------- | --------------------------------- | ----------------------------- |
+| `spawn_<member.id>` | Coordinator and permitted parents | `{ prompt, name? }`           |
+| `send_message`      | All instances                     | `{ to, content, replyTo? }`   |
+| `wait_for_agent`    | All instances                     | `{ instanceId?, timeoutMs? }` |
+| `list_agents`       | All instances                     | `{}`                          |
+| `cancel_agent`      | Instances with spawn permissions  | `{ instanceId, reason? }`     |
+
+Spawning returns an `instanceId` immediately. A definition's `agentId` stays the same across its
+instances; each assignment or resumed interaction has a distinct `runId`. Member IDs must contain
+1–58 letters, digits, underscores, or hyphens so generated tool names are valid. Configured tools
+must not use reserved coordination names.
+
+Routing is between a parent and its children by default. A member can use `to: "parent"`;
+parents address children by instance ID. Enable sibling communication and recursive spawning
+with explicit permissions:
+
+```ts
+const team = new AgentTeam({
+  id: "research-team",
+  model,
+  members: [researcher, reviewer],
+  communication: { siblings: true },
+  spawning: [{ from: researcher, to: [researcher, reviewer] }],
+  limits: { maxDepth: 3, maxConcurrentAgents: 4, maxAgentInstances: 12, maxTotalTurns: 100 },
+});
+```
+
+`members` is the definition catalog available to the coordinator. A spawn rule allows every
+instance of `from` to create only the definitions in `to`, using their generated spawn tools.
+Use the same Agent objects registered in `members`; duplicate rules or targets are rejected.
+Rules and communication options are snapshotted at construction. Without rules, only the
+coordinator can spawn. A self-reference enables recursion; each child has its own conversation
+and its definition's tools, without inheriting the parent's tools.
+
+With `communication.siblings: true`, instances sharing the same parent instance can discover,
+message, and wait for one another. Cousins and other branches remain inaccessible. `list_agents`
+includes self, parent, direct children, and enabled siblings, with `parentInstanceId` and `depth`.
+Sibling access does not grant cancellation or approval authority. Only a parent can cancel its
+direct child; cancellation also stops that child's entire subtree, including idle descendants.
+
+`send_message` returns a queued receipt, not a reply. Messages arrive at safe turn/tool boundaries,
+are explicitly attributed to their sender, and cannot satisfy a tool approval. Sending to an idle
+member starts a follow-up run with its retained conversation. Failed or cancelled members cannot
+receive follow-ups. Each inbox accepts at most 128 pending inputs.
+
+`wait_for_agent` wakes on a relevant message, outcome, cancellation, or timeout (default 30 seconds,
+maximum 5 minutes). Waiting agents and agents awaiting application input release their concurrency
+slot. Every parent waits automatically for its own children before finalizing and receives their
+outcomes as attributed messages. A member failure is reported to its immediate parent; failure or
+blocking cancels its descendants. A coordinator error or team cancellation rejects the execution.
+Guardrail blocking remains a `blocked` outcome. The final `members` array includes all descendants,
+with `parentInstanceId` and `depth` to reconstruct the tree.
+
+The limits in the first example are the defaults. `maxDepth` is a positive integer; the coordinator
+is depth 0 and direct children are depth 1. Concurrent and total instance limits include the coordinator.
+The instance limit counts all instances created during this execution, including completed or
+cancelled ones. The turn budget covers all instances and follow-ups; provider retries remain
+governed by normal retry settings. Reaching the turn budget fails the team. Reaching the instance
+or depth limit rejects the spawn tool call so the parent can use existing members. All budgets are
+shared across the whole tree; spawning does not reset them. Tools within one
+instance execute sequentially; different instances can execute concurrently.
+
+### Team streaming and steering
+
+```ts
+const stream = team.stream({ prompt: "Investigate the proposed architecture." });
+
+// Call from the application's user-input handler while the team is running:
+// stream.steer({ prompt: "Also consider deployment complexity." });
+// stream.cancel("User cancelled.");
+
+for await (const event of stream.events) {
+  if (event.type === "agent_event" && event.event.type === "text_delta") {
+    console.log(event.instanceId, event.event.delta);
+  }
+}
+const outcome = await stream.result;
+```
+
+`events` is an attributed union of agent events, member state changes, queued/delivered messages,
+interactions, and the terminal team outcome. New members emit `agent_queued` before acquiring a
+concurrency slot. `textStream` yields coordinator text only, including
+provisional turns before its final answer. `text` resolves to the final text. Choose one event or text
+consumer; final promises can be read alongside it. Reading only a final promise consumes the run
+without buffering unused events. Non-streaming models also work and emit complete response text
+instead of provider deltas. Closing the event iterator cancels unfinished work.
+
+Streaming buffers at most `limits.maxBufferedEvents` unread events (default 1,024). If a consumer
+falls behind and fills that buffer, the team cancels its running work, discards unread events, and
+rejects both the iterator and final promises with `AgentTeamLimitError` whose `limit` is
+`"maxBufferedEvents"`. This bounds queued event count, not the byte size of individual events.
+Increase the limit when your application needs to tolerate longer pauses between reads.
+Result-only consumption does not buffer events and is unaffected by this limit.
+
+### Team approvals and questions
+
+Only the application resolves interactions. A coordinator or reviewer cannot approve another
+member's protected tool through a message. Existing tool `requiresApproval` and question tools use
+the same interaction contracts as `Agent`:
+
+```ts
+import type { AgentTeamInteraction } from "@anvia/core/agent";
+import type { AgentInteractionResponse } from "@anvia/core/agent/interactions";
+
+// Implement this with your application's authenticated approval/question UI.
+declare function askUser(request: AgentTeamInteraction): Promise<AgentInteractionResponse>;
+
+const result = await team.generate({
+  prompt: "Investigate and propose changes.",
+  resolveInteraction: (request) => askUser(request),
+});
+```
+
+The resolver receives `teamRunId`, `instanceId`, `runId`, the interaction request, and an abort
+signal. A missing, throwing, or invalid resolver fails the team with `AgentTeamInteractionError`
+before the protected action executes. Approval denial follows the ordinary Agent behavior: the
+tool is skipped and its member can continue. Other members may continue while an interaction is
+pending. The application must decide who may approve; agent-generated content is not authorization.
+
+Teams currently live in one process for one execution. Each `generate` or `stream` call creates
+fresh instances. Pass `messages` instead of `prompt` to supply coordinator history. Member
+conversations are retained only within that execution; team session persistence and durable
+checkpoint/resume are not provided. Cancellation signals reach running models, tools, and
+resolvers; work owned by the application must honor its signal to stop external activity.
+Studio provides a team playground with member activity, messages, and approval/question controls.
+
 ## Direct Completions
 
 Use `generateCompletion` for one provider call without Agent turns, memory, or local tool
@@ -355,6 +538,39 @@ Pass `abortSignal` on a run to cancel the active provider call, tools, and neste
 Run observers receive terminal errors with `status: "cancelled"` for cancellation and
 `status: "failed"` for other failures.
 
+### Prompt attribution
+
+Set `trace.promptRef` on `generate()` or `stream()` to identify the prompt used by a run and
+default its generation attribution. The core `AgentRunPromptRef` contract is
+`{ readonly name: string; readonly version?: number }`; use the registry's resolved numeric version
+when available, not the requested label. This identity does not contain templates or variables.
+
+For runs that change prompts between turns, completion-request middleware is the explicit
+generation override boundary:
+
+```ts
+await agent.generate({
+  prompt: "Summarize the ticket",
+  trace: { promptRef: { name: "support", version: 7 } },
+  middlewares: [
+    {
+      onCompletionRequest: ({ request, turn }) => {
+        if (turn === 0) {
+          return { request, promptRef: { name: "planner", version: 3 } };
+        }
+        return { request, promptRef: null };
+      },
+    },
+  ],
+});
+```
+
+The middleware receives the current `promptRef`. Returning a reference overrides that generation;
+`null` clears it, while omission preserves it. Each turn starts again with the run default, and
+later middleware sees earlier overrides. Set attribution alongside any request changes that select
+another prompt: attribution itself does not change the model input. It is a runtime side channel,
+not a provider request field or global current-prompt setting.
+
 ## Memory
 
 Configure durable conversation memory on the Agent, then run through a session:
@@ -565,6 +781,11 @@ enabled.
 `"throw"` and defaults to `"ignore"`. With `"throw"`, the run rejects with a
 `PipelineObserverDispatchError` containing the failed phase and per-observer failures.
 
+Pipeline run and batch options also accept `trace.promptRef`. This identifies the pipeline root;
+it does not stamp every stage or Agent with that prompt. Select each Agent's relevant prompt with
+`request: ({ input }) => ({ prompt: input, trace: { promptRef } })`, especially when a pipeline uses
+multiple prompts. Trace parent propagation and prompt identity are independent.
+
 ## Documents
 
 Applications own file discovery, file reads, document parsing, source metadata, and per-file error
@@ -693,6 +914,11 @@ Metrics that implicitly read `case.expected`, `case.context`, or `case.retrieval
 those fields at compile time. Supplying an explicit metric value or selector removes the matching
 case requirement.
 
+Set `run: { promptRef: { name: "support", version: 7 } }` on `runEvalSuite()` to attribute the
+evaluation run. The reference is preserved in `result.run` and the reporter's run-start, per-metric,
+and run-end contexts. It does not automatically attribute the target Agent or judge generations;
+configure those runs' `trace.promptRef` separately when relevant.
+
 ### Built-in metrics
 
 Deterministic metrics do not call a model:

package/dist/agent/agent-stream.js

@@ -0,0 +1,7 @@
+import {
+  createAgentStream
+} from "../chunk-KY4VXIN2.js";
+export {
+  createAgentStream
+};
+//# sourceMappingURL=agent-stream.js.map

package/dist/agent/agent-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/agent/agent-tool.js

@@ -0,0 +1,24 @@
+import {
+  createAgentTool
+} from "../chunk-PPJ7SYQL.js";
+import "../chunk-BDKFFFVX.js";
+import "../chunk-CKKNO4XB.js";
+import "../chunk-4ONUNWGC.js";
+import "../chunk-UTAB3XQI.js";
+import "../chunk-XQV3XNVT.js";
+import "../chunk-XV3DH5GC.js";
+import "../chunk-YZVFIW5D.js";
+import "../chunk-MHOJJYDK.js";
+import "../chunk-47NTHIVB.js";
+import "../chunk-J6S6MT7O.js";
+import "../chunk-IDNL6IH4.js";
+import "../chunk-BONQTXRQ.js";
+import "../chunk-4C7AXYOM.js";
+import "../chunk-SQAAVYJG.js";
+import "../chunk-POXHJF3H.js";
+import "../chunk-USRKPEQN.js";
+import "../chunk-WN6AVBO4.js";
+export {
+  createAgentTool
+};
+//# sourceMappingURL=agent-tool.js.map

package/dist/agent/agent-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/agent/agent.js

@@ -0,0 +1,89 @@
+import {
+  Agent
+} from "../chunk-B5YTCKUJ.js";
+import "../chunk-RT5LUEO3.js";
+import "../chunk-GDY2Z2SZ.js";
+import "../chunk-KITX3HDN.js";
+import "../chunk-NPJ2T3L5.js";
+import "../chunk-YWRXOPHC.js";
+import "../chunk-SXE4J43E.js";
+import "../chunk-J4SINPUA.js";
+import "../chunk-5I2NVRHC.js";
+import "../chunk-5IURMWFN.js";
+import "../chunk-LAIATEUB.js";
+import "../chunk-F3E2RLC7.js";
+import "../chunk-JMJFK3A4.js";
+import "../chunk-6N4ENZO4.js";
+import "../chunk-4AW2633B.js";
+import "../chunk-IV6YQTY2.js";
+import "../chunk-2NLINXRF.js";
+import "../chunk-XJRNBTIV.js";
+import "../chunk-H3H74RWJ.js";
+import "../chunk-HP34GRQX.js";
+import "../chunk-LQJ4KHMY.js";
+import "../chunk-MJCMKZFP.js";
+import "../chunk-EZR5AV3J.js";
+import "../chunk-OJF67RNM.js";
+import "../chunk-FAPIZJS2.js";
+import "../chunk-7LBPRXZP.js";
+import "../chunk-JB3RFK6K.js";
+import "../chunk-A7BXVZXZ.js";
+import "../chunk-TP3MCUXS.js";
+import "../chunk-6RQYWZI3.js";
+import "../chunk-NF6WBPFG.js";
+import "../chunk-LBYJPMHC.js";
+import "../chunk-KFAVEL5F.js";
+import "../chunk-GLMYZ6OA.js";
+import "../chunk-7KAGWJ5M.js";
+import "../chunk-K4IBS7VB.js";
+import "../chunk-ZPJFXRQZ.js";
+import "../chunk-MEN4AFDZ.js";
+import "../chunk-VZ5ZZBNX.js";
+import "../chunk-6TAWRKFK.js";
+import "../chunk-6BTJC3ES.js";
+import "../chunk-MT3BLVYN.js";
+import "../chunk-ZXLCTQUX.js";
+import "../chunk-23GEYG2X.js";
+import "../chunk-RXKUIJ77.js";
+import "../chunk-5WLIHNNJ.js";
+import "../chunk-QHGYCYV6.js";
+import "../chunk-ESOFEAYK.js";
+import "../chunk-HAAGSIZH.js";
+import "../chunk-PJNE75WC.js";
+import "../chunk-PLDJCCVL.js";
+import "../chunk-3J2CSVPR.js";
+import "../chunk-ERN7P6Q4.js";
+import "../chunk-7F53DOML.js";
+import "../chunk-HHMLE3TZ.js";
+import "../chunk-DU4WA6LQ.js";
+import "../chunk-4FIVU53H.js";
+import "../chunk-KO5NMTAM.js";
+import "../chunk-TFIOU6UR.js";
+import "../chunk-GPVXCY5I.js";
+import "../chunk-NVALGVQG.js";
+import "../chunk-ZHC5CD6J.js";
+import "../chunk-5V533R7F.js";
+import "../chunk-KY4VXIN2.js";
+import "../chunk-PPJ7SYQL.js";
+import "../chunk-BDKFFFVX.js";
+import "../chunk-CKKNO4XB.js";
+import "../chunk-4ONUNWGC.js";
+import "../chunk-UTAB3XQI.js";
+import "../chunk-XQV3XNVT.js";
+import "../chunk-XV3DH5GC.js";
+import "../chunk-YZVFIW5D.js";
+import "../chunk-MHOJJYDK.js";
+import "../chunk-47NTHIVB.js";
+import "../chunk-J6S6MT7O.js";
+import "../chunk-IDNL6IH4.js";
+import "../chunk-BONQTXRQ.js";
+import "../chunk-4C7AXYOM.js";
+import "../chunk-SQAAVYJG.js";
+import "../chunk-POXHJF3H.js";
+import "../chunk-USRKPEQN.js";
+import "../chunk-WN6AVBO4.js";
+import "../chunk-KBBQSP4M.js";
+export {
+  Agent
+};
+//# sourceMappingURL=agent.js.map

package/dist/agent/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/agent/errors.js

@@ -0,0 +1,17 @@
+import {
+  AgentRunBlockedError,
+  AgentRunCancelledError,
+  AgentStreamClosedError,
+  AgentStructuredOutputError,
+  AgentToolSuspensionError,
+  MaxTurnsError
+} from "../chunk-WN6AVBO4.js";
+export {
+  AgentRunBlockedError,
+  AgentRunCancelledError,
+  AgentStreamClosedError,
+  AgentStructuredOutputError,
+  AgentToolSuspensionError,
+  MaxTurnsError
+};
+//# sourceMappingURL=errors.js.map

package/dist/agent/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/agent/ids.js

@@ -0,0 +1,7 @@
+import {
+  normalizeAgentId
+} from "../chunk-KBBQSP4M.js";
+export {
+  normalizeAgentId
+};
+//# sourceMappingURL=ids.js.map

package/dist/agent/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/agent/index.d.ts

@@ -1,23 +1,141 @@
 export { M as ModelCallOptions } from '../model-call-options-CZkSw_xN.js';
 export { R as RetryContext, a as RetryOptions, b as RetrySetting } from '../retry-CjvSlKGW.js';
-export { A as Agent, a as AgentContextInput, b as AgentMemory, c as AgentMemoryOptions, d as AgentOptions, e as AgentToolInput, f as AgentToolOptions, C as CreateHybridVectorContextOptions, g as CreateVectorContextOptions, V as VectorContext, h as VectorContextBaseOptions, i as createVectorContext, j as isVectorContext } from '../agent-DTmzs1Qr.js';
-import { M as Message, U as Usage, c as CompletionFinishReason } from '../types-CiHjqE6J.js';
-import { A as AgentBlockedOutcome, g as AgentInteractionOutcome } from '../types-CRda8x7p.js';
-export { a as AgentChildStreamEvent, b as AgentDeltaEvent, c as AgentErrorEvent, d as AgentErrorStreamEvent, e as AgentFinishEvent, f as AgentInput, h as AgentLifecycle, i as AgentMemoryCompactionEvent, j as AgentMemoryCompactionOptions, k as AgentOutcome, l as AgentPrompt, m as AgentResponse, n as AgentRunOptions, o as AgentRunSettings, p as AgentStartEvent, q as AgentSteerInput, r as AgentSteerReceipt, s as AgentStepFinishEvent, t as AgentStream, u as AgentStreamEvent, v as AgentToolCallDeltaEvent, w as AgentToolFinishEvent, x as AgentToolStartEvent } from '../types-CRda8x7p.js';
+import { A as Agent, d as AgentOptions } from '../agent-C9VhENdj.js';
+export { a as AgentContextInput, b as AgentMemory, c as AgentMemoryOptions, e as AgentToolInput, f as AgentToolOptions, C as CreateHybridVectorContextOptions, g as CreateVectorContextOptions, V as VectorContext, h as VectorContextBaseOptions, i as createVectorContext, j as isVectorContext } from '../agent-C9VhENdj.js';
+import { d as CompletionModel, f as CompletionModelControlsOf, M as Message, U as Usage, c as CompletionFinishReason } from '../types-CiHjqE6J.js';
+import { AgentInteractionRequest, AgentInteractionResponse } from './interactions/index.js';
+import { p as AgentRunSettings, m as AgentPrompt, n as AgentResponse, A as AgentBlockedOutcome, v as AgentStreamEvent, r as AgentSteerInput, s as AgentSteerReceipt, g as AgentInteractionOutcome } from '../middleware-CWjnMbiH.js';
+export { a as AgentChildStreamEvent, b as AgentDeltaEvent, c as AgentErrorEvent, d as AgentErrorStreamEvent, e as AgentFinishEvent, f as AgentInput, h as AgentLifecycle, i as AgentMemoryCompactionEvent, j as AgentMemoryCompactionOptions, l as AgentOutcome, o as AgentRunOptions, q as AgentStartEvent, t as AgentStepFinishEvent, u as AgentStream, w as AgentToolCallDeltaEvent, x as AgentToolFinishEvent, y as AgentToolStartEvent } from '../middleware-CWjnMbiH.js';
 import '../zod-schema-C7F4clpm.js';
 import 'zod';
-import '../types-h0EL6Xn0.js';
-import '../type-utils-CtHVDRn_.js';
+import '../types-Bqw0AuFl.js';
 import '../types-DfRPfehE.js';
 import '../tool-DQMZpZSS.js';
 import '../types-CafU6Ux5.js';
-import '../middleware-mY_lpjDp.js';
-import './interactions/index.js';
 import '../types-C1xYKXF2.js';
 import '../dynamic-tools-CNHSPXr1.js';
 import '../types-Cr4uiYo5.js';
 import '../types-CODGMHnp.js';
 
+/** An Agent definition; individual members may have different output schemas. */
+type AgentTeamMember = Agent<unknown>;
+/** Allow instances of one registered definition to spawn the listed definitions. */
+type AgentTeamSpawnRule = {
+    from: AgentTeamMember;
+    to: readonly AgentTeamMember[];
+};
+type RawResponseOf<Model> = Model extends CompletionModel<infer RawResponse> ? RawResponse : unknown;
+type AgentTeamLimits = {
+    /** Maximum instance depth, with the coordinator at 0. Defaults to 3. */
+    maxDepth?: number;
+    maxConcurrentAgents?: number;
+    maxAgentInstances?: number;
+    maxTotalTurns?: number;
+    /** Maximum unread stream events. Overflow fails and cancels the team. Defaults to 1024. */
+    maxBufferedEvents?: number;
+};
+type AgentTeamOptions<Output = string, M extends CompletionModel = CompletionModel, ContextDocument = unknown> = AgentOptions<Output, M, ContextDocument> & {
+    members: readonly AgentTeamMember[];
+    /** Allow messaging and waiting between instances with the same parent. Defaults to false. */
+    communication?: {
+        siblings?: boolean;
+    };
+    /** Additional spawn permissions for members. The coordinator can spawn every member. */
+    spawning?: readonly AgentTeamSpawnRule[];
+    limits?: AgentTeamLimits;
+};
+type AgentTeamInteraction = {
+    teamRunId: string;
+    instanceId: string;
+    runId: string;
+    interaction: AgentInteractionRequest;
+    abortSignal: AbortSignal;
+};
+type AgentTeamRunOptions<Output = string, M extends CompletionModel = CompletionModel> = Omit<AgentRunSettings<Output, RawResponseOf<M>, CompletionModelControlsOf<M>>, "toolConcurrency"> & ({
+    prompt: AgentPrompt;
+    messages?: never;
+} | {
+    messages: readonly Message[];
+    prompt?: never;
+}) & {
+    resolveInteraction?: (request: AgentTeamInteraction) => AgentInteractionResponse | Promise<AgentInteractionResponse>;
+};
+type AgentTeamMemberStatus = "queued" | "running" | "waiting" | "awaiting_interaction" | "idle" | "failed" | "cancelled";
+type AgentTeamMemberSummary = Readonly<{
+    instanceId: string;
+    agentId: string;
+    name: string;
+    parentInstanceId?: string;
+    depth: number;
+    status: AgentTeamMemberStatus;
+    usage: Usage;
+    outcome?: AgentResponse<unknown> | AgentBlockedOutcome;
+    error?: unknown;
+}>;
+type AgentTeamOutcome<Output = string> = (AgentResponse<Output> | AgentBlockedOutcome) & {
+    teamRunId: string;
+    /** Aggregate usage across every member run, including the coordinator. */
+    usage: Usage;
+    members: readonly AgentTeamMemberSummary[];
+};
+type AgentTeamMessage = Readonly<{
+    id: string;
+    teamRunId: string;
+    fromInstanceId: string;
+    toInstanceId: string;
+    content: string;
+    replyTo?: string;
+    createdAt: string;
+}>;
+type TeamEventIdentity = {
+    teamRunId: string;
+    instanceId: string;
+    runId?: string;
+};
+type AgentTeamEvent<Output = string> = (TeamEventIdentity & {
+    type: "agent_queued" | "agent_started" | "agent_waiting" | "agent_idle" | "agent_failed" | "agent_cancelled";
+    member: AgentTeamMemberSummary;
+}) | (TeamEventIdentity & {
+    type: "message_queued" | "message_delivered";
+    message: AgentTeamMessage;
+}) | (TeamEventIdentity & {
+    type: "interaction";
+    interaction: AgentInteractionRequest;
+}) | (TeamEventIdentity & {
+    type: "agent_event";
+    coordinator: boolean;
+    event: AgentStreamEvent<unknown>;
+}) | AgentTeamOutcome<Output>;
+interface AgentTeamStream<Output = string> extends AsyncIterable<AgentTeamEvent<Output>> {
+    readonly events: AsyncIterable<AgentTeamEvent<Output>>;
+    readonly textStream: AsyncIterable<string>;
+    readonly text: Promise<string>;
+    readonly result: Promise<AgentTeamOutcome<Output>>;
+    steer(input: AgentSteerInput): AgentSteerReceipt;
+    cancel(reason?: string): void;
+}
+
+declare class AgentTeam<Output = string, M extends CompletionModel = CompletionModel, ContextDocument = unknown> {
+    readonly id: string;
+    readonly members: readonly AgentTeamMember[];
+    readonly limits: Readonly<Required<AgentTeamLimits>>;
+    private readonly coordinator;
+    private readonly policy;
+    constructor(options: AgentTeamOptions<Output, M, ContextDocument>);
+    generate(options: AgentTeamRunOptions<Output, M>): Promise<AgentTeamOutcome<Output>>;
+    stream(options: AgentTeamRunOptions<Output, M>): AgentTeamStream<Output>;
+    private createStream;
+}
+
+declare class AgentTeamLimitError extends Error {
+    readonly limit: string;
+    constructor(limit: string);
+}
+declare class AgentTeamInteractionError extends Error {
+    readonly instanceId: string;
+    constructor(instanceId: string, options?: ErrorOptions);
+}
+
 type AgentStructuredOutputPhase = "truncated" | "content-filter" | "parse" | "schema";
 type AgentStructuredOutputFormat = "raw" | "json-fence" | "unlabeled-fence";
 declare class AgentStructuredOutputError extends Error {
@@ -68,4 +186,4 @@ declare class AgentToolSuspensionError extends Error {
     constructor(result: AgentInteractionOutcome);
 }
 
-export { AgentBlockedOutcome, AgentInteractionOutcome, AgentRunBlockedError, AgentRunCancelledError, AgentStreamClosedError, AgentStructuredOutputError, type AgentStructuredOutputFormat, type AgentStructuredOutputPhase, AgentToolSuspensionError, MaxTurnsError };
+export { Agent, AgentBlockedOutcome, AgentInteractionOutcome, AgentOptions, AgentPrompt, AgentResponse, AgentRunBlockedError, AgentRunCancelledError, AgentRunSettings, AgentSteerInput, AgentSteerReceipt, AgentStreamClosedError, AgentStreamEvent, AgentStructuredOutputError, type AgentStructuredOutputFormat, type AgentStructuredOutputPhase, AgentTeam, type AgentTeamEvent, type AgentTeamInteraction, AgentTeamInteractionError, AgentTeamLimitError, type AgentTeamLimits, type AgentTeamMember, type AgentTeamMemberStatus, type AgentTeamMemberSummary, type AgentTeamMessage, type AgentTeamOptions, type AgentTeamOutcome, type AgentTeamRunOptions, type AgentTeamSpawnRule, type AgentTeamStream, AgentToolSuspensionError, MaxTurnsError };