Struct PromptRequest 

pub struct PromptRequest<S, M>
where
    S: PromptType,
    M: CompletionModel,
{ /* private fields */ }

A builder for creating prompt requests with customizable options. Uses generics to track which options have been set during the build process.

When the agent has no configured default_max_turns, the implicit budget is one model call. Use .max_turns() to override the agent’s configured or implicit budget; a tool call followed by a model-authored final answer generally requires at least two model calls.

Implementations

impl<M> PromptRequest<Standard, M>

where M: CompletionModel,

pub fn from_agent(agent: &Agent<M>, prompt: impl Into<Message>) -> Self

Create a new PromptRequest from an agent, cloning the agent’s data and default hook stack.

impl<S, M> PromptRequest<S, M>

where S: PromptType, M: CompletionModel,

pub fn extended_details(self) -> PromptRequest<Extended, M>

Enable returning extended details for responses (includes aggregated token usage and the full message history accumulated during the agent loop).

Note: This changes the type of the response from .send to return a PromptResponse struct instead of a simple String. This is useful for tracking token usage across multiple turns of conversation and inspecting the full message exchange.

pub fn max_turns(self, max_turns: usize) -> Self

Set the total model-call budget, including the initial call and every retry or continuation. Zero emits no model calls; one permits only the initial call. Exceeding the budget returns crate::completion::request::PromptError::MaxTurnsError.

pub fn add_hook<H>(self, hook: H) -> Self

where H: AgentHook<M> + 'static,

Append a hook for this request (on top of any the agent already carries). Hooks run in registration order; how their results compose is event-dependent (CompletionCall request patches accumulate and merge, ToolCall/ToolResult rewrites chain, and only observe-only/recovery events use first-non-Continue-wins). See the hook module docs.

pub fn tool_extensions(self, extensions: ToolCallExtensions) -> Self

Attach a per-call ToolCallExtensions for this request.

Every tool the agent executes during this request can read the caller-provided values (auth tokens, session IDs, conversation state, …) via Tool::call_with_extensions, without the model ever seeing them.

pub fn history<H, Item>(self, history: H) -> Self

where H: IntoIterator<Item = Item>, Item: Into<Message>,

Add chat history to the prompt request.

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

Set the conversation id used to load and persist memory for this request.

Overrides any default conversation id set on the agent. If memory is not configured on the agent, this has no effect.

pub fn without_memory(self) -> Self

Disable conversation memory for this request.

History will neither be loaded from nor saved to the agent’s memory backend.

pub fn max_invalid_tool_call_retries(self, retries: usize) -> Self

Set the retry budget for invalid tool-call recovery.

Invalid tool-call retries also consume the total model-call budget.

pub fn tool_concurrency(self, concurrency: usize) -> Self

Execute up to concurrency of a turn’s tool calls at once.

See AgentRunner::tool_concurrency for ordering guarantees: the tool batch commits and surfaces atomically, so persisted history and streamed tool results are both in tool-call order (results are surfaced only after the whole batch settles successfully).

Trait Implementations

impl<M> IntoFuture for PromptRequest<Standard, M>

where M: CompletionModel + 'static,

Due to: RFC 2515, we have to use a BoxFuture for the IntoFuture implementation. In the future, we should be able to use impl Future<...> directly via the associated type.

type Output = Result<String, PromptError>

The output that the future will produce on completion.

type IntoFuture = Pin<Box<dyn Future<Output = <PromptRequest<Standard, M> as IntoFuture>::Output> + Send>>

Which kind of future are we turning this into?

fn into_future(self) -> Self::IntoFuture

Creates a future from a value.

impl<M> IntoFuture for PromptRequest<Extended, M>

where M: CompletionModel + 'static,

type Output = Result<PromptResponse, PromptError>

The output that the future will produce on completion.

type IntoFuture = Pin<Box<dyn Future<Output = <PromptRequest<Extended, M> as IntoFuture>::Output> + Send>>

Which kind of future are we turning this into?

fn into_future(self) -> Self::IntoFuture

Creates a future from a value.