agents 0.3.0

Facade crate for building typed Rust agents
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

use std::future::Future;
use std::pin::Pin;
use std::sync::Arc;

use async_trait::async_trait;
use serde::{Deserialize, Serialize};
use serde_json::Value;

use crate::agent::context::{ContextChunk, ContextStrategy};
use crate::agent::error::{AgentError, AgentResult};

/// Typed tool call plus its serialized envelope metadata.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ToolCallEnvelope<C> {
    pub call_id: String,
    pub name: String,
    pub arguments: Value,
    pub call: C,
}

impl<C> ToolCallEnvelope<C> {
    pub fn to_context_chunk(&self, strategy: ContextStrategy) -> ContextChunk {
        ContextChunk::ToolCall {
            strategy,
            id: self.call_id.clone(),
            name: self.name.clone(),
            args: self.arguments.clone(),
        }
    }
}

/// Result of executing a tool call.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "status", rename_all = "snake_case")]
pub enum ToolExecutionResult<T> {
    Ok { data: T },
    Error { message: String },
}

/// Typed tool result plus the originating call id.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ToolResultEnvelope<T> {
    pub call_id: String,
    #[serde(flatten)]
    pub result: ToolExecutionResult<T>,
}

impl<T> ToolResultEnvelope<T>
where
    T: Serialize,
{
    pub fn to_context_chunk(&self, strategy: ContextStrategy) -> AgentResult<ContextChunk> {
        let value = serde_json::to_value(self).map_err(|error| AgentError::ToolResultEncoding {
            reason: error.to_string(),
        })?;

        Ok(ContextChunk::ToolResult {
            strategy,
            id: self.call_id.clone(),
            result: value,
        })
    }
}

/// Executes tool calls on behalf of an agent.
#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
pub trait ToolRunner<C, T>: Send + Sync {
    async fn run(&self, call: ToolCallEnvelope<C>) -> AgentResult<ToolResultEnvelope<T>>;
}

/// Tool runner that rejects all tool calls.
pub struct NoToolRunner;

#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
impl<C, R> ToolRunner<C, R> for NoToolRunner
where
    C: Send + Sync + 'static,
    R: Send + Sync + 'static,
{
    async fn run(&self, call: ToolCallEnvelope<C>) -> AgentResult<ToolResultEnvelope<R>> {
        Err(AgentError::ToolExecution {
            reason: format!("unexpected tool call with id {}", call.call_id),
        })
    }
}

type BoxedToolFuture<T> = Pin<Box<dyn Future<Output = AgentResult<ToolResultEnvelope<T>>> + Send>>;
type ToolCallback<C, T> = Arc<dyn Fn(ToolCallEnvelope<C>) -> BoxedToolFuture<T> + Send + Sync>;

/// Tool runner backed by an async callback.
pub struct CallbackToolRunner<C, T> {
    callback: ToolCallback<C, T>,
}

impl<C, T> CallbackToolRunner<C, T> {
    pub fn new<F, Fut>(callback: F) -> Self
    where
        F: Fn(ToolCallEnvelope<C>) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = AgentResult<ToolResultEnvelope<T>>> + Send + 'static,
    {
        Self {
            callback: Arc::new(move |call| Box::pin(callback(call))),
        }
    }
}

#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
impl<C, T> ToolRunner<C, T> for CallbackToolRunner<C, T>
where
    C: Send + Sync + 'static,
    T: Send + Sync + 'static,
{
    async fn run(&self, call: ToolCallEnvelope<C>) -> AgentResult<ToolResultEnvelope<T>> {
        (self.callback)(call).await
    }
}