agents_runtime/agent/
builder.rs

1//! Fluent builder API for constructing Deep Agents
2//!
3//! This module provides the ConfigurableAgentBuilder that offers a fluent interface
4//! for building Deep Agents, mirroring the Python SDK's ergonomic construction patterns.
5
6use super::api::{create_async_deep_agent_from_config, create_deep_agent_from_config};
7use super::config::{DeepAgentConfig, SubAgentConfig, SummarizationConfig};
8use super::runtime::DeepAgent;
9use crate::middleware::HitlPolicy;
10use crate::planner::LlmBackedPlanner;
11use crate::providers::{
12    AnthropicConfig, AnthropicMessagesModel, GeminiChatModel, GeminiConfig, OpenAiChatModel,
13    OpenAiConfig,
14};
15use agents_core::agent::PlannerHandle;
16use agents_core::llm::LanguageModel;
17use agents_core::persistence::Checkpointer;
18use agents_core::tools::ToolBox;
19use std::collections::{HashMap, HashSet};
20use std::sync::Arc;
21
22/// Builder API to assemble a DeepAgent in a single fluent flow, mirroring the Python
23/// `create_configurable_agent` experience. Prefer this for ergonomic construction.
24pub struct ConfigurableAgentBuilder {
25    instructions: String,
26    planner: Option<Arc<dyn PlannerHandle>>,
27    tools: Vec<ToolBox>,
28    subagents: Vec<SubAgentConfig>,
29    summarization: Option<SummarizationConfig>,
30    tool_interrupts: HashMap<String, HitlPolicy>,
31    builtin_tools: Option<HashSet<String>>,
32    auto_general_purpose: bool,
33    enable_prompt_caching: bool,
34    checkpointer: Option<Arc<dyn Checkpointer>>,
35    event_dispatcher: Option<Arc<agents_core::events::EventDispatcher>>,
36}
37
38impl ConfigurableAgentBuilder {
39    pub fn new(instructions: impl Into<String>) -> Self {
40        Self {
41            instructions: instructions.into(),
42            planner: None,
43            tools: Vec::new(),
44            subagents: Vec::new(),
45            summarization: None,
46            tool_interrupts: HashMap::new(),
47            builtin_tools: None,
48            auto_general_purpose: true,
49            enable_prompt_caching: false,
50            checkpointer: None,
51            event_dispatcher: None,
52        }
53    }
54
55    /// Set the language model for the agent (mirrors Python's `model` parameter)
56    pub fn with_model(mut self, model: Arc<dyn LanguageModel>) -> Self {
57        let planner: Arc<dyn PlannerHandle> = Arc::new(LlmBackedPlanner::new(model));
58        self.planner = Some(planner);
59        self
60    }
61
62    /// Low-level planner API (for advanced use cases)
63    pub fn with_planner(mut self, planner: Arc<dyn PlannerHandle>) -> Self {
64        self.planner = Some(planner);
65        self
66    }
67
68    /// Convenience method for OpenAI models (equivalent to model=OpenAiChatModel)
69    pub fn with_openai_chat(self, config: OpenAiConfig) -> anyhow::Result<Self> {
70        let model = Arc::new(OpenAiChatModel::new(config)?);
71        Ok(self.with_model(model))
72    }
73
74    /// Convenience method for Anthropic models (equivalent to model=AnthropicMessagesModel)  
75    pub fn with_anthropic_messages(self, config: AnthropicConfig) -> anyhow::Result<Self> {
76        let model = Arc::new(AnthropicMessagesModel::new(config)?);
77        Ok(self.with_model(model))
78    }
79
80    /// Convenience method for Gemini models (equivalent to model=GeminiChatModel)
81    pub fn with_gemini_chat(self, config: GeminiConfig) -> anyhow::Result<Self> {
82        let model = Arc::new(GeminiChatModel::new(config)?);
83        Ok(self.with_model(model))
84    }
85
86    /// Add a tool to the agent
87    pub fn with_tool(mut self, tool: ToolBox) -> Self {
88        self.tools.push(tool);
89        self
90    }
91
92    /// Add multiple tools
93    pub fn with_tools<I>(mut self, tools: I) -> Self
94    where
95        I: IntoIterator<Item = ToolBox>,
96    {
97        self.tools.extend(tools);
98        self
99    }
100
101    pub fn with_subagent_config<I>(mut self, cfgs: I) -> Self
102    where
103        I: IntoIterator<Item = SubAgentConfig>,
104    {
105        self.subagents.extend(cfgs);
106        self
107    }
108
109    /// Convenience method: automatically create subagents from a list of tools.
110    /// Each tool becomes a specialized subagent with that single tool.
111    pub fn with_subagent_tools<I>(mut self, tools: I) -> Self
112    where
113        I: IntoIterator<Item = ToolBox>,
114    {
115        for tool in tools {
116            let tool_name = tool.schema().name.clone();
117            let subagent_config = SubAgentConfig::new(
118                format!("{}-agent", tool_name),
119                format!("Specialized agent for {} operations", tool_name),
120                format!(
121                    "You are a specialized agent. Use the {} tool to complete tasks efficiently.",
122                    tool_name
123                ),
124            )
125            .with_tools(vec![tool]);
126            self.subagents.push(subagent_config);
127        }
128        self
129    }
130
131    pub fn with_summarization(mut self, config: SummarizationConfig) -> Self {
132        self.summarization = Some(config);
133        self
134    }
135
136    pub fn with_tool_interrupt(mut self, tool_name: impl Into<String>, policy: HitlPolicy) -> Self {
137        self.tool_interrupts.insert(tool_name.into(), policy);
138        self
139    }
140
141    pub fn with_builtin_tools<I, S>(mut self, names: I) -> Self
142    where
143        I: IntoIterator<Item = S>,
144        S: Into<String>,
145    {
146        self.builtin_tools = Some(names.into_iter().map(|s| s.into()).collect());
147        self
148    }
149
150    pub fn with_auto_general_purpose(mut self, enabled: bool) -> Self {
151        self.auto_general_purpose = enabled;
152        self
153    }
154
155    pub fn with_prompt_caching(mut self, enabled: bool) -> Self {
156        self.enable_prompt_caching = enabled;
157        self
158    }
159
160    pub fn with_checkpointer(mut self, checkpointer: Arc<dyn Checkpointer>) -> Self {
161        self.checkpointer = Some(checkpointer);
162        self
163    }
164
165    pub fn with_event_broadcaster(
166        mut self,
167        broadcaster: Arc<dyn agents_core::events::EventBroadcaster>,
168    ) -> Self {
169        if self.event_dispatcher.is_none() {
170            self.event_dispatcher = Some(Arc::new(agents_core::events::EventDispatcher::new()));
171        }
172        if let Some(dispatcher) = Arc::get_mut(self.event_dispatcher.as_mut().unwrap()) {
173            dispatcher.add_broadcaster(broadcaster);
174        }
175        self
176    }
177
178    pub fn with_event_dispatcher(
179        mut self,
180        dispatcher: Arc<agents_core::events::EventDispatcher>,
181    ) -> Self {
182        self.event_dispatcher = Some(dispatcher);
183        self
184    }
185
186    pub fn build(self) -> anyhow::Result<DeepAgent> {
187        self.finalize(create_deep_agent_from_config)
188    }
189
190    /// Build an agent using the async constructor alias. This mirrors the Python
191    /// async_create_deep_agent entry point, while reusing the same runtime internals.
192    pub fn build_async(self) -> anyhow::Result<DeepAgent> {
193        self.finalize(create_async_deep_agent_from_config)
194    }
195
196    fn finalize(self, ctor: fn(DeepAgentConfig) -> DeepAgent) -> anyhow::Result<DeepAgent> {
197        let Self {
198            instructions,
199            planner,
200            tools,
201            subagents,
202            summarization,
203            tool_interrupts,
204            builtin_tools,
205            auto_general_purpose,
206            enable_prompt_caching,
207            checkpointer,
208            event_dispatcher,
209        } = self;
210
211        let planner = planner
212            .ok_or_else(|| anyhow::anyhow!("model must be set (use with_model or with_*_chat)"))?;
213
214        let mut cfg = DeepAgentConfig::new(instructions, planner)
215            .with_auto_general_purpose(auto_general_purpose)
216            .with_prompt_caching(enable_prompt_caching);
217
218        if let Some(ckpt) = checkpointer {
219            cfg = cfg.with_checkpointer(ckpt);
220        }
221        if let Some(dispatcher) = event_dispatcher {
222            cfg = cfg.with_event_dispatcher(dispatcher);
223        }
224        if let Some(sum) = summarization {
225            cfg = cfg.with_summarization(sum);
226        }
227        if let Some(selected) = builtin_tools {
228            cfg = cfg.with_builtin_tools(selected);
229        }
230        for (name, policy) in tool_interrupts {
231            cfg = cfg.with_tool_interrupt(name, policy);
232        }
233        for tool in tools {
234            cfg = cfg.with_tool(tool);
235        }
236        for sub_cfg in subagents {
237            cfg = cfg.with_subagent_config(sub_cfg);
238        }
239
240        Ok(ctor(cfg))
241    }
242}
agents_runtime/agent/builder.rs

agents_runtime/agent/
builder.rs
