Module prelude 

Commonly used imports for building agents and workflows.

Structs

Agent

The primary concrete agent: pairs a chat client with instructions, default options, tools, context providers, and middleware.

AgentBuilder

Builder for Agent.

AgentContext

Context flowing through the agent middleware pipeline.

AgentResponse

A full response from an agent run.

AgentResponseUpdate

A single streaming chunk from an agent run.

AgentRunOptions

Per-run option overrides for a single SupportsAgentRun::run_with_options / SupportsAgentRun::run_stream call, merged over the agent’s build-time defaults.

AgentSession

A conversation session: a lightweight identity + state container.

ApproxTokenizer

A dependency-free default tokenizer using a ~4-characters-per-token heuristic. Mirrors upstream’s CharacterEstimatorTokenizer.

AsToolOptions

Options for Agent::as_tool.

ChatContext

Context flowing through the chat middleware pipeline.

ChatOptions

Common per-request settings for a chat/AI service.

ChatResponse

A full (non-streaming) response from a chat client.

ChatResponseUpdate

A single streaming chunk from a chat client.

CompactionProvider

A ContextProvider that compacts the accumulated message list — typically the run’s history, once a HistoryProvider has prepended it in before_run — down to fit a CompactionStrategy’s constraint before it reaches the model. Rust equivalent of (a subset of) upstream’s CompactionProvider (see module docs and UPSTREAM_DRIFT.md §9).

ConcurrentBuilder

Builder for a concurrent fan-out/fan-in over agents. Rust analogue of ConcurrentBuilder.

Embedding

A single embedding vector with metadata.

EmbeddingGenerationOptions

Common request settings for embedding generation.

FileCheckpointStorage

File-based checkpoint storage: one JSON file per checkpoint in a directory.

FileHistoryProvider

A HistoryProvider that persists to a JSON file on disk, loading any existing history from path on construction and rewriting the whole file after every successful run.

FinishReason

Reason a chat response finished. Open value wrapper, like FinishReason.

FunctionApprovalRequestContent

A request to the user to approve a function call (human-in-the-loop).

FunctionApprovalResponseContent

A user’s response approving or denying a function call.

FunctionCallContent

A request from the model to call a tool/function.

FunctionInvocationConfig

Configuration for the automatic function-invocation loop.

FunctionInvocationContext

Context flowing through the function middleware pipeline.

FunctionInvokingChatClient

Wraps a ChatClient to automatically execute local tool calls in a loop, mirroring use_function_invocation.

FunctionResultContent

The result of executing a tool/function.

FunctionTool

A concrete, locally executable tool built from a closure.

GeneratedEmbeddings

A batch of generated embeddings plus usage metadata.

GroupChatBuilder

Builder for a group chat workflow. Rust analogue of GroupChatBuilder.

GroupChatState

A snapshot of orchestration state handed to a GroupChatManager for its speaker-selection decision. Rust analogue of GroupChatStateSnapshot.

HandoffBuilder

Builder for a handoff workflow. Rust analogue of HandoffBuilder.

InMemoryCheckpointStorage

In-memory checkpoint storage for testing and development.

InMemoryHistoryProvider

In-memory HistoryProvider: keeps history in an Arc<Mutex<Vec<Message>>>, shared across clones.

LiveToolList

The live, mutable tool list of an in-flight agent run (progressive tool exposure).

MagenticBuilder

Builder for a Magentic workflow. Rust analogue of MagenticBuilder.

MagenticContext

Mutable state threaded through the Magentic manager and orchestrator. Rust analogue of MagenticContext.

MagenticPlanReviewRequest

The payload of the request-info event emitted when plan review is enabled and the orchestrator needs a human decision on the task ledger. Rust analogue of Python’s _MagenticHumanInterventionRequest narrowed to its kind=PLAN_REVIEW fields (task_text, facts_text, plan_text, round_index).

MagenticStallInterventionRequest

The payload of the request-info event emitted when stall intervention is enabled and the round loop detects a stall. Rust analogue of Python’s _MagenticHumanInterventionRequest narrowed to its kind=STALL fields (stall_count, max_stall_count, task_text, facts_text, plan_text, last_agent, stall_reason), plus round/resets_so_far for context.

Message

A single chat message: an author role plus an ordered list of content items.

MiddlewarePipeline

A pipeline of middleware of a single category.

Next

The continuation passed to a Middleware. Calling Next::run invokes the remaining middleware and, finally, the terminal handler.

ObservabilityConfig

Observability configuration read from the process environment, mirroring (a subset of) Python’s ObservabilitySettings (observability.py:347-394).

ObservableChatClient

A ChatClient decorator that emits a chat span per request following the OpenTelemetry GenAI semantic conventions.

OpenAIChatClient

An OpenAI Responses API chat client (POST /v1/responses).

OpenAIChatCompletionClient

An OpenAI (or OpenAI-compatible) chat client.

OpenAIEmbeddingClient

An OpenAI (or OpenAI-compatible) embeddings client.

RequestInfoExecutor

A built-in node that surfaces incoming messages as external requests.

RetryPolicy

Policy controlling RetryingChatClient backoff.

RetryingChatClient

A ChatClient decorator that retries transient failures with exponential backoff, honoring a server Retry-After when present.

Role

The role of a message author.

SecretString

A string wrapper that masks its value when printed via Debug or Display, to prevent secrets (API keys, tokens, passwords, …) from accidentally ending up in logs or error messages.

SelectiveToolResult

Replace the payload of Content::FunctionResult (tool-result) content in all but the last keep_last messages that carry tool results — they are the bulkiest and least useful once stale. Text and other content is left intact.

SequentialBuilder

