Skip to content
// EFFECT DAYS 2026

AgUi

Converts between effect/ai values and the Agent User Interaction (AG-UI) protocol.

An AG-UI run starts from a RunAgentInput and answers with a stream of events. This module turns the input's conversation into a Prompt, turns the parts streamed by LanguageModel.streamText into AG-UI events, and wraps an event stream in the run lifecycle that AG-UI clients expect. It performs no I/O; AgUiServer serves runs over HTTP.

Example Streaming a model response as AG-UI events 

import { Stream } from "effect"
import { AgUi, LanguageModel } from "effect/ai"
import type { AgUiSchema } from "effect/ai"


const run = (input: AgUiSchema.RunAgentInput) =>
  LanguageModel.streamText({ prompt: AgUi.toPrompt(input) }).pipe(
    AgUi.fromStreamParts,
    AgUi.withRunLifecycle(input)
  )
3 exports Since v4.1.0 Source

Combinators

withRunLifecycle

Since v4.1.0

Wraps a stream of AG-UI events in the lifecycle of one run.

When to use

Use with fromStreamParts or with any hand-written event stream, so clients always see a well-formed run.

Details

  • RUN_STARTED is emitted first, with the run's ids and the protocol version. RUN_STARTED events from the input stream are dropped.
  • When the input stream ends, any text message, tool call, reasoning span, step, or subagent it left open is closed, most recently opened first, and RUN_FINISHED is emitted. Closing events keep the subagentRunId of the event they close, steps are matched by name within each subagent, and a subagent left running ends with a SUBAGENT_ERROR.
  • A RUN_FINISHED from the input stream ends the run, after closing anything left open, so a stream can report its own outcome. A RUN_ERROR from the input stream also ends the run.
  • When the input stream fails, the cause is logged and reported, and the run ends with a RUN_ERROR whose message carries no error details. Interruptions are not converted.

Gotchas

To send a specific error to the client, emit a RUN_ERROR event from the input stream instead of failing it.

See

Signature

