Struct Agent

Source

pub struct Agent { /* private fields */ }

Expand description

Stateful agent runtime with conversation history and tool registry.

Implementations§

Source §

impl Agent

Source

pub fn builder() -> AgentBuilder

Creates a new builder.

Examples found in repository ?

examples/local_loop.rs (line 89)

88fn build_agent(responses: Vec<Result<ModelCompletion, ProviderError>>) -> Agent {
89    Agent::builder()
90        .model(ScriptedModel::new(responses))
91        .tool(add_tool())
92        .tool(done_tool())
93        .build()
94        .expect("agent builds")
95}

More examples

Hide additional examples

examples/di_override.rs (line 96)

43async fn main() -> Result<(), Box<dyn Error>> {
44    let read_dep_tool = ToolSpec::new("read_dep", "read injected value")
45        .with_schema(json!({
46            "type": "object",
47            "properties": {},
48            "required": [],
49            "additionalProperties": false
50        }))?
51        .with_handler(|_args, deps| {
52            let value = deps.get::<u32>().map(|v| *v).unwrap_or_default();
53            async move { Ok(ToolOutcome::Text(value.to_string())) }
54        });
55
56    let done_tool = ToolSpec::new("done", "finish")
57        .with_schema(json!({
58            "type": "object",
59            "properties": {
60                "message": {"type": "string"}
61            },
62            "required": ["message"],
63            "additionalProperties": false
64        }))?
65        .with_handler(|args, _deps| async move {
66            let message = args
67                .get("message")
68                .and_then(|v| v.as_str())
69                .unwrap_or("done");
70            Ok(ToolOutcome::Done(message.to_string()))
71        });
72
73    let model = ScriptedModel::new(vec![
74        Ok(ModelCompletion {
75            text: None,
76            thinking: None,
77            tool_calls: vec![ModelToolCall {
78                id: "call_1".to_string(),
79                name: "read_dep".to_string(),
80                arguments: json!({}),
81            }],
82            usage: None,
83        }),
84        Ok(ModelCompletion {
85            text: None,
86            thinking: None,
87            tool_calls: vec![ModelToolCall {
88                id: "call_2".to_string(),
89                name: "done".to_string(),
90                arguments: json!({"message": "dependency override applied"}),
91            }],
92            usage: None,
93        }),
94    ]);
95
96    let mut agent = Agent::builder()
97        .model(model)
98        .tool(read_dep_tool)
99        .tool(done_tool)
100        .dependency(1_u32)
101        .dependency_override(9_u32)
102        .build()?;
103
104    let response = agent.query("use dependency").await?;
105    println!("final: {response}");
106
107    Ok(())
108}

Source

pub fn clear_history(&mut self)

Clears conversation history and resets message-id counter.

Source

pub fn load_history(&mut self, messages: Vec<ModelMessage>)

Replaces history with a preloaded message sequence.

Source

pub fn messages_len(&self) -> usize

Returns number of history messages.

Source

pub fn messages(&self) -> &[ModelMessage]

Returns current history slice.

Source

pub async fn query( &mut self, user_message: impl Into<String>, ) -> Result<String, AgentError>

Runs one user query and returns the final response text.

Examples found in repository ?

examples/di_override.rs (line 104)

