Struct PromptRequest 

pub struct PromptRequest { /* private fields */ }

Supplies one foreground prompt and its optional portable overrides.

use agents_kit::{
    model::ReasoningEffort,
    prompt::PromptRequest,
};

let request = PromptRequest::new("Summarize the current task")?
    .with_reasoning_effort(ReasoningEffort::medium());
assert_eq!(request.text(), "Summarize the current task");

Implementations

impl PromptRequest

pub fn new(text: impl Into<String>) -> Result<Self, KitError>

Validates and constructs a request with no overrides.

Prompt text is retained exactly, including whitespace.

Errors

An empty prompt returns InvalidInput.

use agents_kit::prompt::PromptRequest;
let request = PromptRequest::new("Hello")?;
assert_eq!(request.text(), "Hello");
assert!(PromptRequest::new("").is_err());

pub fn with_cwd(self, cwd: PathBuf) -> Result<Self, KitError>

Sets a validated path relative to the active workspace context.

This path is relative to the active workspace, not the caller process.

Errors

Absolute paths, parent traversal, and invalid portable components return InvalidInput.

use agents_kit::prompt::PromptRequest;
let request = PromptRequest::new("Hello")?;
let request = request.with_cwd("src".into())?;
assert_eq!(request.cwd(), Some(std::path::Path::new("src")));

pub fn with_model(self, model: ModelSelector) -> Self

Sets the model selector for this prompt.

Availability is validated by the selected backend when submitting the prompt.

use agents_kit::prompt::PromptRequest;
let request = PromptRequest::new("Hello")?;
let request = request.with_model(agents_kit::model::ModelSelector::new("model-id")?);
assert_eq!(request.model().unwrap().as_str(), "model-id");

pub fn with_reasoning_effort(self, reasoning_effort: ReasoningEffort) -> Self

Sets the reasoning effort for this prompt.

The value must be supported by the selected backend and model; setting it does not validate availability. See the backend restrictions.

use agents_kit::prompt::PromptRequest;
let request = PromptRequest::new("Hello")?;
let request = request.with_reasoning_effort(agents_kit::model::ReasoningEffort::low());
assert_eq!(request.reasoning_effort(), Some(&agents_kit::model::ReasoningEffort::low()));

pub fn with_personality(self, personality: PersonalitySelector) -> Self

Sets the personality selector for this prompt.

This retains the caller value without validating backend support. The supplied Codex, OpenCode and Custom implementations currently reject explicit personality selection; caller backends may advertise and support it. See crate::model.

use agents_kit::prompt::PromptRequest;
let request = PromptRequest::new("Hello")?;
let request = request.with_personality(agents_kit::model::PersonalitySelector::new("concise")?);
assert_eq!(request.personality().unwrap().as_str(), "concise");

pub fn with_instructions( self, instructions: impl Into<String>, ) -> Result<Self, KitError>

Sets nonempty prompt-level instructions.

Text is preserved without trimming.

Errors

Empty instructions return InvalidInput.

use agents_kit::prompt::PromptRequest;
let request = PromptRequest::new("Hello")?;
let request = request.with_instructions("Be concise.")?;
assert_eq!(request.instructions(), Some("Be concise."));

pub fn with_knowledge_policy( self, policy: KnowledgePolicy, ) -> Result<Self, KitError>

Sets the effective managed-knowledge policy for this prompt.

This configures private retrieval; it does not install a model-visible tool.

Errors

An Only policy with no scopes or duplicate scopes returns InvalidInput.

use agents_kit::prompt::PromptRequest;
let request = PromptRequest::new("Hello")?;
let request = request.with_knowledge_policy(agents_kit::knowledge::KnowledgePolicy::Disabled)?;
assert_eq!(request.knowledge_policy(), Some(&agents_kit::knowledge::KnowledgePolicy::Disabled));

pub fn with_timeout(self, timeout: Duration) -> Result<Self, KitError>

Sets a nonzero foreground prompt timeout that starts after admission.

