Skip to main content

agent/
types.rs

1use std::sync::Arc;
2
3use ai::http::BoxFuture;
4use ai::{
5    AbortSignal, AssistantMessage, AssistantMessageEvent, EventSink, Message, Model, ToolCall, ToolResultMessage,
6    TranscriptContext, Usage, UserContent,
7};
8use serde::{Deserialize, Serialize};
9use serde_json::Value;
10
11/// A transcript message. Upstream allows app-specific message kinds; none exist in Rust yet.
12pub type AgentMessage = Message;
13
14/// What a tool returns. `terminate` on every result of a batch ends the run after it.
15#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
16#[serde(rename_all = "camelCase")]
17pub struct AgentToolResult {
18    pub content: Vec<UserContent>,
19    pub details: Value,
20    #[serde(default, skip_serializing_if = "Option::is_none")]
21    pub usage: Option<Usage>,
22    #[serde(default, skip_serializing_if = "Option::is_none")]
23    pub terminate: Option<bool>,
24}
25
26impl AgentToolResult {
27    pub(crate) fn error(message: impl Into<String>) -> Self {
28        AgentToolResult {
29            content: vec![UserContent::Text(ai::TextContent {
30                text: message.into(),
31                text_signature: None,
32            })],
33            details: Value::Object(Default::default()),
34            usage: None,
35            terminate: None,
36        }
37    }
38}
39
40/// Receives partial results while a tool runs (`tool_execution_update`).
41pub type ToolUpdate<'a> = dyn Fn(AgentToolResult) + Send + Sync + 'a;
42
43/// An executable tool. `Err` is a thrown error: it becomes an error result with the message as text.
44pub trait AgentTool: Send + Sync {
45    /// The declaration the model sees.
46    fn tool(&self) -> &ai::Tool;
47    fn execute<'a>(
48        &'a self,
49        tool_call_id: &'a str,
50        args: Value,
51        signal: &'a AbortSignal,
52        on_update: &'a ToolUpdate<'a>,
53    ) -> BoxFuture<'a, Result<AgentToolResult, String>>;
54}
55
56/// `StreamFn`: one model response, events to `sink`, the final message returned (errors are messages).
57pub trait StreamFn: Send + Sync {
58    fn stream<'a>(
59        &'a self,
60        model: &'a Model,
61        context: &'a TranscriptContext,
62        options: &'a ai::SimpleStreamOptions,
63        sink: &'a mut EventSink<'_>,
64    ) -> BoxFuture<'a, AssistantMessage>;
65}
66
67#[derive(Clone, Default)]
68pub struct AgentContext {
69    pub messages: Vec<AgentMessage>,
70    pub tools: Vec<Arc<dyn AgentTool>>,
71}
72
73/// Polls queued messages; called between turns.
74pub type MessageSource = Box<dyn FnMut() -> Vec<AgentMessage> + Send>;
75
76/// What `beforeToolCall` sees: the call as the model sent it and its validated arguments.
77pub struct BeforeToolCallContext<'a> {
78    pub assistant_message: &'a AssistantMessage,
79    pub tool_call: &'a ToolCall,
80    pub args: &'a Value,
81    pub context: &'a AgentContext,
82}
83
84/// `beforeToolCall`'s decision: `block` fails the call with `reason` (default "Tool execution was blocked");
85/// `terminate` marks that error result as ending the run.
86#[derive(Clone, Debug, Default, PartialEq)]
87pub struct BeforeToolCallResult {
88    pub block: bool,
89    pub reason: Option<String>,
90    pub terminate: Option<bool>,
91}
92
93/// Runs after validation, before execution. `Err` is a thrown error: the call fails with the message as text.
94pub type BeforeToolCall = Arc<
95    dyn for<'a> Fn(
96            BeforeToolCallContext<'a>,
97            &'a AbortSignal,
98        ) -> BoxFuture<'a, Result<Option<BeforeToolCallResult>, String>>
99        + Send
100        + Sync,
101>;
102
103pub struct AgentLoopConfig {
104    pub model: Model,
105    /// `None` is thinking off.
106    pub reasoning: Option<String>,
107    pub session_id: Option<String>,
108    pub api_key: Option<String>,
109    pub get_steering_messages: Option<MessageSource>,
110    pub before_tool_call: Option<BeforeToolCall>,
111}
112
113impl AgentLoopConfig {
114    pub fn new(model: Model) -> Self {
115        AgentLoopConfig {
116            model,
117            reasoning: None,
118            session_id: None,
119            api_key: None,
120            get_steering_messages: None,
121            before_tool_call: None,
122        }
123    }
124}
125
126#[derive(Clone, Debug, PartialEq, Serialize)]
127#[serde(tag = "type", rename_all = "snake_case")]
128#[allow(clippy::large_enum_variant)] // events are short-lived; boxing every message would cost more than it saves
129pub enum AgentEvent {
130    AgentStart,
131    AgentEnd {
132        messages: Vec<AgentMessage>,
133    },
134    TurnStart,
135    TurnEnd {
136        message: AgentMessage,
137        #[serde(rename = "toolResults")]
138        tool_results: Vec<ToolResultMessage>,
139    },
140    MessageStart {
141        message: AgentMessage,
142    },
143    MessageUpdate {
144        message: AgentMessage,
145        #[serde(rename = "assistantMessageEvent")]
146        assistant_message_event: AssistantMessageEvent,
147    },
148    MessageEnd {
149        message: AgentMessage,
150    },
151    #[serde(rename_all = "camelCase")]
152    ToolExecutionStart {
153        tool_call_id: String,
154        tool_name: String,
155        args: Value,
156    },
157    #[serde(rename_all = "camelCase")]
158    ToolExecutionUpdate {
159        tool_call_id: String,
160        tool_name: String,
161        args: Value,
162        partial_result: AgentToolResult,
163    },
164    #[serde(rename_all = "camelCase")]
165    ToolExecutionEnd {
166        tool_call_id: String,
167        tool_name: String,
168        result: AgentToolResult,
169        is_error: bool,
170    },
171}