declare function withRunLifecycle(run: {
  readonly runId: string;
  readonly threadId: string;
}): <E, R>(self: Stream<{
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly name?: string;
  readonly rawEvent?: unknown;
  readonly role?: "developer" | "system" | "assistant" | "user";
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "TEXT_MESSAGE_START";
} | {
  readonly delta: string;
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "TEXT_MESSAGE_CONTENT";
} | {
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "TEXT_MESSAGE_END";
} | {
  readonly delta?: string;
  readonly messageId?: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly name?: string;
  readonly rawEvent?: unknown;
  readonly role?: "developer" | "system" | "assistant" | "user";
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "TEXT_MESSAGE_CHUNK";
} | {
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly parentMessageId?: string;
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly toolCallId: string;
  readonly toolCallName: string;
  readonly type: "TOOL_CALL_START";
} | {
  readonly delta: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly toolCallId: string;
  readonly type: "TOOL_CALL_ARGS";
} | {
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly toolCallId: string;
  readonly type: "TOOL_CALL_END";
} | {
  readonly delta?: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly parentMessageId?: string;
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly toolCallId?: string;
  readonly toolCallName?: string;
  readonly type: "TOOL_CALL_CHUNK";
} | {
  readonly content: string | readonly Array<{
    readonly id?: string;
    readonly metadata?: unknown;
    readonly text: string;
    readonly type: "text";
  } | {
    readonly id?: string;
    readonly metadata?: unknown;
    readonly source: {
      readonly mimeType: string;
      readonly type: "data";
      readonly value: string;
    } | {
      readonly mimeType?: ... | ...;
      readonly type: "url";
      readonly value: string;
    } | {
      readonly mimeType?: ... | ...;
      readonly provider?: ... | ...;
      readonly type: "file";
      readonly value: string;
    };
    readonly type: "image";
  } | {
    readonly id?: string;
    readonly metadata?: unknown;
    readonly source: {
      readonly mimeType: string;
      readonly type: "data";
      readonly value: string;
    } | {
      readonly mimeType?: ... | ...;
      readonly type: "url";
      readonly value: string;
    } | {
      readonly mimeType?: ... | ...;
      readonly provider?: ... | ...;
      readonly type: "file";
      readonly value: string;
    };
    readonly type: "audio";
  } | {
    readonly id?: string;
    readonly metadata?: unknown;
    readonly source: {
      readonly mimeType: string;
      readonly type: "data";
      readonly value: string;
    } | {
      readonly mimeType?: ... | ...;
      readonly type: "url";
      readonly value: string;
    } | {
      readonly mimeType?: ... | ...;
      readonly provider?: ... | ...;
      readonly type: "file";
      readonly value: string;
    };
    readonly type: "video";
  } | {
    readonly id?: string;
    readonly metadata?: unknown;
    readonly source: {
      readonly mimeType: string;
      readonly type: "data";
      readonly value: string;
    } | {
      readonly mimeType?: ... | ...;
      readonly type: "url";
      readonly value: string;
    } | {
      readonly mimeType?: ... | ...;
      readonly provider?: ... | ...;
      readonly type: "file";
      readonly value: string;
    };
    readonly type: "document";
  }>;
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly role?: "tool";
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly toolCallId: string;
  readonly type: "TOOL_CALL_RESULT";
} | {
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly snapshot: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "STATE_SNAPSHOT";
} | {
  readonly delta: readonly Array<{
    readonly op: "add";
    readonly path: string;
    readonly value: unknown;
  } | {
    readonly op: "remove";
    readonly path: string;
  } | {
    readonly op: "replace";
    readonly path: string;
    readonly value: unknown;
  } | {
    readonly from: string;
    readonly op: "move";
    readonly path: string;
  } | {
    readonly from: string;
    readonly op: "copy";
    readonly path: string;
  } | {
    readonly op: "test";
    readonly path: string;
    readonly value: unknown;
  }>;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "STATE_DELTA";
} | {
  readonly messages: readonly Array<{
    readonly content: string;
    readonly encryptedValue?: string;
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly name?: string;
    readonly role: "developer";
    readonly subagentRunId?: string;
  } | {
    readonly content: string;
    readonly encryptedValue?: string;
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly name?: string;
    readonly role: "system";
    readonly subagentRunId?: string;
  } | {
    readonly content?: string;
    readonly encryptedValue?: string;
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly name?: string;
    readonly role: "assistant";
    readonly subagentRunId?: string;
    readonly toolCalls?: readonly Array<{
      readonly encryptedValue?: ... | ...;
      readonly function: {
        readonly arguments: ...;
        readonly name: ...;
      };
      readonly id: string;
      readonly metadata?: ... | ...;
      readonly type: "function";
    }>;
  } | {
    readonly content: string | readonly Array<{
      readonly id?: ...;
      readonly metadata?: ...;
      readonly text: ...;
      readonly type: ...;
    } | {
      readonly id?: ...;
      readonly metadata?: ...;
      readonly source: ...;
      readonly type: ...;
    } | {
      readonly id?: ...;
      readonly metadata?: ...;
      readonly source: ...;
      readonly type: ...;
    } | {
      readonly id?: ...;
      readonly metadata?: ...;
      readonly source: ...;
      readonly type: ...;
    } | {
      readonly id?: ...;
      readonly metadata?: ...;
      readonly source: ...;
      readonly type: ...;
    }>;
    readonly encryptedValue?: string;
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly name?: string;
    readonly role: "user";
    readonly subagentRunId?: string;
  } | {
    readonly content: string | readonly Array<{
      readonly id?: ...;
      readonly metadata?: ...;
      readonly text: ...;
      readonly type: ...;
    } | {
      readonly id?: ...;
      readonly metadata?: ...;
      readonly source: ...;
      readonly type: ...;
    } | {
      readonly id?: ...;
      readonly metadata?: ...;
      readonly source: ...;
      readonly type: ...;
    } | {
      readonly id?: ...;
      readonly metadata?: ...;
      readonly source: ...;
      readonly type: ...;
    } | {
      readonly id?: ...;
      readonly metadata?: ...;
      readonly source: ...;
      readonly type: ...;
    }>;
    readonly encryptedValue?: string;
    readonly error?: string;
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly role: "tool";
    readonly subagentRunId?: string;
    readonly toolCallId: string;
  } | {
    readonly activityType: string;
    readonly content: {
      [key: string]: unknown;
    };
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly role: "activity";
    readonly subagentRunId?: string;
  } | {
    readonly content: string;
    readonly encryptedValue?: string;
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly role: "reasoning";
    readonly subagentRunId?: string;
  }>;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly timestamp?: number;
  readonly type: "MESSAGES_SNAPSHOT";
} | {
  readonly activityType: string;
  readonly content: {
    [key: string]: unknown;
  };
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly replace?: boolean;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "ACTIVITY_SNAPSHOT";
} | {
  readonly activityType: string;
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly patch: readonly Array<{
    readonly op: "add";
    readonly path: string;
    readonly value: unknown;
  } | {
    readonly op: "remove";
    readonly path: string;
  } | {
    readonly op: "replace";
    readonly path: string;
    readonly value: unknown;
  } | {
    readonly from: string;
    readonly op: "move";
    readonly path: string;
  } | {
    readonly from: string;
    readonly op: "copy";
    readonly path: string;
  } | {
    readonly op: "test";
    readonly path: string;
    readonly value: unknown;
  }>;
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "ACTIVITY_DELTA";
} | {
  readonly event: unknown;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly source?: string;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "RAW";
} | {
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly name: string;
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "CUSTOM";
  readonly value: unknown;
} | {
  readonly input?: {
    readonly context: readonly Array<{
      readonly description: string;
      readonly value: string;
    }>;
    readonly forwardedProps?: unknown;
    readonly messages: readonly Array<{
      readonly content: string;
      readonly encryptedValue?: string;
      readonly id: string;
      readonly metadata?: {
        [key: ...]: ...;
      };
      readonly name?: string;
      readonly role: "developer";
      readonly subagentRunId?: string;
    } | {
      readonly content: string;
      readonly encryptedValue?: string;
      readonly id: string;
      readonly metadata?: {
        [key: ...]: ...;
      };
      readonly name?: string;
      readonly role: "system";
      readonly subagentRunId?: string;
    } | {
      readonly content?: string;
      readonly encryptedValue?: string;
      readonly id: string;
      readonly metadata?: {
        [key: ...]: ...;
      };
      readonly name?: string;
      readonly role: "assistant";
      readonly subagentRunId?: string;
      readonly toolCalls?: readonly Array<...>;
    } | {
      readonly content: string | readonly Array<...>;
      readonly encryptedValue?: string;
      readonly id: string;
      readonly metadata?: {
        [key: ...]: ...;
      };
      readonly name?: string;
      readonly role: "user";
      readonly subagentRunId?: string;
    } | {
      readonly content: string | readonly Array<...>;
      readonly encryptedValue?: string;
      readonly error?: string;
      readonly id: string;
      readonly metadata?: {
        [key: ...]: ...;
      };
      readonly role: "tool";
      readonly subagentRunId?: string;
      readonly toolCallId: string;
    } | {
      readonly activityType: string;
      readonly content: {
        [key: string]: unknown;
      };
      readonly id: string;
      readonly metadata?: {
        [key: ...]: ...;
      };
      readonly role: "activity";
      readonly subagentRunId?: string;
    } | {
      readonly content: string;
      readonly encryptedValue?: string;
      readonly id: string;
      readonly metadata?: {
        [key: ...]: ...;
      };
      readonly role: "reasoning";
      readonly subagentRunId?: string;
    }>;
    readonly parentRunId?: string;
    readonly protocolVersion?: string;
    readonly resume?: readonly Array<{
      readonly interruptId: string;
      readonly metadata?: {
        [key: ...]: ...;
      };
      readonly payload?: unknown;
      readonly status: "resolved" | "cancelled";
    }>;
    readonly runId: string;
    readonly state?: unknown;
    readonly threadId: string;
    readonly tools: readonly Array<{
      readonly description: string;
      readonly metadata?: {
        [key: string]: unknown;
      };
      readonly name: string;
      readonly parameters?: unknown;
    }>;
  };
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly parentRunId?: string;
  readonly protocolVersion?: string;
  readonly rawEvent?: unknown;
  readonly runId: string;
  readonly threadId: string;
  readonly timestamp?: number;
  readonly type: "RUN_STARTED";
} | {
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly outcome?: {
    readonly pendingToolCallIds?: readonly Array<string>;
    readonly type: "success";
  } | {
    readonly interrupts: readonly [{
      readonly expiresAt?: string;
      readonly id: string;
      readonly message?: string;
      readonly metadata?: {
        [key: string]: unknown;
      };
      readonly reason: string;
      readonly responseSchema?: {
        [key: string]: unknown;
      };
      readonly subagentRunId?: string;
      readonly toolCallId?: string;
    }, {
      readonly expiresAt?: string;
      readonly id: string;
      readonly message?: string;
      readonly metadata?: {
        [key: string]: unknown;
      };
      readonly reason: string;
      readonly responseSchema?: {
        [key: string]: unknown;
      };
      readonly subagentRunId?: string;
      readonly toolCallId?: string;
    }];
    readonly type: "interrupt";
  } | {
    readonly type: "cancelled";
  };
  readonly rawEvent?: unknown;
  readonly result?: unknown;
  readonly runId: string;
  readonly threadId: string;
  readonly timestamp?: number;
  readonly type: "RUN_FINISHED";
  readonly usage?: readonly Array<{
    readonly cachedInputTokens?: number;
    readonly cacheWriteInputTokens?: number;
    readonly inputTokens?: number;
    readonly model?: string;
    readonly outputTokens?: number;
    readonly provider?: string;
    readonly reasoningTokens?: number;
    readonly totalTokens?: number;
  }>;
} | {
  readonly code?: string;
  readonly message: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly timestamp?: number;
  readonly type: "RUN_ERROR";
  readonly usage?: readonly Array<{
    readonly cachedInputTokens?: number;
    readonly cacheWriteInputTokens?: number;
    readonly inputTokens?: number;
    readonly model?: string;
    readonly outputTokens?: number;
    readonly provider?: string;
    readonly reasoningTokens?: number;
    readonly totalTokens?: number;
  }>;
} | {
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly stepName: string;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "STEP_STARTED";
} | {
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly stepName: string;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "STEP_FINISHED";
} | {
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "REASONING_START";
} | {
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly role: "reasoning";
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "REASONING_MESSAGE_START";
} | {
  readonly delta: string;
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "REASONING_MESSAGE_CONTENT";
} | {
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "REASONING_MESSAGE_END";
} | {
  readonly delta?: string;
  readonly messageId?: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "REASONING_MESSAGE_CHUNK";
} | {
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "REASONING_END";
} | {
  readonly encryptedValue: string;
  readonly entityId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly subtype: "message" | "tool-call";
  readonly timestamp?: number;
  readonly type: "REASONING_ENCRYPTED_VALUE";
} | {
  readonly description?: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly name: string;
  readonly parentMessageId?: string;
  readonly parentSubagentRunId?: string;
  readonly parentToolCallId?: string;
  readonly rawEvent?: unknown;
  readonly subagentRunId: string;
  readonly timestamp?: number;
  readonly type: "SUBAGENT_STARTED";
} | {
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly outcome?: {
    readonly type: "success";
  } | {
    readonly interruptIds?: readonly Array<string>;
    readonly type: "suspended";
  };
  readonly rawEvent?: unknown;
  readonly result?: unknown;
  readonly subagentRunId: string;
  readonly timestamp?: number;
  readonly type: "SUBAGENT_FINISHED";
} | {
  readonly code?: string;
  readonly message: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId: string;
  readonly timestamp?: number;
  readonly type: "SUBAGENT_ERROR";
}, E, R>) => Stream<{
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly name?: string;
  readonly rawEvent?: unknown;
  readonly role?: "developer" | "system" | "assistant" | "user";
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "TEXT_MESSAGE_START";
} | {
  readonly delta: string;
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "TEXT_MESSAGE_CONTENT";
} | {
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "TEXT_MESSAGE_END";
} | {
  readonly delta?: string;
  readonly messageId?: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly name?: string;
  readonly rawEvent?: unknown;
  readonly role?: "developer" | "system" | "assistant" | "user";
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "TEXT_MESSAGE_CHUNK";
} | {
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly parentMessageId?: string;
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly toolCallId: string;
  readonly toolCallName: string;
  readonly type: "TOOL_CALL_START";
} | {
  readonly delta: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly toolCallId: string;
  readonly type: "TOOL_CALL_ARGS";
} | {
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly toolCallId: string;
  readonly type: "TOOL_CALL_END";
} | {
  readonly delta?: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly parentMessageId?: string;
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly toolCallId?: string;
  readonly toolCallName?: string;
  readonly type: "TOOL_CALL_CHUNK";
} | {
  readonly content: string | readonly Array<{
    readonly id?: string;
    readonly metadata?: unknown;
    readonly text: string;
    readonly type: "text";
  } | {
    readonly id?: string;
    readonly metadata?: unknown;
    readonly source: {
      readonly mimeType: string;
      readonly type: "data";
      readonly value: string;
    } | {
      readonly mimeType?: ... | ...;
      readonly type: "url";
      readonly value: string;
    } | {
      readonly mimeType?: ... | ...;
      readonly provider?: ... | ...;
      readonly type: "file";
      readonly value: string;
    };
    readonly type: "image";
  } | {
    readonly id?: string;
    readonly metadata?: unknown;
    readonly source: {
      readonly mimeType: string;
      readonly type: "data";
      readonly value: string;
    } | {
      readonly mimeType?: ... | ...;
      readonly type: "url";
      readonly value: string;
    } | {
      readonly mimeType?: ... | ...;
      readonly provider?: ... | ...;
      readonly type: "file";
      readonly value: string;
    };
    readonly type: "audio";
  } | {
    readonly id?: string;
    readonly metadata?: unknown;
    readonly source: {
      readonly mimeType: string;
      readonly type: "data";
      readonly value: string;
    } | {
      readonly mimeType?: ... | ...;
      readonly type: "url";
      readonly value: string;
    } | {
      readonly mimeType?: ... | ...;
      readonly provider?: ... | ...;
      readonly type: "file";
      readonly value: string;
    };
    readonly type: "video";
  } | {
    readonly id?: string;
    readonly metadata?: unknown;
    readonly source: {
      readonly mimeType: string;
      readonly type: "data";
      readonly value: string;
    } | {
      readonly mimeType?: ... | ...;
      readonly type: "url";
      readonly value: string;
    } | {
      readonly mimeType?: ... | ...;
      readonly provider?: ... | ...;
      readonly type: "file";
      readonly value: string;
    };
    readonly type: "document";
  }>;
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly role?: "tool";
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly toolCallId: string;
  readonly type: "TOOL_CALL_RESULT";
} | {
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly snapshot: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "STATE_SNAPSHOT";
} | {
  readonly delta: readonly Array<{
    readonly op: "add";
    readonly path: string;
    readonly value: unknown;
  } | {
    readonly op: "remove";
    readonly path: string;
  } | {
    readonly op: "replace";
    readonly path: string;
    readonly value: unknown;
  } | {
    readonly from: string;
    readonly op: "move";
    readonly path: string;
  } | {
    readonly from: string;
    readonly op: "copy";
    readonly path: string;
  } | {
    readonly op: "test";
    readonly path: string;
    readonly value: unknown;
  }>;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "STATE_DELTA";
} | {
  readonly messages: readonly Array<{
    readonly content: string;
    readonly encryptedValue?: string;
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly name?: string;
    readonly role: "developer";
    readonly subagentRunId?: string;
  } | {
    readonly content: string;
    readonly encryptedValue?: string;
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly name?: string;
    readonly role: "system";
    readonly subagentRunId?: string;
  } | {
    readonly content?: string;
    readonly encryptedValue?: string;
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly name?: string;
    readonly role: "assistant";
    readonly subagentRunId?: string;
    readonly toolCalls?: readonly Array<{
      readonly encryptedValue?: ... | ...;
      readonly function: {
        readonly arguments: ...;
        readonly name: ...;
      };
      readonly id: string;
      readonly metadata?: ... | ...;
      readonly type: "function";
    }>;
  } | {
    readonly content: string | readonly Array<{
      readonly id?: ...;
      readonly metadata?: ...;
      readonly text: ...;
      readonly type: ...;
    } | {
      readonly id?: ...;
      readonly metadata?: ...;
      readonly source: ...;
      readonly type: ...;
    } | {
      readonly id?: ...;
      readonly metadata?: ...;
      readonly source: ...;
      readonly type: ...;
    } | {
      readonly id?: ...;
      readonly metadata?: ...;
      readonly source: ...;
      readonly type: ...;
    } | {
      readonly id?: ...;
      readonly metadata?: ...;
      readonly source: ...;
      readonly type: ...;
    }>;
    readonly encryptedValue?: string;
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly name?: string;
    readonly role: "user";
    readonly subagentRunId?: string;
  } | {
    readonly content: string | readonly Array<{
      readonly id?: ...;
      readonly metadata?: ...;
      readonly text: ...;
      readonly type: ...;
    } | {
      readonly id?: ...;
      readonly metadata?: ...;
      readonly source: ...;
      readonly type: ...;
    } | {
      readonly id?: ...;
      readonly metadata?: ...;
      readonly source: ...;
      readonly type: ...;
    } | {
      readonly id?: ...;
      readonly metadata?: ...;
      readonly source: ...;
      readonly type: ...;
    } | {
      readonly id?: ...;
      readonly metadata?: ...;
      readonly source: ...;
      readonly type: ...;
    }>;
    readonly encryptedValue?: string;
    readonly error?: string;
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly role: "tool";
    readonly subagentRunId?: string;
    readonly toolCallId: string;
  } | {
    readonly activityType: string;
    readonly content: {
      [key: string]: unknown;
    };
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly role: "activity";
    readonly subagentRunId?: string;
  } | {
    readonly content: string;
    readonly encryptedValue?: string;
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly role: "reasoning";
    readonly subagentRunId?: string;
  }>;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly timestamp?: number;
  readonly type: "MESSAGES_SNAPSHOT";
} | {
  readonly activityType: string;
  readonly content: {
    [key: string]: unknown;
  };
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly replace?: boolean;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "ACTIVITY_SNAPSHOT";
} | {
  readonly activityType: string;
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly patch: readonly Array<{
    readonly op: "add";
    readonly path: string;
    readonly value: unknown;
  } | {
    readonly op: "remove";
    readonly path: string;
  } | {
    readonly op: "replace";
    readonly path: string;
    readonly value: unknown;
  } | {
    readonly from: string;
    readonly op: "move";
    readonly path: string;
  } | {
    readonly from: string;
    readonly op: "copy";
    readonly path: string;
  } | {
    readonly op: "test";
    readonly path: string;
    readonly value: unknown;
  }>;
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "ACTIVITY_DELTA";
} | {
  readonly event: unknown;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly source?: string;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "RAW";
} | {
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly name: string;
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "CUSTOM";
  readonly value: unknown;
} | {
  readonly input?: {
    readonly context: readonly Array<{
      readonly description: string;
      readonly value: string;
    }>;
    readonly forwardedProps?: unknown;
    readonly messages: readonly Array<{
      readonly content: string;
      readonly encryptedValue?: string;
      readonly id: string;
      readonly metadata?: {
        [key: ...]: ...;
      };
      readonly name?: string;
      readonly role: "developer";
      readonly subagentRunId?: string;
    } | {
      readonly content: string;
      readonly encryptedValue?: string;
      readonly id: string;
      readonly metadata?: {
        [key: ...]: ...;
      };
      readonly name?: string;
      readonly role: "system";
      readonly subagentRunId?: string;
    } | {
      readonly content?: string;
      readonly encryptedValue?: string;
      readonly id: string;
      readonly metadata?: {
        [key: ...]: ...;
      };
      readonly name?: string;
      readonly role: "assistant";
      readonly subagentRunId?: string;
      readonly toolCalls?: readonly Array<...>;
    } | {
      readonly content: string | readonly Array<...>;
      readonly encryptedValue?: string;
      readonly id: string;
      readonly metadata?: {
        [key: ...]: ...;
      };
      readonly name?: string;
      readonly role: "user";
      readonly subagentRunId?: string;
    } | {
      readonly content: string | readonly Array<...>;
      readonly encryptedValue?: string;
      readonly error?: string;
      readonly id: string;
      readonly metadata?: {
        [key: ...]: ...;
      };
      readonly role: "tool";
      readonly subagentRunId?: string;
      readonly toolCallId: string;
    } | {
      readonly activityType: string;
      readonly content: {
        [key: string]: unknown;
      };
      readonly id: string;
      readonly metadata?: {
        [key: ...]: ...;
      };
      readonly role: "activity";
      readonly subagentRunId?: string;
    } | {
      readonly content: string;
      readonly encryptedValue?: string;
      readonly id: string;
      readonly metadata?: {
        [key: ...]: ...;
      };
      readonly role: "reasoning";
      readonly subagentRunId?: string;
    }>;
    readonly parentRunId?: string;
    readonly protocolVersion?: string;
    readonly resume?: readonly Array<{
      readonly interruptId: string;
      readonly metadata?: {
        [key: ...]: ...;
      };
      readonly payload?: unknown;
      readonly status: "resolved" | "cancelled";
    }>;
    readonly runId: string;
    readonly state?: unknown;
    readonly threadId: string;
    readonly tools: readonly Array<{
      readonly description: string;
      readonly metadata?: {
        [key: string]: unknown;
      };
      readonly name: string;
      readonly parameters?: unknown;
    }>;
  };
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly parentRunId?: string;
  readonly protocolVersion?: string;
  readonly rawEvent?: unknown;
  readonly runId: string;
  readonly threadId: string;
  readonly timestamp?: number;
  readonly type: "RUN_STARTED";
} | {
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly outcome?: {
    readonly pendingToolCallIds?: readonly Array<string>;
    readonly type: "success";
  } | {
    readonly interrupts: readonly [{
      readonly expiresAt?: string;
      readonly id: string;
      readonly message?: string;
      readonly metadata?: {
        [key: string]: unknown;
      };
      readonly reason: string;
      readonly responseSchema?: {
        [key: string]: unknown;
      };
      readonly subagentRunId?: string;
      readonly toolCallId?: string;
    }, {
      readonly expiresAt?: string;
      readonly id: string;
      readonly message?: string;
      readonly metadata?: {
        [key: string]: unknown;
      };
      readonly reason: string;
      readonly responseSchema?: {
        [key: string]: unknown;
      };
      readonly subagentRunId?: string;
      readonly toolCallId?: string;
    }];
    readonly type: "interrupt";
  } | {
    readonly type: "cancelled";
  };
  readonly rawEvent?: unknown;
  readonly result?: unknown;
  readonly runId: string;
  readonly threadId: string;
  readonly timestamp?: number;
  readonly type: "RUN_FINISHED";
  readonly usage?: readonly Array<{
    readonly cachedInputTokens?: number;
    readonly cacheWriteInputTokens?: number;
    readonly inputTokens?: number;
    readonly model?: string;
    readonly outputTokens?: number;
    readonly provider?: string;
    readonly reasoningTokens?: number;
    readonly totalTokens?: number;
  }>;
} | {
  readonly code?: string;
  readonly message: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly timestamp?: number;
  readonly type: "RUN_ERROR";
  readonly usage?: readonly Array<{
    readonly cachedInputTokens?: number;
    readonly cacheWriteInputTokens?: number;
    readonly inputTokens?: number;
    readonly model?: string;
    readonly outputTokens?: number;
    readonly provider?: string;
    readonly reasoningTokens?: number;
    readonly totalTokens?: number;
  }>;
} | {
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly stepName: string;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "STEP_STARTED";
} | {
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly stepName: string;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "STEP_FINISHED";
} | {
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "REASONING_START";
} | {
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly role: "reasoning";
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "REASONING_MESSAGE_START";
} | {
  readonly delta: string;
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "REASONING_MESSAGE_CONTENT";
} | {
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "REASONING_MESSAGE_END";
} | {
  readonly delta?: string;
  readonly messageId?: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "REASONING_MESSAGE_CHUNK";
} | {
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "REASONING_END";
} | {
  readonly encryptedValue: string;
  readonly entityId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly subtype: "message" | "tool-call";
  readonly timestamp?: number;
  readonly type: "REASONING_ENCRYPTED_VALUE";
} | {
  readonly description?: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly name: string;
  readonly parentMessageId?: string;
  readonly parentSubagentRunId?: string;
  readonly parentToolCallId?: string;
  readonly rawEvent?: unknown;
  readonly subagentRunId: string;
  readonly timestamp?: number;
  readonly type: "SUBAGENT_STARTED";
} | {
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly outcome?: {
    readonly type: "success";
  } | {
    readonly interruptIds?: readonly Array<string>;
    readonly type: "suspended";
  };
  readonly rawEvent?: unknown;
  readonly result?: unknown;
  readonly subagentRunId: string;
  readonly timestamp?: number;
  readonly type: "SUBAGENT_FINISHED";
} | {
  readonly code?: string;
  readonly message: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId: string;
  readonly timestamp?: number;
  readonly type: "SUBAGENT_ERROR";
}, never, R>

