starweaver_runtime/
agent.rs

1//! Bare agent runtime.
2
3use std::sync::Arc;
4
5use starweaver_context::{AgentContext, AgentInfo, ModelConfig, ToolConfig};
6use starweaver_core::{AgentId, CancellationToken};
7use starweaver_model::{ModelAdapter, ModelRequestParameters, ModelSettings, OutputMode};
8use starweaver_tools::{DynToolset, ToolRegistry};
9
10use starweaver_usage::UsageLimits;
11
12use crate::{
13    agent::helpers::merge_request_params,
14    capability::{AgentCapability, CapabilityBundle, resolve_capability_order},
15    executor::{DirectAgentExecutor, DynAgentExecutor},
16    graph::{AgentGraphTrace, AgentNode, GraphError, inspect_graph},
17    instructions::DynDynamicInstruction,
18    output::{
19        DynOutputFunction, OutputPolicy, OutputSchema, OutputValidator, SchemaOutputFunction,
20    },
21    trace::{DynTraceRecorder, NoopTraceRecorder},
22};
23
24mod helpers;
25mod overrides;
26mod run_loop;
27mod run_loop_helpers;
28mod runtime_helpers;
29mod types;
30
31pub use overrides::AgentOverride;
32pub use types::{
33    AgentEndStrategy, AgentError, AgentInput, AgentResult, AgentRuntimePolicy,
34    AgentToolExecutionMode,
35};
36
37/// Minimal agent builder/runtime.
38#[derive(Clone)]
39pub struct Agent {
40    default_id: AgentId,
41    default_name: String,
42    model: Arc<dyn ModelAdapter>,
43    instructions: Vec<String>,
44    dynamic_instructions: Vec<DynDynamicInstruction>,
45    model_settings: Option<ModelSettings>,
46    request_params: ModelRequestParameters,
47    output_schema: Option<OutputSchema>,
48    output_validators: Vec<Arc<dyn OutputValidator>>,
49    output_functions: Vec<DynOutputFunction>,
50    usage_limits: Option<UsageLimits>,
51    tools: ToolRegistry,
52    toolsets: Vec<DynToolset>,
53    capabilities: Vec<Arc<dyn AgentCapability>>,
54    stream_observers: Vec<Arc<dyn AgentCapability>>,
55    cancellation_token: Option<CancellationToken>,
56    executor: DynAgentExecutor,
57    trace_recorder: DynTraceRecorder,
58    policy: AgentRuntimePolicy,
59    model_config: Option<ModelConfig>,
60    tool_config: Option<ToolConfig>,
61}
62
63impl Agent {
64    /// Create an agent with a model adapter.
65    #[must_use]
66    pub fn new(model: Arc<dyn ModelAdapter>) -> Self {
67        Self {
68            default_id: AgentId::default(),
69            default_name: AgentId::default().as_str().to_string(),
70            model,
71            instructions: Vec::new(),
72            dynamic_instructions: Vec::new(),
73            model_settings: None,
74            request_params: ModelRequestParameters::default(),
75            output_schema: None,
76            output_validators: Vec::new(),
77            output_functions: Vec::new(),
78            usage_limits: None,
79            tools: ToolRegistry::new(),
80            toolsets: Vec::new(),
81            capabilities: Vec::new(),
82            stream_observers: Vec::new(),
83            cancellation_token: None,
84            executor: Arc::new(DirectAgentExecutor),
85            trace_recorder: Arc::new(NoopTraceRecorder),
86            policy: AgentRuntimePolicy::default(),
87            model_config: None,
88            tool_config: None,
89        }
90    }
91
92    /// Return the default agent id used when this agent creates a context.
93    #[must_use]
94    pub const fn agent_id(&self) -> &AgentId {
95        &self.default_id
96    }
97
98    /// Return the default human-readable agent name.
99    #[must_use]
100    pub fn agent_name(&self) -> &str {
101        &self.default_name
102    }
103
104    /// Set the default agent id used when this agent creates a context.
105    #[must_use]
106    pub fn with_agent_id(mut self, agent_id: AgentId) -> Self {
107        self.default_id = agent_id;
108        self
109    }
110
111    /// Set the default human-readable agent name.
112    #[must_use]
113    pub fn with_agent_name(mut self, agent_name: impl Into<String>) -> Self {
114        self.default_name = agent_name.into();
115        self
116    }
117
118    /// Set both the default agent id and human-readable agent name.
119    #[must_use]
120    pub fn with_agent_identity(mut self, agent_id: AgentId, agent_name: impl Into<String>) -> Self {
121        self.default_id = agent_id;
122        self.default_name = agent_name.into();
123        self
124    }
125
126    /// Create a fresh context using this agent's configured identity.
127    #[must_use]
128    pub fn new_context(&self) -> AgentContext {
129        let mut context = AgentContext::new(self.default_id.clone());
130        self.apply_context_identity(&mut context);
131        context
132    }
133
134    fn apply_context_identity(&self, context: &mut AgentContext) {
135        context.agent_registry.insert(
136            self.default_id.as_str().to_string(),
137            AgentInfo::new(self.default_id.as_str(), self.default_name.clone()),
138        );
139        if self.default_name != self.default_id.as_str() {
140            context.metadata.insert(
141                "agent_name".to_string(),
142                serde_json::json!(self.default_name.as_str()),
143            );
144        }
145    }
146
147    /// Add a static instruction.
148    #[must_use]
149    pub fn with_instruction(mut self, instruction: impl Into<String>) -> Self {
150        self.instructions.push(instruction.into());
151        self
152    }
153
154    /// Add a dynamic instruction.
155    #[must_use]
156    pub fn with_dynamic_instruction(mut self, instruction: DynDynamicInstruction) -> Self {
157        self.dynamic_instructions.push(instruction);
158        self
159    }
160
161    /// Set default model settings.
162    #[must_use]
163    pub fn with_model_settings(mut self, settings: ModelSettings) -> Self {
164        self.model_settings = Some(settings);
165        self
166    }
167
168    /// Set default request parameters.
169    #[must_use]
170    pub fn with_request_params(mut self, params: ModelRequestParameters) -> Self {
171        self.request_params = params;
172        self
173    }
174
175    /// Set runtime tools.
176    #[must_use]
177    pub fn with_tools(mut self, tools: ToolRegistry) -> Self {
178        self.tools = tools;
179        self
180    }
181
182    /// Add one runtime toolset that is materialized for each agent context.
183    #[must_use]
184    pub fn with_toolset(mut self, toolset: DynToolset) -> Self {
185        self.toolsets.push(toolset);
186        self
187    }
188
189    /// Add many runtime toolsets that are materialized for each agent context.
190    #[must_use]
191    pub fn with_toolsets(mut self, toolsets: impl IntoIterator<Item = DynToolset>) -> Self {
192        self.toolsets.extend(toolsets);
193        self
194    }
195
196    /// Merge additional runtime tools into this agent.
197    #[must_use]
198    pub fn with_appended_tools(mut self, tools: &ToolRegistry) -> Self {
199        self.tools.insert_registry(tools);
200        self
201    }
202
203    /// Return a clone of the runtime tool registry.
204    #[must_use]
205    pub fn tools(&self) -> ToolRegistry {
206        let mut tools = self.tools.clone();
207        for toolset in &self.toolsets {
208            tools.insert_toolset(toolset);
209        }
210        tools
211    }
212
213    /// Set the agent-level retry default for runtime tools.
214    #[must_use]
215    pub const fn with_tool_retries(mut self, max_retries: usize) -> Self {
216        self.tools.set_max_retries(max_retries);
217        self
218    }
219
220    /// Set structured output schema.
221    #[must_use]
222    pub fn with_output_schema(mut self, schema: OutputSchema) -> Self {
223        self.output_schema = Some(schema);
224        self
225    }
226
227    /// Apply a complete output policy.
228    #[must_use]
229    pub fn with_output_policy(mut self, policy: OutputPolicy) -> Self {
230        let (schema, validators, functions, retries, mode, allow_text_output, allow_image_output) =
231            policy.into_parts();
232        let schema_output_function = match (schema.as_ref(), mode) {
233            (Some(schema), Some(OutputMode::Tool | OutputMode::ToolOrText)) => {
234                Some(Arc::new(SchemaOutputFunction::new(schema.clone())) as DynOutputFunction)
235            }
236            _ => None,
237        };
238        if let Some(schema) = schema {
239            self.output_schema = Some(schema);
240        }
241        self.output_validators.extend(validators);
242        if let Some(function) = schema_output_function {
243            self.output_functions.push(function);
244        }
245        self.output_functions.extend(functions);
246        if let Some(retries) = retries {
247            self.policy.output_retries = retries;
248        }
249        if let Some(mode) = mode {
250            self.request_params.output_mode = Some(mode);
251        }
252        if let Some(allow_text_output) = allow_text_output {
253            self.request_params.allow_text_output = Some(allow_text_output);
254        }
255        if let Some(allow_image_output) = allow_image_output {
256            self.request_params.allow_image_output = Some(allow_image_output);
257        }
258        self
259    }
260
261    /// Add an output validator.
262    #[must_use]
263    pub fn with_output_validator(mut self, validator: Arc<dyn OutputValidator>) -> Self {
264        self.output_validators.push(validator);
265        self
266    }
267
268    /// Add an output function.
269    #[must_use]
270    pub fn with_output_function(mut self, function: DynOutputFunction) -> Self {
271        self.output_functions.push(function);
272        self
273    }
274
275    /// Set usage limits.
276    #[must_use]
277    pub const fn with_usage_limits(mut self, limits: UsageLimits) -> Self {
278        self.usage_limits = Some(limits);
279        self
280    }
281
282    /// Set the full model config exposed to `AgentContext`.
283    #[must_use]
284    pub fn with_model_config(mut self, model_config: ModelConfig) -> Self {
285        self.model_config = Some(model_config);
286        self
287    }
288
289    /// Set tool-level configuration exposed to runtime tools.
290    #[must_use]
291    pub fn with_tool_config(mut self, tool_config: ToolConfig) -> Self {
292        self.tool_config = Some(tool_config);
293        self
294    }
295
296    /// Set the model context window exposed to `AgentContext` runtime instructions.
297    #[must_use]
298    pub fn with_context_window(mut self, context_window: u64) -> Self {
299        let mut model_config = self.model_config.unwrap_or_default();
300        model_config.context_window = Some(context_window);
301        self.model_config = Some(model_config);
302        self
303    }
304
305    /// Add a capability hook.
306    #[must_use]
307    pub fn with_capability(mut self, capability: Arc<dyn AgentCapability>) -> Self {
308        self.capabilities.push(capability);
309        self
310    }
311
312    pub(super) fn ordered_capabilities(&self) -> Result<Vec<Arc<dyn AgentCapability>>, AgentError> {
313        resolve_capability_order(&self.capabilities).map_err(AgentError::from)
314    }
315
316    pub(super) fn ordered_stream_observers(
317        &self,
318    ) -> Result<Vec<Arc<dyn AgentCapability>>, AgentError> {
319        resolve_capability_order(&self.stream_observers).map_err(AgentError::from)
320    }
321
322    pub(super) fn ordered_capabilities_for_validation(
323        &self,
324    ) -> Result<Vec<Arc<dyn AgentCapability>>, crate::capability::CapabilityError> {
325        resolve_capability_order(&self.capabilities)
326            .map_err(|error| crate::capability::CapabilityError::Failed(error.to_string()))
327    }
328
329    /// Add a stream observer hook.
330    #[must_use]
331    pub fn with_stream_observer(mut self, observer: Arc<dyn AgentCapability>) -> Self {
332        self.stream_observers.push(observer);
333        self
334    }
335
336    /// Set a cooperative cancellation token used by streaming callers.
337    #[must_use]
338    pub fn with_cancellation_token(mut self, token: CancellationToken) -> Self {
339        self.cancellation_token = Some(token);
340        self
341    }
342
343    /// Apply a composable capability bundle.
344    #[must_use]
345    pub fn with_capability_bundle(mut self, bundle: &dyn CapabilityBundle) -> Self {
346        self.apply_capability_bundle(bundle);
347        self
348    }
349
350    /// Set durable execution checkpoint handler.
351    #[must_use]
352    pub fn with_executor(mut self, executor: DynAgentExecutor) -> Self {
353        self.executor = executor;
354        self
355    }
356
357    /// Set runtime trace recorder.
358    #[must_use]
359    pub fn with_trace_recorder(mut self, recorder: DynTraceRecorder) -> Self {
360        self.trace_recorder = recorder;
361        self
362    }
363
364    /// Set runtime policy.
365    #[must_use]
366    pub const fn with_policy(mut self, policy: AgentRuntimePolicy) -> Self {
367        self.policy = policy;
368        self
369    }
370
371    /// Inspect graph transitions from a state snapshot.
372    ///
373    /// # Errors
374    ///
375    /// Returns an error when the inspected transition is invalid for the provided state.
376    pub fn inspect_graph(
377        &self,
378        start: AgentNode,
379        state: &crate::run::AgentRunState,
380    ) -> Result<AgentGraphTrace, GraphError> {
381        inspect_graph(
382            start,
383            state,
384            self.policy.max_steps,
385            self.policy.max_steps.saturating_mul(4),
386        )
387    }
388
389    /// Create a scoped override builder for tests and alternate run contexts.
390    #[must_use]
391    pub fn override_config(&self) -> AgentOverride {
392        AgentOverride::new(self.clone())
393    }
394
395    fn apply_capability_bundle(&mut self, bundle: &dyn CapabilityBundle) {
396        self.capabilities.extend(bundle.hooks());
397        self.stream_observers.extend(bundle.stream_observers());
398        self.instructions.extend(bundle.get_instructions());
399        self.dynamic_instructions
400            .extend(bundle.dynamic_instructions());
401        if let Some(tools) = bundle.get_tools() {
402            self.tools.insert_registry(&tools);
403        }
404        if let Some(settings) = bundle.model_settings() {
405            self.model_settings = Some(match &self.model_settings {
406                Some(current) => current.merge(&settings),
407                None => settings,
408            });
409        }
410        if let Some(params) = bundle.request_params() {
411            self.request_params = merge_request_params(&self.request_params, &params);
412        }
413        self.output_functions.extend(bundle.output_functions());
414        self.output_validators.extend(bundle.output_validators());
415        if let Some(limits) = bundle.usage_limits() {
416            self.usage_limits = Some(limits);
417        }
418    }
419}
starweaver_runtime/agent.rs

starweaver_runtime/
agent.rs
