Struct AgentBuilder 

pub struct AgentBuilder { /* private fields */ }

Builder for configuring and running agent sessions.

Use the builder pattern to set options, then call a terminal method (exec, run, resume, continue_last) to execute.

Implementations

impl AgentBuilder

pub fn new() -> Self

Create a new builder with default settings.

pub fn provider(self, provider: &str) -> Self

Set the provider (e.g., “claude”, “codex”, “gemini”, “copilot”, “ollama”).

Calling this method pins the provider — it will NOT be downgraded to another provider in the tier list if its binary is missing or the startup probe fails. Omit this call (or set provider via the config file) to allow automatic downgrading.

pub fn model(self, model: &str) -> Self

Set the model (e.g., “sonnet”, “opus”, “small”, “large”).

pub fn system_prompt(self, prompt: &str) -> Self

Set a system prompt to configure agent behavior.

pub fn root(self, root: &str) -> Self

Set the root directory for the agent to operate in.

pub fn auto_approve(self, approve: bool) -> Self

Enable auto-approve mode (skip permission prompts).

pub fn add_dir(self, dir: &str) -> Self

Add an additional directory for the agent to include.

pub fn file(self, path: &str) -> Self

Attach a file to the prompt (text files ≤50 KB inlined, others referenced).

pub fn env(self, key: &str, value: &str) -> Self

Add an environment variable for the agent subprocess.

pub fn worktree(self, name: Option<&str>) -> Self

Enable worktree mode with an optional name.

pub fn sandbox(self, name: Option<&str>) -> Self

Enable sandbox mode with an optional name.

pub fn size(self, size: &str) -> Self

Set the Ollama parameter size (e.g., “2b”, “9b”, “35b”).

pub fn json(self) -> Self

Request JSON output from the agent.

pub fn json_schema(self, schema: Value) -> Self

Set a JSON schema for structured output validation. Implies json().

pub fn session_id(self, id: &str) -> Self

Set a specific session ID (UUID).

pub fn name(self, name: &str) -> Self

Set a human-readable session name (mirrors the CLI’s --name).

Names are used by zag input --name <n>, zag session list --name <n>, and for session discovery across the store. When the session has a generated wrapper ID, the builder will persist this name to the session store so CLI tools can find it later.

pub fn description(self, description: &str) -> Self

Set a short description for the session (mirrors the CLI’s --description).

pub fn tag(self, tag: &str) -> Self

Add a discovery tag for the session (mirrors the CLI’s --tag, repeatable).

pub fn metadata(self, metadata: SessionMetadata) -> Self

Replace the full session metadata in one call.

pub fn output_format(self, format: &str) -> Self

Set the output format (e.g., “text”, “json”, “json-pretty”, “stream-json”).

pub fn input_format(self, format: &str) -> Self

Set the input format (Claude only, e.g., “text”, “stream-json”).

No-op for Codex, Gemini, Copilot, and Ollama. See docs/providers.md for the full per-provider support matrix.

pub fn replay_user_messages(self, replay: bool) -> Self

Re-emit user messages from stdin on stdout (Claude only).

Only works with --input-format stream-json and --output-format stream-json. exec_streaming auto-enables this flag, so most callers never need to set it manually. No-op for non-Claude providers.

pub fn include_partial_messages(self, include: bool) -> Self

Include partial message chunks in streaming output (Claude only).

Only works with --output-format stream-json. Defaults to false.

When false (the default), streaming surfaces one assistant_message event per complete assistant turn. When true, the agent instead emits a stream of token-level partial assistant_message chunks as the model generates them — use this for responsive, token-by-token UIs over exec_streaming. No-op for non-Claude providers.

pub fn verbose(self, v: bool) -> Self

Enable verbose output.

pub fn quiet(self, q: bool) -> Self

Enable quiet mode (suppress all non-essential output).

pub fn show_usage(self, show: bool) -> Self

Show token usage statistics.

pub fn max_turns(self, turns: u32) -> Self

Set the maximum number of agentic turns.

