use async_trait::async_trait;
use serde_json::{Map, Value};
#[derive(Debug, Clone, Default, PartialEq)]
pub struct CallbackContext {
fields: Map<String, Value>,
}
impl CallbackContext {
#[must_use]
pub fn new() -> Self {
Self::default()
}
#[must_use]
pub fn with_field(mut self, key: impl Into<String>, value: impl Into<Value>) -> Self {
self.fields.insert(key.into(), value.into());
self
}
#[must_use]
pub fn get(&self, key: &str) -> Option<&Value> {
self.fields.get(key)
}
#[must_use]
pub fn as_map(&self) -> &Map<String, Value> {
&self.fields
}
}
impl From<Map<String, Value>> for CallbackContext {
fn from(fields: Map<String, Value>) -> Self {
Self { fields }
}
}
#[async_trait]
pub trait CallbackHandler: Send + Sync {
async fn on_agent_start(&self, ctx: &CallbackContext) -> Option<Value> {
let _ = ctx;
None
}
async fn on_agent_end(&self, ctx: &CallbackContext) -> Option<Value> {
let _ = ctx;
None
}
async fn on_model_start(&self, ctx: &CallbackContext) -> Option<Value> {
let _ = ctx;
None
}
async fn on_model_end(&self, ctx: &CallbackContext) -> Option<Value> {
let _ = ctx;
None
}
async fn on_tool_start(&self, ctx: &CallbackContext) -> Option<Value> {
let _ = ctx;
None
}
async fn on_tool_end(&self, ctx: &CallbackContext) -> Option<Value> {
let _ = ctx;
None
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::sync::Mutex;
struct NoopHandler;
#[async_trait]
impl CallbackHandler for NoopHandler {}
#[tokio::test]
async fn test_default_hooks_return_none() {
let handler = NoopHandler;
let ctx = CallbackContext::new();
assert_eq!(handler.on_agent_start(&ctx).await, None);
assert_eq!(handler.on_agent_end(&ctx).await, None);
assert_eq!(handler.on_model_start(&ctx).await, None);
assert_eq!(handler.on_model_end(&ctx).await, None);
assert_eq!(handler.on_tool_start(&ctx).await, None);
assert_eq!(handler.on_tool_end(&ctx).await, None);
}
struct RecordingHandler {
calls: Mutex<Vec<&'static str>>,
}
impl RecordingHandler {
fn new() -> Self {
Self {
calls: Mutex::new(Vec::new()),
}
}
fn calls(&self) -> Vec<&'static str> {
self.calls
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.clone()
}
}
#[async_trait]
impl CallbackHandler for RecordingHandler {
async fn on_agent_start(&self, ctx: &CallbackContext) -> Option<Value> {
self.calls
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.push("on_agent_start");
ctx.get("input").cloned()
}
async fn on_agent_end(&self, _ctx: &CallbackContext) -> Option<Value> {
self.calls
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.push("on_agent_end");
Some(Value::String("agent_end".to_owned()))
}
async fn on_model_start(&self, ctx: &CallbackContext) -> Option<Value> {
self.calls
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.push("on_model_start");
ctx.get("messages").cloned()
}
async fn on_model_end(&self, ctx: &CallbackContext) -> Option<Value> {
self.calls
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.push("on_model_end");
ctx.get("llm_result").cloned()
}
async fn on_tool_start(&self, _ctx: &CallbackContext) -> Option<Value> {
self.calls
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.push("on_tool_start");
None
}
async fn on_tool_end(&self, _ctx: &CallbackContext) -> Option<Value> {
self.calls
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.push("on_tool_end");
Some(Value::String("tool_end".to_owned()))
}
}
#[tokio::test]
async fn test_all_six_hooks_invoked_and_recorded() {
let handler = RecordingHandler::new();
let start_ctx = CallbackContext::new().with_field("input", Value::String("hi".into()));
let model_start_ctx =
CallbackContext::new().with_field("messages", serde_json::json!(["hello"]));
let model_end_ctx =
CallbackContext::new().with_field("llm_result", Value::String("hi back".into()));
let empty_ctx = CallbackContext::new();
assert_eq!(
handler.on_agent_start(&start_ctx).await,
Some(Value::String("hi".to_owned()))
);
assert_eq!(
handler.on_agent_end(&empty_ctx).await,
Some(Value::String("agent_end".to_owned()))
);
assert_eq!(
handler.on_model_start(&model_start_ctx).await,
Some(serde_json::json!(["hello"]))
);
assert_eq!(
handler.on_model_end(&model_end_ctx).await,
Some(Value::String("hi back".to_owned()))
);
assert_eq!(handler.on_tool_start(&empty_ctx).await, None);
assert_eq!(
handler.on_tool_end(&empty_ctx).await,
Some(Value::String("tool_end".to_owned()))
);
assert_eq!(
handler.calls(),
vec![
"on_agent_start",
"on_agent_end",
"on_model_start",
"on_model_end",
"on_tool_start",
"on_tool_end",
]
);
}
#[tokio::test]
async fn test_usable_as_boxed_trait_object() {
let handlers: Vec<Box<dyn CallbackHandler>> =
vec![Box::new(NoopHandler), Box::new(RecordingHandler::new())];
let ctx = CallbackContext::new();
for handler in &handlers {
let _ = handler.on_agent_start(&ctx).await;
}
assert_eq!(handlers.len(), 2);
}
#[test]
fn test_callback_context_field_access() {
let ctx = CallbackContext::new()
.with_field("tool_name", Value::String("lookup_weather".to_owned()))
.with_field("arguments", serde_json::json!({"city": "Tokyo"}));
assert_eq!(
ctx.get("tool_name"),
Some(&Value::String("lookup_weather".to_owned()))
);
assert_eq!(
ctx.get("arguments"),
Some(&serde_json::json!({"city": "Tokyo"}))
);
assert_eq!(ctx.get("missing"), None);
assert_eq!(ctx.as_map().len(), 2);
}
#[test]
fn test_callback_context_from_map() {
let mut map = Map::new();
map.insert("k".to_owned(), Value::from(1));
let ctx = CallbackContext::from(map);
assert_eq!(ctx.get("k"), Some(&Value::from(1)));
}
}