Builder for a sequential pipeline of agents. Rust analogue of SequentialBuilder. Each participant sees the running conversation and appends its reply; the final conversation is yielded as output.

SessionContext

Per-invocation context a provider contributes to a run. Providers mutate this in place in before_run. Rust equivalent of upstream SessionContext.

SessionState

The free-form state bag of an AgentSession, shared by reference across clones.

SharedState

A thread-safe, async, string→JSON store shared by all executors in a run.

Skill

A named, progressive-disclosure capability package.

SkillsProvider

A ContextProvider that attaches a set of Skills to an agent run with progressive disclosure.

SlidingWindow

Keep leading system message(s) + the last window non-system messages. Mirrors upstream’s SlidingWindow strategy.

StandardMagenticManager

The standard LLM-driven manager. Rust analogue of StandardMagenticManager.

TextContent

Plain text content.

TokenBudget

Keep leading system message(s), then walk from the newest message backward accumulating token counts, keeping messages until adding the next would exceed max_tokens. Returns the kept messages in original order. Mirrors upstream’s ContextWindow/token-budget strategy.

ToolDefinition

A uniform, cloneable descriptor of a tool passed via ChatOptions::tools.

Truncation

Keep the most recent max_messages, always preserving any leading system message(s) at the front. Mirrors upstream’s Truncation strategy.

UsageDetails

Token usage counts for a request/response.

Workflow

A built, runnable workflow graph.

WorkflowAgent

An SupportsAgentRun that wraps a Workflow and exposes it through the agent interface. Rust analogue of WorkflowAgent.

WorkflowBuilder

Fluent builder for a Workflow. Rust equivalent of WorkflowBuilder.

WorkflowContext

Collects the effects an executor produces while handling a message: messages to send downstream, workflow outputs, custom events, info requests, and access to run-scoped SharedState.

WorkflowExecutor

An Executor that runs a child Workflow, enabling hierarchical composition.

WorkflowRun

A live workflow run: owns the pending message queue, fan-in buffers, iteration count, shared state, and outstanding requests, so a run can pause (awaiting external input) and later resume.

Enums

ApprovalMode

Whether a call to a tool must be approved by a human before it runs.

Content

The unified content union, discriminated by the type tag.

Error

The primary error type for the agent framework.

GroupChatDirective

An instruction emitted by a GroupChatManager: either route to a participant, or finish the conversation. Rust analogue of GroupChatDirective.

HandoffInteractionMode

Whether the workflow pauses for fresh user input between agent turns.

MagenticPlanReviewDecision

A human’s decision on a MagenticPlanReviewRequest. Rust analogue of Python’s _MagenticHumanInterventionReply narrowed to plan review, with MagenticHumanInterventionDecision.{APPROVE,REVISE} as the two variants.

MagenticStallInterventionDecision

A human’s decision on a MagenticStallInterventionRequest. Rust analogue of Python’s _MagenticHumanInterventionReply narrowed to the stall subset of MagenticHumanInterventionDecision (CONTINUE / REPLAN / GUIDANCE).

McpApprovalMode

The approval gate configured on a hosted MCP connector – i.e. how the service itself decides whether a call to one of its MCP tools needs human sign-off before it runs. Set via ToolDefinition::mcp_approval_mode.

ResponseFormat

The requested structured-output format for a response.

RetryOn

Which errors a RetryPolicy considers retryable.

ToolKind

The category of a tool as advertised to the service.

ToolMode

If and how tools may be used for a request. Mirrors the Python ToolMode.

WorkflowEvent

An event observed while a workflow runs.

WorkflowRunState

The run state of a workflow, mirroring Python’s WorkflowRunState.

Traits

ChatClient

The interface every chat client implements.

CheckpointStorage

Storage backend for workflow checkpoints.

CompactionStrategy

A strategy that reduces a message list to fit some constraint.

ContextProvider

A source of per-invocation context (memory, RAG, etc.). Upstream renamed invoking/invoked -> before_run/after_run and REMOVED thread_created. before_run mutates the SessionContext in place instead of returning a Context.

EmbeddingClient

The interface every embedding client implements.

Executor

A node in a workflow graph.

GroupChatManager

The decision-making interface for a group chat. Implementations pick the next speaker or finish the conversation. Rust analogue of the manager callable / set_manager agent in Python.

HistoryProvider

A ContextProvider that also manages conversation history.

MagenticManager

The Magentic manager interface: planning, replanning, progress evaluation, and final-answer synthesis. Rust analogue of MagenticManagerBase.

Middleware

A middleware that transforms a context of type C.

SupportsAgentRun

The common interface implemented by all agents.

Tokenizer

Counts tokens for a piece of text. Rust equivalent of upstream TokenizerProtocol.

Tool

An executable tool the framework can invoke locally.

ToolSource

A dynamic source of tools, resolved fresh on every agent run instead of being frozen into the agent’s tool list at build time.

WorkflowAgentExt

Extension trait adding Workflow::as_agent so a built workflow can be exposed as an SupportsAgentRun fluently.

Functions

compact

Compact messages with strategy and tokenizer.

hosted_code_interpreter

Construct a hosted code-interpreter tool marker.

hosted_file_search

Construct a hosted file-search tool marker.

hosted_image_generation

Construct a hosted image-generation tool marker.

hosted_mcp

Construct a hosted MCP tool marker.

hosted_web_search

Construct a hosted web-search tool marker.

load_setting

Resolve a single setting value using the same precedence as upstream’s load_settings:

Type Aliases

AgentRunStream

A boxed stream of agent run updates.

AgentToolStreamCallback

A callback receiving each AgentResponseUpdate streamed by an agent running as a tool — see AsToolOptions::stream_callback.

ChatStream

A boxed stream of streaming chat updates.

Result

The result type used throughout the framework.