pub fn timeout(self, duration: Duration) -> Self

Set a timeout for exec. If the agent doesn’t complete within this duration, it will be killed and an error returned.

pub fn mcp_config(self, config: &str) -> Self

Set MCP server config for this invocation (Claude only).

Accepts either a JSON string ({"mcpServers": {...}}) or a path to a JSON file. No-op for Codex, Gemini, Copilot, and Ollama — those providers manage MCP configuration through their own CLIs or do not support it. See docs/providers.md for the full per-provider support matrix.

pub fn on_progress(self, handler: Box<dyn ProgressHandler>) -> Self

Set a custom progress handler for status reporting.

pub fn session_log(self, mode: SessionLogMode) -> Self

Select how the builder manages the session log. See SessionLogMode.

pub fn enable_session_log(self, enable: bool) -> Self

Shortcut for .session_log(SessionLogMode::Auto) when true, or .session_log(SessionLogMode::Disabled) when false.

pub fn on_log_event<F>(self, f: F) -> Self

where F: Fn(&AgentLogEvent) + Send + Sync + 'static,

Register a callback fired for each AgentLogEvent written to the session log during the terminal method. Implicitly switches session_log_mode to SessionLogMode::Auto if it is currently SessionLogMode::Disabled.

pub fn stream_events_to_stderr(self, format: ListenFormat) -> Self

Convenience: tail the session log to stderr during the terminal method, using the same formatters as the zag listen command.

This is the drop-in replacement for the live stderr tail that a previous shell-out-to-zag wrapper produced. Implicitly enables session logging.

pub fn stream_show_thinking(self, show: bool) -> Self

Include Reasoning events in the stderr stream when [stream_events_to_stderr] is active. Off by default.

pub async fn exec(self, prompt: &str) -> Result<AgentOutput>

Run the agent non-interactively and return structured output.

This is the primary entry point for programmatic use.

pub async fn exec_streaming(self, prompt: &str) -> Result<StreamingSession>

Run the agent with streaming input and output (Claude only).

Returns a StreamingSession that allows sending NDJSON messages to the agent’s stdin and reading events from stdout. Automatically configures --input-format stream-json, --output-format stream-json, and --replay-user-messages.

Default emission granularity

By default assistant_message events are emitted once per complete assistant turn — you get one event when the model finishes speaking, not a stream of token chunks. For responsive, token-level UIs call include_partial_messages(true) on the builder before exec_streaming; the session will then emit partial assistant_message chunks as the model generates them.

The default is kept false so existing callers that render whole-turn bubbles are not broken. See docs/providers.md for the full per-provider flag support matrix.

Event lifecycle

The session emits a unified Event::Result at the end of every agent turn — not only at final session end. Use that event as the authoritative turn-boundary signal. After a Result, the session remains open and accepts another send_user_message for the next turn. Call close_input followed by wait to terminate the session cleanly.

Do not depend on replayed user_message events to detect turn boundaries; those only appear while --replay-user-messages is set.

Examples

use zag_agent::builder::AgentBuilder;
use zag_agent::output::Event;

let mut session = AgentBuilder::new()
    .provider("claude")
    .exec_streaming("initial prompt")
    .await?;

// Drain the first turn until Result.
while let Some(event) = session.next_event().await? {
    println!("{:?}", event);
    if matches!(event, Event::Result { .. }) {
        break;
    }
}

// Follow-up turn.
session.send_user_message("do something else").await?;
while let Some(event) = session.next_event().await? {
    if matches!(event, Event::Result { .. }) {
        break;
    }
}

session.close_input();
session.wait().await?;

pub async fn run(self, prompt: Option<&str>) -> Result<()>

Start an interactive agent session.

This takes over stdin/stdout for the duration of the session.

pub async fn resume(self, session_id: &str) -> Result<()>

Resume a previous session by ID.

pub async fn continue_last(self) -> Result<()>

Resume the most recent session.

Trait Implementations

impl Default for AgentBuilder

fn default() -> Self

Returns the “default value” for a type.