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::PromptError::MaxTurnsError.

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

where H: AgentHook + '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, while model-turn steering and observe-only/recovery events use first-non-Continue-wins). See the hook module docs.

pub fn tool_context(self, context: ToolContext) -> Self

Attach a per-call ToolContext for this request.

Every tool the agent executes during this request can read the caller-provided values (auth tokens, session IDs, conversation state, …) through the tool’s ToolContext, 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 preamble(self, preamble: impl Into<String>) -> Self

Override the agent preamble for this request.

pub fn without_preamble(self) -> Self

Remove the agent’s configured preamble for this request.

pub fn document(self, document: Document) -> Self

Append one static context document for this request.

pub fn documents(self, documents: impl IntoIterator<Item = Document>) -> Self

Append static context documents for this request.

pub fn temperature(self, temperature: f64) -> Self

Override the model temperature for this request.

pub fn without_temperature(self) -> Self

Remove the agent’s configured temperature for this request.

pub fn max_tokens(self, max_tokens: u64) -> Self

Override the maximum completion token count for this request.

pub fn without_max_tokens(self) -> Self

Remove the agent’s configured maximum token count for this request.

pub fn merge_additional_params(self, params: Map<String, Value>) -> Self

Shallow-merge object fields into the provider-specific parameters for this request. Later fields win.

pub fn replace_additional_params(self, params: Value) -> Self

Replace all provider-specific parameters for this request.

pub fn without_additional_params(self) -> Self

Remove the agent’s configured provider-specific parameters for this request.

pub fn tool_choice(self, tool_choice: ToolChoice) -> Self

Override the tool-choice policy for this request.

pub fn without_tool_choice(self) -> Self

Remove the agent’s configured tool-choice policy for this request.

pub fn record_content_telemetry(self, enabled: bool) -> Self

Opt in or out of recording sensitive request, response, and tool content on GenAI telemetry spans for this request.

Defaults to the agent’s setting, which defaults to false. Enabling this can expose prompts, retrieved context, tool results, model responses, and other sensitive or high-cardinality data through OpenTelemetry span attributes, which can increase observability backend storage and query costs. Only enable it when content telemetry is acceptable for this request. Structural metadata and token usage remain available when disabled.

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.