conversation_api/execution/
agent.rs

1//! Commands accepted by the transport-independent Runtime.
2
3use serde::{Deserialize, Serialize};
4
5use crate::execution::{InvocationContext, Message, MessageId, ModelMode, RunId, UseCase};
6
7/// Mutation policy for tools that can change application state.
8#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
9#[serde(rename_all = "snake_case")]
10pub enum AccessMode {
11    /// Operations requiring approval are denied without creating an interaction.
12    /// Operations requiring no approval remain available.
13    NoAccess,
14    /// Mutating tools pause after prepare and require a user decision.
15    #[default]
16    Interactive,
17    /// Mutating tools may be committed without a user interaction.
18    FullAccess,
19}
20
21/// Per-run policy supplied by a deployment rather than selected through conditional compilation.
22#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
23#[serde(deny_unknown_fields)]
24pub struct RunOptions {
25    /// Logical LLM route selected by the deployment.
26    pub use_case: UseCase,
27    /// Logical quality/cost mode resolved by the deployment without exposing a provider or model ID.
28    pub model_mode: ModelMode,
29    /// Tool mutation policy.
30    pub access_mode: AccessMode,
31    /// Whether this run may expose any tools to the model.
32    pub allow_tools: bool,
33    /// Maximum LLM/tool loop steps requested by the caller.
34    pub max_steps: u32,
35    /// Optional maximum normalized credits the run may consume.
36    pub credit_budget: Option<u64>,
37    /// Requests additional sanitized diagnostic observations when enabled.
38    pub debug: bool,
39}
40
41/// User decisions submitted to a waiting run.
42#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
43#[serde(deny_unknown_fields)]
44pub struct Interaction {
45    /// Batch identifier emitted by `InteractionRequired`.
46    pub batch_id: MessageId,
47    /// One response for every waiting item in the batch.
48    pub responses: Vec<crate::InteractionResponse>,
49}
50
51/// Durable request waiting to enter the Runtime execution loop.
52#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
53pub struct QueuedRun {
54    /// Invocation identity frozen when the request is accepted.
55    pub context: InvocationContext,
56    /// User-supplied multimodal message.
57    pub message: Message,
58    /// Runtime policy frozen when the request is accepted.
59    pub options: RunOptions,
60}
61
62impl QueuedRun {
63    /// Returns the stable run identifier used for queue idempotency.
64    #[must_use]
65    pub fn run_id(&self) -> &RunId {
66        &self.context.run_id
67    }
68}
69
70/// Semantic commands understood by the Runtime.
71#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
72#[serde(tag = "type", rename_all = "snake_case")]
73#[serde(deny_unknown_fields)]
74pub enum AgentCommand {
75    /// Enqueues a new user message.
76    Enqueue {
77        /// Invocation identity and ownership.
78        context: InvocationContext,
79        /// User-supplied multimodal message.
80        message: Message,
81        /// Runtime policy for this run.
82        options: RunOptions,
83    },
84    /// Supplies a response to a pending interaction.
85    SubmitInteraction {
86        /// Invocation identity and ownership.
87        context: InvocationContext,
88        /// Submitted interaction.
89        interaction: Interaction,
90    },
91    /// Requests cancellation of the current run.
92    Cancel {
93        /// Invocation identity and ownership.
94        context: InvocationContext,
95    },
96}
conversation_api/execution/agent.rs

conversation_api/execution/
agent.rs
