Struct AgentCall 

pub struct AgentCall<T = NoSchema> { /* private fields */ }

A fluent, owned builder for one agent leaf. Created by agent.

The type parameter T selects the terminal: NoSchema (default) yields the agent’s text, a StructuredSchema type T yields a validated T, and RawJson yields a validated serde_json::Value. T is phantom — it lives only here, so the underlying runner stays Value-only and object-safe.

Implementations

impl<T> AgentCall<T>

pub fn label(self, label: impl Into<String>) -> Self

Set the display label (used in events and as the runner name).

pub fn phase(self, phase: impl Into<String>) -> Self

Override the phase this call is grouped under.

pub fn model(self, model: impl Into<String>) -> Self

Run this leaf on a different model: a ROLE name (“fast”, “frontier”) or a raw model id, resolved by the ctx’s provider factory. Dynamic model-by-task, the Claude Code way — the workflow decides per agent.

pub fn isolation(self, isolation: Isolation) -> Self

Isolate this leaf’s filesystem effects (see Isolation).

pub fn tools(self, tools: Vec<Arc<dyn Tool>>) -> Self

Wire a tool set into this agent, overriding the ctx’s base tools. The agent can then call these tools during its ReAct loop. (Sub-agents inherit tools the way Claude Code’s subagents inherit the allowlist.)

pub fn goal(self, goal: GoalCondition) -> Self

Attach a persistent GoalCondition: the leaf self-continues until an independent judge confirms the objective (bounded by the goal’s max_continuations). The continuations all run inside the one leaf, so their combined token spend is recorded once against the shared flow budget, and a run-wide budget breach or cancellation aborts the goal loop at the leaf’s cancel race.

impl AgentCall<NoSchema>

pub fn schema<S: StructuredSchema>(self) -> AgentCall<S>

Force validated structured output of type S, transforming this into an AgentCall<S> whose run() returns Option<S>. The schema comes from StructuredSchema::json_schema.

pub fn schema_value(self, schema: Value) -> AgentCall<RawJson>

Force validated structured output against a hand-written JSON Schema, transforming this into an AgentCall<RawJson> whose run() returns the raw validated serde_json::Value (no deserialization).

pub async fn run(self) -> Result<Option<String>, Error>

Run the agent leaf and return its text. Ok(None) only on cancellation.

impl<T: StructuredSchema> AgentCall<T>

pub async fn run(self) -> Result<Option<T>, Error>

Run the agent leaf and deserialize its validated structured output into T. Ok(None) only on cancellation. A run that finishes without producing structured output, or whose output fails to deserialize into T, returns Err — never a silent None.

impl AgentCall<RawJson>

pub async fn run(self) -> Result<Option<Value>, Error>

Run the agent leaf and return its raw validated serde_json::Value. Ok(None) only on cancellation; a run that finishes without structured output returns Err.