Converting

fromStreamParts

Since v4.1.0

Converts the parts streamed by LanguageModel.streamText into AG-UI events.

Details

  • Each model round becomes a step named step-1, step-2, and so on. The round's finish part closes the step.
  • Text parts become TEXT_MESSAGE_* events from the assistant role, and reasoning parts become a reasoning span holding one reasoning message.
  • Streamed tool parameters become TOOL_CALL_START, TOOL_CALL_ARGS, and TOOL_CALL_END. A tool call that arrives without streamed parameters becomes the same sequence with its parameters as one JSON fragment. Tool calls name the step's latest text message as their parent.
  • Final tool results become TOOL_CALL_RESULT events with a fresh message id from IdGenerator. Failed results carry { "effect/ai": { isFailure: true } } as metadata.
  • An error part is logged and becomes a RUN_ERROR event with a generic message.
  • Preliminary tool results, approval requests, files, sources, and response metadata are dropped.

Failures of the input stream are kept. Use withRunLifecycle to open and close the run and to report failures to the client.

See

Signature

declare function fromStreamParts<E, R>(self: Stream<AnyPart, E, R>): Stream<{
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly name?: string;
  readonly rawEvent?: unknown;
  readonly role?: "developer" | "system" | "assistant" | "user";
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "TEXT_MESSAGE_START";
} | {
  readonly delta: string;
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "TEXT_MESSAGE_CONTENT";
} | {
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "TEXT_MESSAGE_END";
} | {
  readonly delta?: string;
  readonly messageId?: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly name?: string;
  readonly rawEvent?: unknown;
  readonly role?: "developer" | "system" | "assistant" | "user";
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "TEXT_MESSAGE_CHUNK";
} | {
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly parentMessageId?: string;
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly toolCallId: string;
  readonly toolCallName: string;
  readonly type: "TOOL_CALL_START";
} | {
  readonly delta: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly toolCallId: string;
  readonly type: "TOOL_CALL_ARGS";
} | {
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly toolCallId: string;
  readonly type: "TOOL_CALL_END";
} | {
  readonly delta?: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly parentMessageId?: string;
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly toolCallId?: string;
  readonly toolCallName?: string;
  readonly type: "TOOL_CALL_CHUNK";
} | {
  readonly content: string | readonly Array<{
    readonly id?: string;
    readonly metadata?: unknown;
    readonly text: string;
    readonly type: "text";
  } | {
    readonly id?: string;
    readonly metadata?: unknown;
    readonly source: {
      readonly mimeType: string;
      readonly type: "data";
      readonly value: string;
    } | {
      readonly mimeType?: string;
      readonly type: "url";
      readonly value: string;
    } | {
      readonly mimeType?: string;
      readonly provider?: string;
      readonly type: "file";
      readonly value: string;
    };
    readonly type: "image";
  } | {
    readonly id?: string;
    readonly metadata?: unknown;
    readonly source: {
      readonly mimeType: string;
      readonly type: "data";
      readonly value: string;
    } | {
      readonly mimeType?: string;
      readonly type: "url";
      readonly value: string;
    } | {
      readonly mimeType?: string;
      readonly provider?: string;
      readonly type: "file";
      readonly value: string;
    };
    readonly type: "audio";
  } | {
    readonly id?: string;
    readonly metadata?: unknown;
    readonly source: {
      readonly mimeType: string;
      readonly type: "data";
      readonly value: string;
    } | {
      readonly mimeType?: string;
      readonly type: "url";
      readonly value: string;
    } | {
      readonly mimeType?: string;
      readonly provider?: string;
      readonly type: "file";
      readonly value: string;
    };
    readonly type: "video";
  } | {
    readonly id?: string;
    readonly metadata?: unknown;
    readonly source: {
      readonly mimeType: string;
      readonly type: "data";
      readonly value: string;
    } | {
      readonly mimeType?: string;
      readonly type: "url";
      readonly value: string;
    } | {
      readonly mimeType?: string;
      readonly provider?: string;
      readonly type: "file";
      readonly value: string;
    };
    readonly type: "document";
  }>;
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly role?: "tool";
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly toolCallId: string;
  readonly type: "TOOL_CALL_RESULT";
} | {
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly snapshot: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "STATE_SNAPSHOT";
} | {
  readonly delta: readonly Array<{
    readonly op: "add";
    readonly path: string;
    readonly value: unknown;
  } | {
    readonly op: "remove";
    readonly path: string;
  } | {
    readonly op: "replace";
    readonly path: string;
    readonly value: unknown;
  } | {
    readonly from: string;
    readonly op: "move";
    readonly path: string;
  } | {
    readonly from: string;
    readonly op: "copy";
    readonly path: string;
  } | {
    readonly op: "test";
    readonly path: string;
    readonly value: unknown;
  }>;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "STATE_DELTA";
} | {
  readonly messages: readonly Array<{
    readonly content: string;
    readonly encryptedValue?: string;
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly name?: string;
    readonly role: "developer";
    readonly subagentRunId?: string;
  } | {
    readonly content: string;
    readonly encryptedValue?: string;
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly name?: string;
    readonly role: "system";
    readonly subagentRunId?: string;
  } | {
    readonly content?: string;
    readonly encryptedValue?: string;
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly name?: string;
    readonly role: "assistant";
    readonly subagentRunId?: string;
    readonly toolCalls?: readonly Array<{
      readonly encryptedValue?: string;
      readonly function: {
        readonly arguments: string;
        readonly name: string;
      };
      readonly id: string;
      readonly metadata?: {
        [key: ...]: ...;
      };
      readonly type: "function";
    }>;
  } | {
    readonly content: string | readonly Array<{
      readonly id?: ... | ...;
      readonly metadata?: unknown;
      readonly text: string;
      readonly type: "text";
    } | {
      readonly id?: ... | ...;
      readonly metadata?: unknown;
      readonly source: ... | ... | ...;
      readonly type: "image";
    } | {
      readonly id?: ... | ...;
      readonly metadata?: unknown;
      readonly source: ... | ... | ...;
      readonly type: "audio";
    } | {
      readonly id?: ... | ...;
      readonly metadata?: unknown;
      readonly source: ... | ... | ...;
      readonly type: "video";
    } | {
      readonly id?: ... | ...;
      readonly metadata?: unknown;
      readonly source: ... | ... | ...;
      readonly type: "document";
    }>;
    readonly encryptedValue?: string;
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly name?: string;
    readonly role: "user";
    readonly subagentRunId?: string;
  } | {
    readonly content: string | readonly Array<{
      readonly id?: ... | ...;
      readonly metadata?: unknown;
      readonly text: string;
      readonly type: "text";
    } | {
      readonly id?: ... | ...;
      readonly metadata?: unknown;
      readonly source: ... | ... | ...;
      readonly type: "image";
    } | {
      readonly id?: ... | ...;
      readonly metadata?: unknown;
      readonly source: ... | ... | ...;
      readonly type: "audio";
    } | {
      readonly id?: ... | ...;
      readonly metadata?: unknown;
      readonly source: ... | ... | ...;
      readonly type: "video";
    } | {
      readonly id?: ... | ...;
      readonly metadata?: unknown;
      readonly source: ... | ... | ...;
      readonly type: "document";
    }>;
    readonly encryptedValue?: string;
    readonly error?: string;
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly role: "tool";
    readonly subagentRunId?: string;
    readonly toolCallId: string;
  } | {
    readonly activityType: string;
    readonly content: {
      [key: string]: unknown;
    };
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly role: "activity";
    readonly subagentRunId?: string;
  } | {
    readonly content: string;
    readonly encryptedValue?: string;
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly role: "reasoning";
    readonly subagentRunId?: string;
  }>;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly timestamp?: number;
  readonly type: "MESSAGES_SNAPSHOT";
} | {
  readonly activityType: string;
  readonly content: {
    [key: string]: unknown;
  };
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly replace?: boolean;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "ACTIVITY_SNAPSHOT";
} | {
  readonly activityType: string;
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly patch: readonly Array<{
    readonly op: "add";
    readonly path: string;
    readonly value: unknown;
  } | {
    readonly op: "remove";
    readonly path: string;
  } | {
    readonly op: "replace";
    readonly path: string;
    readonly value: unknown;
  } | {
    readonly from: string;
    readonly op: "move";
    readonly path: string;
  } | {
    readonly from: string;
    readonly op: "copy";
    readonly path: string;
  } | {
    readonly op: "test";
    readonly path: string;
    readonly value: unknown;
  }>;
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "ACTIVITY_DELTA";
} | {
  readonly event: unknown;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly source?: string;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "RAW";
} | {
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly name: string;
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "CUSTOM";
  readonly value: unknown;
} | {
  readonly input?: {
    readonly context: readonly Array<{
      readonly description: string;
      readonly value: string;
    }>;
    readonly forwardedProps?: unknown;
    readonly messages: readonly Array<{
      readonly content: string;
      readonly encryptedValue?: string;
      readonly id: string;
      readonly metadata?: {
        [key: string]: unknown;
      };
      readonly name?: string;
      readonly role: "developer";
      readonly subagentRunId?: string;
    } | {
      readonly content: string;
      readonly encryptedValue?: string;
      readonly id: string;
      readonly metadata?: {
        [key: string]: unknown;
      };
      readonly name?: string;
      readonly role: "system";
      readonly subagentRunId?: string;
    } | {
      readonly content?: string;
      readonly encryptedValue?: string;
      readonly id: string;
      readonly metadata?: {
        [key: string]: unknown;
      };
      readonly name?: string;
      readonly role: "assistant";
      readonly subagentRunId?: string;
      readonly toolCalls?: readonly Array<{
        readonly encryptedValue?: ...;
        readonly function: ...;
        readonly id: ...;
        readonly metadata?: ...;
        readonly type: ...;
      }>;
    } | {
      readonly content: string | readonly Array<... | ... | ... | ... | ...>;
      readonly encryptedValue?: string;
      readonly id: string;
      readonly metadata?: {
        [key: string]: unknown;
      };
      readonly name?: string;
      readonly role: "user";
      readonly subagentRunId?: string;
    } | {
      readonly content: string | readonly Array<... | ... | ... | ... | ...>;
      readonly encryptedValue?: string;
      readonly error?: string;
      readonly id: string;
      readonly metadata?: {
        [key: string]: unknown;
      };
      readonly role: "tool";
      readonly subagentRunId?: string;
      readonly toolCallId: string;
    } | {
      readonly activityType: string;
      readonly content: {
        [key: string]: unknown;
      };
      readonly id: string;
      readonly metadata?: {
        [key: string]: unknown;
      };
      readonly role: "activity";
      readonly subagentRunId?: string;
    } | {
      readonly content: string;
      readonly encryptedValue?: string;
      readonly id: string;
      readonly metadata?: {
        [key: string]: unknown;
      };
      readonly role: "reasoning";
      readonly subagentRunId?: string;
    }>;
    readonly parentRunId?: string;
    readonly protocolVersion?: string;
    readonly resume?: readonly Array<{
      readonly interruptId: string;
      readonly metadata?: {
        [key: string]: unknown;
      };
      readonly payload?: unknown;
      readonly status: "resolved" | "cancelled";
    }>;
    readonly runId: string;
    readonly state?: unknown;
    readonly threadId: string;
    readonly tools: readonly Array<{
      readonly description: string;
      readonly metadata?: {
        [key: string]: unknown;
      };
      readonly name: string;
      readonly parameters?: unknown;
    }>;
  };
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly parentRunId?: string;
  readonly protocolVersion?: string;
  readonly rawEvent?: unknown;
  readonly runId: string;
  readonly threadId: string;
  readonly timestamp?: number;
  readonly type: "RUN_STARTED";
} | {
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly outcome?: {
    readonly pendingToolCallIds?: readonly Array<string>;
    readonly type: "success";
  } | {
    readonly interrupts: readonly [{
      readonly expiresAt?: string;
      readonly id: string;
      readonly message?: string;
      readonly metadata?: {
        [key: string]: unknown;
      };
      readonly reason: string;
      readonly responseSchema?: {
        [key: string]: unknown;
      };
      readonly subagentRunId?: string;
      readonly toolCallId?: string;
    }, {
      readonly expiresAt?: string;
      readonly id: string;
      readonly message?: string;
      readonly metadata?: {
        [key: string]: unknown;
      };
      readonly reason: string;
      readonly responseSchema?: {
        [key: string]: unknown;
      };
      readonly subagentRunId?: string;
      readonly toolCallId?: string;
    }];
    readonly type: "interrupt";
  } | {
    readonly type: "cancelled";
  };
  readonly rawEvent?: unknown;
  readonly result?: unknown;
  readonly runId: string;
  readonly threadId: string;
  readonly timestamp?: number;
  readonly type: "RUN_FINISHED";
  readonly usage?: readonly Array<{
    readonly cachedInputTokens?: number;
    readonly cacheWriteInputTokens?: number;
    readonly inputTokens?: number;
    readonly model?: string;
    readonly outputTokens?: number;
    readonly provider?: string;
    readonly reasoningTokens?: number;
    readonly totalTokens?: number;
  }>;
} | {
  readonly code?: string;
  readonly message: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly timestamp?: number;
  readonly type: "RUN_ERROR";
  readonly usage?: readonly Array<{
    readonly cachedInputTokens?: number;
    readonly cacheWriteInputTokens?: number;
    readonly inputTokens?: number;
    readonly model?: string;
    readonly outputTokens?: number;
    readonly provider?: string;
    readonly reasoningTokens?: number;
    readonly totalTokens?: number;
  }>;
} | {
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly stepName: string;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "STEP_STARTED";
} | {
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly stepName: string;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "STEP_FINISHED";
} | {
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "REASONING_START";
} | {
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly role: "reasoning";
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "REASONING_MESSAGE_START";
} | {
  readonly delta: string;
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "REASONING_MESSAGE_CONTENT";
} | {
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "REASONING_MESSAGE_END";
} | {
  readonly delta?: string;
  readonly messageId?: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "REASONING_MESSAGE_CHUNK";
} | {
  readonly messageId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly timestamp?: number;
  readonly type: "REASONING_END";
} | {
  readonly encryptedValue: string;
  readonly entityId: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId?: string;
  readonly subtype: "message" | "tool-call";
  readonly timestamp?: number;
  readonly type: "REASONING_ENCRYPTED_VALUE";
} | {
  readonly description?: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly name: string;
  readonly parentMessageId?: string;
  readonly parentSubagentRunId?: string;
  readonly parentToolCallId?: string;
  readonly rawEvent?: unknown;
  readonly subagentRunId: string;
  readonly timestamp?: number;
  readonly type: "SUBAGENT_STARTED";
} | {
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly outcome?: {
    readonly type: "success";
  } | {
    readonly interruptIds?: readonly Array<string>;
    readonly type: "suspended";
  };
  readonly rawEvent?: unknown;
  readonly result?: unknown;
  readonly subagentRunId: string;
  readonly timestamp?: number;
  readonly type: "SUBAGENT_FINISHED";
} | {
  readonly code?: string;
  readonly message: string;
  readonly metadata?: {
    [key: string]: unknown;
  };
  readonly rawEvent?: unknown;
  readonly subagentRunId: string;
  readonly timestamp?: number;
  readonly type: "SUBAGENT_ERROR";
}, E, R | IdGenerator>

