open_agent/types/
message_blocks.rs

1/// Identifies the sender of a conversation message. Serializes as a lowercase string.
2#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
3#[serde(rename_all = "lowercase")]
4pub enum MessageRole {
5    /// System message that establishes agent behavior and context.
6    ///
7    /// Typically the first message in a conversation. Used for instructions,
8    /// personality definition, and constraints that apply throughout the
9    /// conversation.
10    System,
11
12    /// User message representing human or application input.
13    ///
14    /// The prompt or query that the agent should respond to. In multi-turn
15    /// conversations, user messages alternate with assistant messages.
16    User,
17
18    /// Assistant message containing the AI model's response.
19    ///
20    /// Can include text, tool use requests, or both. When the model wants to
21    /// call a tool, it includes ToolUseBlock content.
22    Assistant,
23
24    /// Tool result message containing function execution results.
25    ///
26    /// Sent back to the model after executing a requested tool. Contains the
27    /// tool's output that the model can use in its next response.
28    Tool,
29}
30
31/// A text, image, tool-call, or tool-result block.
32///
33/// Serializes as an object with a snake-case `type` tag. See [`Message`] for examples.
34#[derive(Debug, Clone, Serialize, Deserialize)]
35#[serde(tag = "type", rename_all = "snake_case")]
36pub enum ContentBlock {
37    /// Text content block containing a string message.
38    Text(TextBlock),
39
40    /// Image content block for vision-capable models.
41    Image(ImageBlock),
42
43    /// Tool use request from the model to execute a function.
44    ToolUse(ToolUseBlock),
45
46    /// Tool execution result sent back to the model.
47    ToolResult(ToolResultBlock),
48}
49
50/// A text block in a message or an incremental streamed text fragment.
51#[derive(Debug, Clone, Serialize, Deserialize)]
52pub struct TextBlock {
53    /// The text content.
54    pub text: String,
55}
56
57impl TextBlock {
58    /// Creates a text block.
59    pub fn new(text: impl Into<String>) -> Self {
60        Self { text: text.into() }
61    }
62}
63
64/// A model-requested tool call with an ID, name, and assembled JSON input.
65///
66/// The ID pairs this call with its [`ToolResultBlock`].
67#[derive(Debug, Clone, Serialize, Deserialize)]
68pub struct ToolUseBlock {
69    /// Unique identifier for this tool call.
70    ///
71    /// Generated by the model. Used to correlate the tool result back to
72    /// this specific request, especially when multiple tools are called.
73    id: String,
74
75    /// Name of the tool to execute.
76    ///
77    /// Must match the name of a tool that was provided in the agent's
78    /// configuration, otherwise execution will fail.
79    name: String,
80
81    /// JSON parameters to pass to the tool.
82    ///
83    /// The structure should match the tool's input schema. The tool's
84    /// execution function receives this value as input.
85    input: serde_json::Value,
86}
87
88impl ToolUseBlock {
89    /// Creates a tool call from its ID, name, and JSON input.
90    pub fn new(id: impl Into<String>, name: impl Into<String>, input: serde_json::Value) -> Self {
91        Self {
92            id: id.into(),
93            name: name.into(),
94            input,
95        }
96    }
97
98    /// Returns the unique identifier for this tool call.
99    pub fn id(&self) -> &str {
100        &self.id
101    }
102
103    /// Returns the name of the tool to execute.
104    pub fn name(&self) -> &str {
105        &self.name
106    }
107
108    /// Returns the JSON parameters for the tool.
109    pub fn input(&self) -> &serde_json::Value {
110        &self.input
111    }
112}
113
114/// A JSON tool result paired with the originating [`ToolUseBlock`] ID.
115#[derive(Debug, Clone, Serialize, Deserialize)]
116pub struct ToolResultBlock {
117    /// ID of the tool use request this result corresponds to.
118    ///
119    /// Must match the `id` field from the ToolUseBlock that requested
120    /// this tool execution. This correlation is essential for the model
121    /// to understand which tool call produced which result.
122    tool_use_id: String,
123
124    /// JSON result from executing the tool.
125    ///
126    /// Contains the tool's output data. Can be any valid JSON structure -
127    /// the model will interpret it based on the tool's description and
128    /// output schema.
129    content: serde_json::Value,
130}
131
132impl ToolResultBlock {
133    /// Creates a result associated with the supplied tool-call ID.
134    pub fn new(tool_use_id: impl Into<String>, content: serde_json::Value) -> Self {
135        Self {
136            tool_use_id: tool_use_id.into(),
137            content,
138        }
139    }
140
141    /// Returns the ID of the tool use request this result corresponds to.
142    pub fn tool_use_id(&self) -> &str {
143        &self.tool_use_id
144    }
145
146    /// Returns the JSON result from executing the tool.
147    pub fn content(&self) -> &serde_json::Value {
148        &self.content
149    }
150}
open_agent/types/message_blocks.rs

open_agent/types/
message_blocks.rs
