molo_core/
agent.rs

1//! Step-wise agent action protocol shared by runtimes and harnesses.
2
3use crate::effect::{EffectObservation, EffectRequest};
4use crate::provider::{ChatRequest, ChatResponse};
5use crate::run::{RunMetadata, RunOutput};
6
7/// Provider request emitted by a step-wise agent kernel.
8#[derive(Debug, Clone, PartialEq)]
9pub struct ModelRequest {
10    /// Model request id, unique within the run or agent implementation.
11    pub id: String,
12    /// Provider chat request to execute.
13    pub chat: ChatRequest,
14    /// Framework/application metadata.
15    pub metadata: RunMetadata,
16}
17
18impl ModelRequest {
19    /// Constructs a model request.
20    pub fn new(id: impl Into<String>, chat: ChatRequest) -> Self {
21        Self {
22            id: id.into(),
23            chat,
24            metadata: RunMetadata::new(),
25        }
26    }
27
28    /// Sets framework/application metadata.
29    pub fn with_metadata(mut self, metadata: RunMetadata) -> Self {
30        self.metadata = metadata;
31        self
32    }
33}
34
35/// Successful provider response observed by a step-wise agent kernel.
36#[derive(Debug, Clone, PartialEq)]
37pub struct ModelObservation {
38    /// Model request id matching [`ModelRequest::id`].
39    pub request_id: String,
40    /// Provider response.
41    pub response: ChatResponse,
42    /// Framework/application metadata.
43    pub metadata: RunMetadata,
44}
45
46impl ModelObservation {
47    /// Constructs a model observation.
48    pub fn new(request_id: impl Into<String>, response: ChatResponse) -> Self {
49        Self {
50            request_id: request_id.into(),
51            response,
52            metadata: RunMetadata::new(),
53        }
54    }
55
56    /// Sets framework/application metadata.
57    pub fn with_metadata(mut self, metadata: RunMetadata) -> Self {
58        self.metadata = metadata;
59        self
60    }
61}
62
63/// Observation fed back to a step-wise agent kernel.
64#[derive(Debug, Clone, PartialEq)]
65#[non_exhaustive]
66pub enum Observation {
67    /// Successful model response.
68    Model(ModelObservation),
69    /// Effect observation produced by an outer harness.
70    Effect(EffectObservation),
71    /// Batch effect observations produced by an outer harness.
72    ///
73    /// This is the companion to [`AgentAction::RequestEffects`]. The outer
74    /// runtime may execute the requests sequentially or in parallel, then
75    /// feeds the completed set back to the kernel as one step.
76    Effects(Vec<EffectObservation>),
77}
78
79/// Next action requested by a step-wise agent kernel.
80#[derive(Debug, Clone, PartialEq)]
81#[non_exhaustive]
82pub enum AgentAction {
83    /// The run is complete.
84    Respond {
85        /// Final structured run output.
86        output: RunOutput,
87    },
88    /// The outer runtime should execute a provider request and feed back
89    /// [`Observation::Model`].
90    RequestModel {
91        /// Provider request.
92        request: ModelRequest,
93    },
94    /// The outer runtime should govern and execute an effect request, then
95    /// feed back [`Observation::Effect`].
96    RequestEffect {
97        /// Effect request.
98        request: EffectRequest,
99    },
100    /// The outer runtime should govern and execute multiple effect requests,
101    /// then feed back [`Observation::Effects`].
102    RequestEffects {
103        /// Effect requests.
104        requests: Vec<EffectRequest>,
105    },
106}
molo_core/agent.rs

molo_core/
agent.rs