43async fn main() -> Result<(), Box<dyn Error>> {
44    let read_dep_tool = ToolSpec::new("read_dep", "read injected value")
45        .with_schema(json!({
46            "type": "object",
47            "properties": {},
48            "required": [],
49            "additionalProperties": false
50        }))?
51        .with_handler(|_args, deps| {
52            let value = deps.get::<u32>().map(|v| *v).unwrap_or_default();
53            async move { Ok(ToolOutcome::Text(value.to_string())) }
54        });
55
56    let done_tool = ToolSpec::new("done", "finish")
57        .with_schema(json!({
58            "type": "object",
59            "properties": {
60                "message": {"type": "string"}
61            },
62            "required": ["message"],
63            "additionalProperties": false
64        }))?
65        .with_handler(|args, _deps| async move {
66            let message = args
67                .get("message")
68                .and_then(|v| v.as_str())
69                .unwrap_or("done");
70            Ok(ToolOutcome::Done(message.to_string()))
71        });
72
73    let model = ScriptedModel::new(vec![
74        Ok(ModelCompletion {
75            text: None,
76            thinking: None,
77            tool_calls: vec![ModelToolCall {
78                id: "call_1".to_string(),
79                name: "read_dep".to_string(),
80                arguments: json!({}),
81            }],
82            usage: None,
83        }),
84        Ok(ModelCompletion {
85            text: None,
86            thinking: None,
87            tool_calls: vec![ModelToolCall {
88                id: "call_2".to_string(),
89                name: "done".to_string(),
90                arguments: json!({"message": "dependency override applied"}),
91            }],
92            usage: None,
93        }),
94    ]);
95
96    let mut agent = Agent::builder()
97        .model(model)
98        .tool(read_dep_tool)
99        .tool(done_tool)
100        .dependency(1_u32)
101        .dependency_override(9_u32)
102        .build()?;
103
104    let response = agent.query("use dependency").await?;
105    println!("final: {response}");
106
107    Ok(())
108}

More examples

Hide additional examples

examples/local_loop.rs (line 122)

98async fn main() -> Result<(), Box<dyn Error>> {
99    let mut agent = build_agent(vec![
100        Ok(ModelCompletion {
101            text: Some("Working on it".to_string()),
102            thinking: Some("Need arithmetic".to_string()),
103            tool_calls: vec![ModelToolCall {
104                id: "call_1".to_string(),
105                name: "add".to_string(),
106                arguments: json!({"a": 2, "b": 3}),
107            }],
108            usage: None,
109        }),
110        Ok(ModelCompletion {
111            text: None,
112            thinking: None,
113            tool_calls: vec![ModelToolCall {
114                id: "call_2".to_string(),
115                name: "done".to_string(),
116                arguments: json!({"message": "2 + 3 = 5"}),
117            }],
118            usage: None,
119        }),
120    ]);
121
122    let final_response = agent.query("What is 2 + 3?").await?;
123    println!("query final: {final_response}");
124
125    let mut streaming_agent = build_agent(vec![
126        Ok(ModelCompletion {
127            text: Some("Streaming run".to_string()),
128            thinking: Some("Will call add and done".to_string()),
129            tool_calls: vec![ModelToolCall {
130                id: "call_3".to_string(),
131                name: "add".to_string(),
132                arguments: json!({"a": 10, "b": 7}),
133            }],
134            usage: None,
135        }),
136        Ok(ModelCompletion {
137            text: None,
138            thinking: None,
139            tool_calls: vec![ModelToolCall {
140                id: "call_4".to_string(),
141                name: "done".to_string(),
142                arguments: json!({"message": "10 + 7 = 17"}),
143            }],
144            usage: None,
145        }),
146    ]);
147
148    let stream = streaming_agent.query_stream("What is 10 + 7?");
149    futures_util::pin_mut!(stream);
150    while let Some(event) = stream.next().await {
151        match event? {
152            AgentEvent::MessageStart { message_id, role } => {
153                println!("message start [{message_id}] {role:?}")
154            }
155            AgentEvent::MessageComplete {
156                message_id,
157                content,
158            } => println!("message complete [{message_id}]: {content}"),
159            AgentEvent::HiddenUserMessage { content } => println!("hidden: {content}"),
160            AgentEvent::StepStart {
161                step_id,
162                title,
163                step_number,
164            } => println!("step start [{step_id}] #{step_number} {title}"),
165            AgentEvent::StepComplete {
166                step_id,
167                status,
168                duration_ms,
169            } => println!("step complete [{step_id}] {status:?} ({duration_ms} ms)"),
170            AgentEvent::Thinking { content } => println!("thinking: {content}"),
171            AgentEvent::Text { content } => println!("text: {content}"),
172            AgentEvent::ToolCall {
173                tool,
174                args_json,
175                tool_call_id,
176            } => println!("tool call [{tool_call_id}] {tool}: {args_json}"),
177            AgentEvent::ToolResult {
178                tool,
179                result_text,
180                tool_call_id,
181                is_error,
182            } => println!("tool result [{tool_call_id}] {tool}: {result_text} (error={is_error})"),
183            AgentEvent::FinalResponse { content } => println!("stream final: {content}"),
184        }
185    }
186
187    Ok(())
188}