The timeout bounds execution after admission; it does not renew lifecycle deadlines.

Errors

A zero timeout returns InvalidInput.

use agents_kit::prompt::PromptRequest;
let request = PromptRequest::new("Hello")?;
let request = request.with_timeout(std::time::Duration::from_secs(20))?;
assert_eq!(request.timeout(), Some(std::time::Duration::from_secs(20)));

pub fn with_structured_output( self, structured_output: StructuredOutputRequest, ) -> Self

Requests strict output matching the supplied schema.

Selected backends may reject unsupported structured-output execution.

use agents_kit::prompt::PromptRequest;
let request = PromptRequest::new("Hello")?;
let schema = agents_kit::prompt::StructuredOutputRequest::new(serde_json::json!({"type":"string"}))?;
let request = request.with_structured_output(schema);
assert!(request.structured_output().is_some());

pub fn with_tool_selection( self, selection: ToolSelection, ) -> Result<Self, KitError>

Sets the portable tool-selection override.

A restricted catalog is distinct from requiring a call.

Errors

Empty named selections, duplicate names, or invalid portable names return InvalidInput.

use agents_kit::prompt::PromptRequest;
let request = PromptRequest::new("Hello")?;
let request = request.with_tool_selection(agents_kit::tool::ToolSelection::None)?;
assert_eq!(request.tool_selection(), Some(&agents_kit::tool::ToolSelection::None));

pub fn text(&self) -> &str

Returns the required prompt text.

use agents_kit::prompt::PromptRequest;
let request = PromptRequest::new("Hello")?;
assert_eq!(request.text(), "Hello");

pub fn cwd(&self) -> Option<&Path>

Returns the optional workspace-relative cwd override.

use agents_kit::prompt::PromptRequest;
let request = PromptRequest::new("Hello")?;
assert_eq!(request.cwd(), None);

pub fn model(&self) -> Option<&ModelSelector>

Returns the optional model override.

use agents_kit::prompt::PromptRequest;
let request = PromptRequest::new("Hello")?;
assert_eq!(request.model(), None);

pub fn reasoning_effort(&self) -> Option<&ReasoningEffort>

Returns the optional reasoning-effort override.

use agents_kit::prompt::PromptRequest;
let request = PromptRequest::new("Hello")?;
assert_eq!(request.reasoning_effort(), None);

pub fn personality(&self) -> Option<&PersonalitySelector>

Returns the optional personality override.

use agents_kit::prompt::PromptRequest;
let request = PromptRequest::new("Hello")?;
assert_eq!(request.personality(), None);

pub fn instructions(&self) -> Option<&str>

Returns the optional prompt-level instructions.

use agents_kit::prompt::PromptRequest;
let request = PromptRequest::new("Hello")?;
assert_eq!(request.instructions(), None);

pub fn knowledge_policy(&self) -> Option<&KnowledgePolicy>

Returns the optional managed-knowledge policy override.

use agents_kit::prompt::PromptRequest;
let request = PromptRequest::new("Hello")?;
assert_eq!(request.knowledge_policy(), None);

pub fn timeout(&self) -> Option<Duration>

Returns the optional foreground prompt timeout.

use agents_kit::prompt::PromptRequest;
let request = PromptRequest::new("Hello")?;
assert_eq!(request.timeout(), None);

pub fn structured_output(&self) -> Option<&StructuredOutputRequest>

Returns the optional strict structured-output request.

use agents_kit::prompt::PromptRequest;
let request = PromptRequest::new("Hello")?;
assert_eq!(request.structured_output(), None);

pub fn tool_selection(&self) -> Option<&ToolSelection>

Returns the optional portable tool-selection override.

use agents_kit::prompt::PromptRequest;
let request = PromptRequest::new("Hello")?;
assert_eq!(request.tool_selection(), None);

Trait Implementations

impl Clone for PromptRequest

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for PromptRequest

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

Formats the value using the given formatter.