toPrompt

Since v4.1.0

Converts the conversation in an AG-UI run input into a Prompt.

Details

  • User and assistant messages keep their text. Assistant tool calls become tool-call parts with their JSON arguments parsed.
  • Each tool message becomes a tool message with one tool-result part, named after the latest preceding assistant tool call with its id, since providers may reuse call ids across turns. Content that is valid JSON is parsed. A message with an error becomes a failed result carrying the error text, and a message carrying the failure metadata that fromStreamParts emits becomes a failed result carrying its content.
  • User image, audio, video, and document parts with inline data or a valid URL become file parts.
  • Activity and reasoning messages, provider file handles, and tool messages that answer no preceding tool call are dropped.

Gotchas

The whole conversation comes from the client. By default system and developer messages and the input's context are dropped, so a browser cannot replace the server's instructions. Set trustClientInstructions to keep them: system and developer messages then become system messages in place, and context becomes a leading system message.

Signature

declare function toPrompt(input: {
  readonly context: readonly Array<{
    readonly description: string;
    readonly value: string;
  }>;
  readonly forwardedProps?: unknown;
  readonly messages: readonly Array<{
    readonly content: string;
    readonly encryptedValue?: string;
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly name?: string;
    readonly role: "developer";
    readonly subagentRunId?: string;
  } | {
    readonly content: string;
    readonly encryptedValue?: string;
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly name?: string;
    readonly role: "system";
    readonly subagentRunId?: string;
  } | {
    readonly content?: string;
    readonly encryptedValue?: string;
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly name?: string;
    readonly role: "assistant";
    readonly subagentRunId?: string;
    readonly toolCalls?: readonly Array<{
      readonly encryptedValue?: string;
      readonly function: {
        readonly arguments: string;
        readonly name: string;
      };
      readonly id: string;
      readonly metadata?: {
        [key: string]: unknown;
      };
      readonly type: "function";
    }>;
  } | {
    readonly content: string | readonly Array<{
      readonly id?: string;
      readonly metadata?: unknown;
      readonly text: string;
      readonly type: "text";
    } | {
      readonly id?: string;
      readonly metadata?: unknown;
      readonly source: {
        readonly mimeType: string;
        readonly type: "data";
        readonly value: string;
      } | {
        readonly mimeType?: ... | ...;
        readonly type: "url";
        readonly value: string;
      } | {
        readonly mimeType?: ... | ...;
        readonly provider?: ... | ...;
        readonly type: "file";
        readonly value: string;
      };
      readonly type: "image";
    } | {
      readonly id?: string;
      readonly metadata?: unknown;
      readonly source: {
        readonly mimeType: string;
        readonly type: "data";
        readonly value: string;
      } | {
        readonly mimeType?: ... | ...;
        readonly type: "url";
        readonly value: string;
      } | {
        readonly mimeType?: ... | ...;
        readonly provider?: ... | ...;
        readonly type: "file";
        readonly value: string;
      };
      readonly type: "audio";
    } | {
      readonly id?: string;
      readonly metadata?: unknown;
      readonly source: {
        readonly mimeType: string;
        readonly type: "data";
        readonly value: string;
      } | {
        readonly mimeType?: ... | ...;
        readonly type: "url";
        readonly value: string;
      } | {
        readonly mimeType?: ... | ...;
        readonly provider?: ... | ...;
        readonly type: "file";
        readonly value: string;
      };
      readonly type: "video";
    } | {
      readonly id?: string;
      readonly metadata?: unknown;
      readonly source: {
        readonly mimeType: string;
        readonly type: "data";
        readonly value: string;
      } | {
        readonly mimeType?: ... | ...;
        readonly type: "url";
        readonly value: string;
      } | {
        readonly mimeType?: ... | ...;
        readonly provider?: ... | ...;
        readonly type: "file";
        readonly value: string;
      };
      readonly type: "document";
    }>;
    readonly encryptedValue?: string;
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly name?: string;
    readonly role: "user";
    readonly subagentRunId?: string;
  } | {
    readonly content: string | readonly Array<{
      readonly id?: string;
      readonly metadata?: unknown;
      readonly text: string;
      readonly type: "text";
    } | {
      readonly id?: string;
      readonly metadata?: unknown;
      readonly source: {
        readonly mimeType: string;
        readonly type: "data";
        readonly value: string;
      } | {
        readonly mimeType?: ... | ...;
        readonly type: "url";
        readonly value: string;
      } | {
        readonly mimeType?: ... | ...;
        readonly provider?: ... | ...;
        readonly type: "file";
        readonly value: string;
      };
      readonly type: "image";
    } | {
      readonly id?: string;
      readonly metadata?: unknown;
      readonly source: {
        readonly mimeType: string;
        readonly type: "data";
        readonly value: string;
      } | {
        readonly mimeType?: ... | ...;
        readonly type: "url";
        readonly value: string;
      } | {
        readonly mimeType?: ... | ...;
        readonly provider?: ... | ...;
        readonly type: "file";
        readonly value: string;
      };
      readonly type: "audio";
    } | {
      readonly id?: string;
      readonly metadata?: unknown;
      readonly source: {
        readonly mimeType: string;
        readonly type: "data";
        readonly value: string;
      } | {
        readonly mimeType?: ... | ...;
        readonly type: "url";
        readonly value: string;
      } | {
        readonly mimeType?: ... | ...;
        readonly provider?: ... | ...;
        readonly type: "file";
        readonly value: string;
      };
      readonly type: "video";
    } | {
      readonly id?: string;
      readonly metadata?: unknown;
      readonly source: {
        readonly mimeType: string;
        readonly type: "data";
        readonly value: string;
      } | {
        readonly mimeType?: ... | ...;
        readonly type: "url";
        readonly value: string;
      } | {
        readonly mimeType?: ... | ...;
        readonly provider?: ... | ...;
        readonly type: "file";
        readonly value: string;
      };
      readonly type: "document";
    }>;
    readonly encryptedValue?: string;
    readonly error?: string;
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly role: "tool";
    readonly subagentRunId?: string;
    readonly toolCallId: string;
  } | {
    readonly activityType: string;
    readonly content: {
      [key: string]: unknown;
    };
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly role: "activity";
    readonly subagentRunId?: string;
  } | {
    readonly content: string;
    readonly encryptedValue?: string;
    readonly id: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly role: "reasoning";
    readonly subagentRunId?: string;
  }>;
  readonly parentRunId?: string;
  readonly protocolVersion?: string;
  readonly resume?: readonly Array<{
    readonly interruptId: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly payload?: unknown;
    readonly status: "resolved" | "cancelled";
  }>;
  readonly runId: string;
  readonly state?: unknown;
  readonly threadId: string;
  readonly tools: readonly Array<{
    readonly description: string;
    readonly metadata?: {
      [key: string]: unknown;
    };
    readonly name: string;
    readonly parameters?: unknown;
  }>;
}, options?: {
  readonly trustClientInstructions?: boolean;
}): Prompt