Source

pub fn query_stream( &mut self, user_message: impl Into<String>, ) -> impl Stream<Item = Result<AgentEvent, AgentError>> + '_

Runs one user query and streams intermediate events.

Examples found in repository ?

examples/local_loop.rs (line 148)

98async fn main() -> Result<(), Box<dyn Error>> {
99    let mut agent = build_agent(vec![
100        Ok(ModelCompletion {
101            text: Some("Working on it".to_string()),
102            thinking: Some("Need arithmetic".to_string()),
103            tool_calls: vec![ModelToolCall {
104                id: "call_1".to_string(),
105                name: "add".to_string(),
106                arguments: json!({"a": 2, "b": 3}),
107            }],
108            usage: None,
109        }),
110        Ok(ModelCompletion {
111            text: None,
112            thinking: None,
113            tool_calls: vec![ModelToolCall {
114                id: "call_2".to_string(),
115                name: "done".to_string(),
116                arguments: json!({"message": "2 + 3 = 5"}),
117            }],
118            usage: None,
119        }),
120    ]);
121
122    let final_response = agent.query("What is 2 + 3?").await?;
123    println!("query final: {final_response}");
124
125    let mut streaming_agent = build_agent(vec![
126        Ok(ModelCompletion {
127            text: Some("Streaming run".to_string()),
128            thinking: Some("Will call add and done".to_string()),
129            tool_calls: vec![ModelToolCall {
130                id: "call_3".to_string(),
131                name: "add".to_string(),
132                arguments: json!({"a": 10, "b": 7}),
133            }],
134            usage: None,
135        }),
136        Ok(ModelCompletion {
137            text: None,
138            thinking: None,
139            tool_calls: vec![ModelToolCall {
140                id: "call_4".to_string(),
141                name: "done".to_string(),
142                arguments: json!({"message": "10 + 7 = 17"}),
143            }],
144            usage: None,
145        }),
146    ]);
147
148    let stream = streaming_agent.query_stream("What is 10 + 7?");
149    futures_util::pin_mut!(stream);
150    while let Some(event) = stream.next().await {
151        match event? {
152            AgentEvent::MessageStart { message_id, role } => {
153                println!("message start [{message_id}] {role:?}")
154            }
155            AgentEvent::MessageComplete {
156                message_id,
157                content,
158            } => println!("message complete [{message_id}]: {content}"),
159            AgentEvent::HiddenUserMessage { content } => println!("hidden: {content}"),
160            AgentEvent::StepStart {
161                step_id,
162                title,
163                step_number,
164            } => println!("step start [{step_id}] #{step_number} {title}"),
165            AgentEvent::StepComplete {
166                step_id,
167                status,
168                duration_ms,
169            } => println!("step complete [{step_id}] {status:?} ({duration_ms} ms)"),
170            AgentEvent::Thinking { content } => println!("thinking: {content}"),
171            AgentEvent::Text { content } => println!("text: {content}"),
172            AgentEvent::ToolCall {
173                tool,
174                args_json,
175                tool_call_id,
176            } => println!("tool call [{tool_call_id}] {tool}: {args_json}"),
177            AgentEvent::ToolResult {
178                tool,
179                result_text,
180                tool_call_id,
181                is_error,
182            } => println!("tool result [{tool_call_id}] {tool}: {result_text} (error={is_error})"),
183            AgentEvent::FinalResponse { content } => println!("stream final: {content}"),
184        }
185    }
186
187    Ok(())
188}