Struct Request 

pub struct Request { /* private fields */ }

A run, described but not yet started.

Built fluently and then handed to crate::run or crate::stream:

use agent_abstraction::{Agent, Permission, Request};

let request = Request::new(Agent::Claude, "summarize this repo")
    .model("sonnet")
    .permission(Permission::ReadOnly);

Implementations

impl Request

pub fn new(agent: Agent, prompt: impl Into<String>) -> Self

A request for agent with prompt.

Defaults are deliberately conservative: Permission::ReadOnly, EnvPolicy::Minimal, and the agent’s structured output format. Widen them explicitly.

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

Override the binary. Defaults to the agent’s own name on PATH.

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

A system prompt. Delivered by flag where the agent has one and prepended to the prompt where it does not. It is never dropped.

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

Pin the model. Passed through verbatim; this crate does not validate model names, so an unknown one surfaces as the agent’s own error.

pub fn permission(self, permission: Permission) -> Self

Set the permission posture.

pub fn format(self, format: Format) -> Self

Pin the output format. Left unset, a run picks the agent’s structured format, which is also the one that carries a session id.

pub fn cwd(self, cwd: impl Into<PathBuf>) -> Self

The working directory the agent runs in.

pub fn env(self, key: impl Into<String>, value: impl Into<String>) -> Self

Set an environment variable for the child. Repeatable.

pub fn env_policy(self, policy: EnvPolicy) -> Self

Choose which of the host’s environment variables reach the agent.

Defaults to EnvPolicy::Minimal, which passes through only what the selected agent needs. Reach for EnvPolicy::Inherit when the host holds nothing the agent should not see, or when something this crate does not know about has to reach the CLI.

let request = Request::new(Agent::Claude, "review this")
    .env_policy(EnvPolicy::Inherit);

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

Kill the run if it has not finished within timeout.

pub fn unchecked_args<I, S>(self, args: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Append raw arguments after everything this crate builds.

The escape hatch for agent-specific flags with no unified spelling.

This voids the crate’s guarantees. Arguments land after the generated ones, so they can contradict Request::permission, redirect the output format the parser expects, or point the run at a different session. Codex’s -c key=value in particular can rewrite sandbox and approval policy for the invocation. Nothing here is validated, and a security review of the permission posture means little without also reviewing whatever is passed here.

Arguments are passed straight to the binary without a shell.

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

Constrain the answer to a JSON Schema.

The agent is asked to return a value conforming to schema, which Outcome::structured then carries already parsed. Useful when the answer is data rather than prose: a set of review findings, an extraction, a classification. Reading it beats parsing prose, which is a guess about formatting the model never promised.

The two CLIs that support this take it differently, and the difference is hidden: Claude accepts the schema inline, Codex reads it from a file this crate writes for the run and removes afterwards. Copilot 1.0.75 has no schema support, so asking is crate::Error::Unsupported rather than a prose answer presented as data.

The schema is passed through unvalidated; a malformed one surfaces as the agent’s own error.

Write the schema strictly

Codex sends it to OpenAI’s structured-output API, which rejects anything permissive. Every object needs "additionalProperties": false and every property listed in required, or the request fails with a 400 before the model runs:

'additionalProperties' is required to be supplied and to be false

Claude is more forgiving, so a schema that works there can still fail on Codex. Writing to the stricter rule keeps one schema usable for both.

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

Continue an earlier conversation by its native id, bypassing the session store. Prefer Request::session unless you are tracking ids yourself.

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

Start a new conversation under an id you choose, rather than one the agent picks.

Useful when a host already has its own identifier for a thread and wants the agent’s session to match it, with no mapping table in between. The id is known before the process starts, so the association survives a run that dies mid-turn.

Only Claude and Copilot accept an assigned id (SessionSupport::Minted). Codex reveals its thread_id only in its own output, so this is crate::Error::Unsupported for it, raised when the argv is built rather than silently starting an unrelated session.

Both CLIs require a valid UUID here; this crate passes the string through without checking, so a non-UUID surfaces as the agent’s own error.

pub fn session( self, store: &SessionStore, project: impl AsRef<Path>, name: impl Into<String>, fork: bool, ) -> Result<Self>

Attach this run to a caller-owned session name.

The store decides whether this turn creates, continues, or forks, and the binding is written back once the run yields an id. fork branches a new conversation off the stored one instead of appending to it.

The store is cloned into the request so the run can write the binding back without borrowing it. That clone is a PathBuf, not the sessions themselves: records are read and written on demand and never held in memory, so this stays cheap however many sessions exist.

Errors

crate::Error::SessionConflict if the name belongs to another agent, or crate::Error::Unsupported if this agent cannot fork or has no session id at all.

pub fn effective_format(&self) -> Format

The format this request will actually use.

pub fn session_phase(&self) -> Option<Phase>

Whether this turn opens, continues, or branches its named session. None when the request is not attached to one.

Known before the run starts, so a UI can label the turn up front.

pub fn argv(&self) -> Result<Vec<String>>

The full command line, for logging or for showing a user exactly what will run before they approve it.

Errors

crate::Error::Unsupported if the agent cannot honour this request.

Trait Implementations

impl Clone for Request

fn clone(&self) -> Request

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Request

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.