use std::sync::Arc;
use serde_json::Value;
use tokio::sync::mpsc;
use crate::error::{Result, RustyError};
use crate::executor::GraphEvent;
use crate::graph::{Graph, GraphBuilder, Route};
use crate::journal::{Journal, PARENT_EVENT_KEY};
use crate::llm::{ChatMessage, ChatModel};
use crate::node::NodeOutput;
use crate::replay::{
RecordingChatModel, RecordingTool, ReplaySource, ReplayingChatModel, ReplayingTool,
};
use crate::tool::{ToolExecutor, ToolRegistry};
pub const MESSAGES_CHANNEL: &str = "messages";
pub const AGENT_NODE: &str = "agent";
pub const TOOLS_NODE: &str = "tools";
fn read_messages(state: &crate::state::State) -> Result<Vec<ChatMessage>> {
Ok(state
.get_as::<Vec<ChatMessage>>(MESSAGES_CHANNEL)?
.unwrap_or_default())
}
#[derive(Debug, Clone)]
enum EvidenceMode {
None,
Record(Journal),
Replay {
source: ReplaySource,
journal: Journal,
},
}
fn invocation_parent(ctx: &crate::node::NodeContext, node: &str) -> Result<String> {
ctx.config()
.extra
.get(PARENT_EVENT_KEY)
.and_then(Value::as_str)
.map(str::to_owned)
.ok_or_else(|| {
RustyError::Node(format!(
"node `{node}` is wired for Flight Recorder evidence but the run supplied no \
`{PARENT_EVENT_KEY}` — drive the graph through `Executor::run`, which hands each \
invocation its node-input event id as the causal parent"
))
})
}
fn sorted_tool_schemas(tools: &ToolRegistry) -> Vec<Value> {
fn tool_name(schema: &Value) -> &str {
schema
.pointer("/function/name")
.and_then(Value::as_str)
.unwrap_or("")
}
let mut schemas = tools.schemas();
schemas.sort_by(|a, b| tool_name(a).cmp(tool_name(b)));
schemas
}
pub fn create_react_agent(model: Arc<dyn ChatModel>, tools: ToolRegistry) -> Result<Graph> {
build_react_agent(model, tools, None, EvidenceMode::None)
}
pub fn create_react_agent_streaming(
model: Arc<dyn ChatModel>,
tools: ToolRegistry,
token_tx: mpsc::Sender<GraphEvent>,
) -> Result<Graph> {
build_react_agent(model, tools, Some(token_tx), EvidenceMode::None)
}
pub fn create_react_agent_with_recording(
model: Arc<dyn ChatModel>,
tools: ToolRegistry,
journal: Journal,
) -> Result<Graph> {
build_react_agent(model, tools, None, EvidenceMode::Record(journal))
}
pub fn create_react_agent_replaying(
model: Arc<dyn ChatModel>,
tools: ToolRegistry,
source: ReplaySource,
journal: Journal,
) -> Result<Graph> {
build_react_agent(model, tools, None, EvidenceMode::Replay { source, journal })
}
fn build_react_agent(
model: Arc<dyn ChatModel>,
tools: ToolRegistry,
token_tx: Option<mpsc::Sender<GraphEvent>>,
evidence: EvidenceMode,
) -> Result<Graph> {
let tool_schemas = sorted_tool_schemas(&tools);
let tool_executor = ToolExecutor::new(tools);
let agent_node = {
let model = Arc::clone(&model);
let evidence = evidence.clone();
move |ctx: crate::node::NodeContext| {
let model = Arc::clone(&model);
let evidence = evidence.clone();
let tool_schemas = tool_schemas.clone();
let token_tx = token_tx.clone();
async move {
let messages = read_messages(ctx.state())?;
let model: Arc<dyn ChatModel> = match &evidence {
EvidenceMode::None => model,
EvidenceMode::Record(journal) => Arc::new(
RecordingChatModel::new(
model,
journal.clone(),
invocation_parent(&ctx, AGENT_NODE)?,
)
.node(AGENT_NODE),
),
EvidenceMode::Replay { source, journal } => Arc::new(ReplayingChatModel::new(
model,
source.clone(),
journal.clone(),
invocation_parent(&ctx, AGENT_NODE)?,
)),
};
tracing::debug!(
node = AGENT_NODE,
messages = messages.len(),
tools = tool_schemas.len(),
"calling chat model"
);
let response = match token_tx {
Some(tx) => {
model
.chat_stream(&messages, &tool_schemas, &mut |chunk| {
if !chunk.delta.is_empty() {
let _ = tx.try_send(GraphEvent::Token {
node: AGENT_NODE.to_owned(),
delta: chunk.delta,
});
}
})
.await?
}
None => model.chat(&messages, &tool_schemas).await?,
};
let appended = serde_json::to_value(&response.message)?;
Ok(NodeOutput::update(MESSAGES_CHANNEL, appended))
}
}
};
let tools_node = move |ctx: crate::node::NodeContext| {
let tool_executor = tool_executor.clone();
let evidence = evidence.clone();
async move {
let messages = read_messages(ctx.state())?;
let last = messages.last().ok_or_else(|| {
RustyError::Node(format!(
"node `{TOOLS_NODE}` ran with an empty `{MESSAGES_CHANNEL}` channel"
))
})?;
if !last.has_tool_calls() {
return Err(RustyError::Node(format!(
"node `{TOOLS_NODE}` expected the last message to carry tool calls"
)));
}
let tool_names: Vec<&str> = last
.tool_calls
.iter()
.map(|call| call.name.as_str())
.collect();
tracing::debug!(
node = TOOLS_NODE,
calls = last.tool_calls.len(),
tools = ?tool_names,
"dispatching tool calls"
);
let mut tool_executor =
match &evidence {
EvidenceMode::None => tool_executor,
EvidenceMode::Record(journal) => {
let parent = invocation_parent(&ctx, TOOLS_NODE)?;
let mut wrapped = ToolRegistry::new();
for name in tool_executor.registry().names() {
let tool = tool_executor.registry().get(name).expect(
"tool names iterated from a registry resolve in that registry",
);
wrapped.register_shared(Arc::new(
RecordingTool::new(tool, journal.clone(), parent.clone())
.node(TOOLS_NODE),
));
}
ToolExecutor::new(wrapped)
}
EvidenceMode::Replay { source, journal } => {
let parent = invocation_parent(&ctx, TOOLS_NODE)?;
let mut wrapped = ToolRegistry::new();
for name in tool_executor.registry().names() {
let tool = tool_executor.registry().get(name).expect(
"tool names iterated from a registry resolve in that registry",
);
wrapped.register_shared(Arc::new(ReplayingTool::new(
tool,
source.clone(),
journal.clone(),
parent.clone(),
)));
}
ToolExecutor::new(wrapped)
}
};
tool_executor = tool_executor
.with_middleware(ctx.middleware().clone())
.with_call_context(ctx.thread_id(), TOOLS_NODE);
if let Some(admission) = ctx.effect_admission() {
tool_executor = tool_executor.with_effect_admission(admission.clone());
}
let results = tool_executor.execute_batch(&last.tool_calls).await;
let appended = serde_json::to_value(&results)?;
Ok(NodeOutput::update(MESSAGES_CHANNEL, appended))
}
};
let mut builder = GraphBuilder::new();
builder.add_node(AGENT_NODE, agent_node);
builder.add_node(TOOLS_NODE, tools_node);
builder.set_entry_point(AGENT_NODE);
builder.add_conditional_edges(AGENT_NODE, |state| async move {
let needs_tools = read_messages(&state)?
.last()
.map(ChatMessage::has_tool_calls)
.unwrap_or(false);
Ok(if needs_tools {
Route::Node(TOOLS_NODE.to_owned())
} else {
Route::End
})
});
builder.add_edge(TOOLS_NODE, AGENT_NODE);
builder.compile()
}
#[cfg(test)]
mod tests {
use super::*;
use crate::graph::Edge;
use crate::llm::{ChatResponse, TokenChunk, ToolCall};
use crate::node::{Node, NodeConfig, NodeContext};
use crate::state::{Reducer, State, StateSpec};
use crate::tool::Tool;
use async_trait::async_trait;
use serde_json::{json, Value};
use std::collections::VecDeque;
use std::sync::Mutex;
struct ScriptedModel {
script: Mutex<VecDeque<ChatMessage>>,
seen_tool_schemas: Mutex<Vec<usize>>,
}
impl ScriptedModel {
fn new(script: Vec<ChatMessage>) -> Self {
Self {
script: Mutex::new(script.into()),
seen_tool_schemas: Mutex::new(Vec::new()),
}
}
}
#[async_trait]
impl ChatModel for ScriptedModel {
async fn chat(&self, _messages: &[ChatMessage], tools: &[Value]) -> Result<ChatResponse> {
self.seen_tool_schemas.lock().unwrap().push(tools.len());
let message = self
.script
.lock()
.unwrap()
.pop_front()
.ok_or_else(|| RustyError::Llm("script exhausted".into()))?;
Ok(ChatResponse {
message,
model: None,
usage: None,
})
}
}
struct StreamingModel;
#[async_trait]
impl ChatModel for StreamingModel {
async fn chat(&self, _messages: &[ChatMessage], _tools: &[Value]) -> Result<ChatResponse> {
Ok(ChatResponse {
message: ChatMessage::assistant("streamed"),
model: None,
usage: None,
})
}
async fn chat_stream(
&self,
messages: &[ChatMessage],
tools: &[Value],
on_token: &mut (dyn FnMut(TokenChunk) + Send),
) -> Result<ChatResponse> {
for delta in ["str", "eamed"] {
on_token(TokenChunk {
delta: delta.to_owned(),
finish: false,
raw: None,
});
}
self.chat(messages, tools).await
}
}
#[tokio::test]
async fn streaming_variant_forwards_token_events() {
let (tx, mut rx) = mpsc::channel::<GraphEvent>(8);
let model: Arc<dyn ChatModel> = Arc::new(StreamingModel);
let graph = create_react_agent_streaming(model, registry(), tx).unwrap();
let state = State::from_value(json!({
MESSAGES_CHANNEL: [serde_json::to_value(ChatMessage::user("hi")).unwrap()]
}))
.unwrap();
let ctx = NodeContext::new(state, NodeConfig::default());
let out = graph.node(AGENT_NODE).unwrap().run(ctx).await.unwrap();
let appended = out.updates.get(MESSAGES_CHANNEL).unwrap();
let msg: ChatMessage = serde_json::from_value(appended.clone()).unwrap();
assert_eq!(msg.content.as_deref(), Some("streamed"));
let mut deltas = String::new();
for _ in 0..2 {
match rx.try_recv().expect("two token events") {
GraphEvent::Token { node, delta } => {
assert_eq!(node, AGENT_NODE);
deltas.push_str(&delta);
}
other => panic!("expected Token event, got {other:?}"),
}
}
assert_eq!(deltas, "streamed");
}
#[tokio::test]
async fn non_streaming_variant_emits_no_token_events() {
let model: Arc<dyn ChatModel> =
Arc::new(ScriptedModel::new(vec![ChatMessage::assistant("done")]));
let graph = create_react_agent(model, registry()).unwrap();
assert!(graph.has_node(AGENT_NODE));
}
struct Echo;
#[async_trait]
impl Tool for Echo {
fn name(&self) -> &str {
"echo"
}
fn description(&self) -> &str {
"Echoes its input."
}
fn parameters_schema(&self) -> Value {
json!({"type": "object", "properties": {"text": {"type": "string"}}})
}
async fn call(&self, args: Value) -> Result<Value> {
Ok(json!(args.get("text").cloned().unwrap_or(Value::Null)))
}
}
fn registry() -> ToolRegistry {
let mut r = ToolRegistry::new();
r.register(Echo);
r
}
#[test]
fn graph_topology_is_the_react_loop() {
let model: Arc<dyn ChatModel> = Arc::new(ScriptedModel::new(vec![]));
let graph = create_react_agent(model, registry()).unwrap();
assert_eq!(graph.node_count(), 2);
assert_eq!(graph.entry_point(), AGENT_NODE);
assert!(graph.has_node(AGENT_NODE));
assert!(graph.has_node(TOOLS_NODE));
let agent_edges = graph.outgoing_edges(AGENT_NODE);
assert_eq!(agent_edges.len(), 1);
assert!(matches!(agent_edges[0], Edge::Conditional { .. }));
let tools_edges = graph.outgoing_edges(TOOLS_NODE);
assert_eq!(tools_edges.len(), 1);
assert!(matches!(
tools_edges[0],
Edge::Direct { from, to } if from == TOOLS_NODE && to == AGENT_NODE
));
}
#[tokio::test]
async fn agent_node_appends_assistant_message_and_sees_schemas() {
let model = Arc::new(ScriptedModel::new(vec![ChatMessage::assistant("done")]));
let graph = create_react_agent(model.clone(), registry()).unwrap();
let state = State::from_value(json!({
MESSAGES_CHANNEL: [serde_json::to_value(ChatMessage::user("hi")).unwrap()]
}))
.unwrap();
let ctx = NodeContext::new(state, NodeConfig::default());
let out = graph.node(AGENT_NODE).unwrap().run(ctx).await.unwrap();
let appended = out.updates.get(MESSAGES_CHANNEL).unwrap();
let msg: ChatMessage = serde_json::from_value(appended.clone()).unwrap();
assert_eq!(msg.content.as_deref(), Some("done"));
assert_eq!(model.seen_tool_schemas.lock().unwrap().as_slice(), &[1]);
}
#[tokio::test]
async fn tools_node_executes_pending_calls_in_order() {
let model: Arc<dyn ChatModel> = Arc::new(ScriptedModel::new(vec![]));
let graph = create_react_agent(model, registry()).unwrap();
let calls = vec![
ToolCall::new("c1", "echo", json!({"text": "a"})),
ToolCall::new("c2", "echo", json!({"text": "b"})),
];
let state = State::from_value(json!({
MESSAGES_CHANNEL: [
serde_json::to_value(ChatMessage::assistant_tool_calls(calls)).unwrap()
]
}))
.unwrap();
let ctx = NodeContext::new(state, NodeConfig::default());
let out = graph.node(TOOLS_NODE).unwrap().run(ctx).await.unwrap();
let appended = out.updates.get(MESSAGES_CHANNEL).unwrap();
let msgs: Vec<ChatMessage> = serde_json::from_value(appended.clone()).unwrap();
assert_eq!(msgs.len(), 2);
assert_eq!(msgs[0].tool_call_id.as_deref(), Some("c1"));
assert_eq!(msgs[0].content.as_deref(), Some("a"));
assert_eq!(msgs[1].tool_call_id.as_deref(), Some("c2"));
assert_eq!(msgs[1].content.as_deref(), Some("b"));
}
#[tokio::test]
async fn router_follows_tool_calls_else_ends() {
let model: Arc<dyn ChatModel> = Arc::new(ScriptedModel::new(vec![]));
let graph = create_react_agent(model, registry()).unwrap();
let edges = graph.outgoing_edges(AGENT_NODE);
let router = match edges[0] {
Edge::Conditional { router, .. } => router,
_ => panic!("expected conditional edge"),
};
let with_calls = State::from_value(json!({
MESSAGES_CHANNEL: [serde_json::to_value(ChatMessage::assistant_tool_calls(vec![
ToolCall::new("c1", "echo", json!({"text": "x"})),
]))
.unwrap()]
}))
.unwrap();
assert_eq!(
router(with_calls).await.unwrap(),
Route::Node(TOOLS_NODE.to_owned())
);
let final_answer = State::from_value(json!({
MESSAGES_CHANNEL: [serde_json::to_value(ChatMessage::assistant("42")).unwrap()]
}))
.unwrap();
assert_eq!(router(final_answer).await.unwrap(), Route::End);
}
#[tokio::test]
async fn manual_super_steps_reproduce_the_react_loop() {
let model: Arc<dyn ChatModel> = Arc::new(ScriptedModel::new(vec![
ChatMessage::assistant_tool_calls(vec![ToolCall::new(
"c1",
"echo",
json!({"text": "hello"}),
)]),
ChatMessage::assistant("echoed: hello"),
]));
let graph = create_react_agent(model, registry()).unwrap();
let spec = StateSpec::new().channel(MESSAGES_CHANNEL, Reducer::AddMessages);
let mut state = State::from_value(json!({
MESSAGES_CHANNEL: [serde_json::to_value(ChatMessage::user("say hello")).unwrap()]
}))
.unwrap();
let out = graph
.node(AGENT_NODE)
.unwrap()
.run(NodeContext::new(state.clone(), NodeConfig::default()))
.await
.unwrap();
spec.apply_single(&mut state, AGENT_NODE, out.updates)
.unwrap();
let edges = graph.outgoing_edges(AGENT_NODE);
let route = match edges[0] {
Edge::Conditional { router, .. } => router(state.clone()).await.unwrap(),
_ => unreachable!(),
};
assert_eq!(route, Route::Node(TOOLS_NODE.to_owned()));
let out = graph
.node(TOOLS_NODE)
.unwrap()
.run(NodeContext::new(state.clone(), NodeConfig::default()))
.await
.unwrap();
spec.apply_single(&mut state, TOOLS_NODE, out.updates)
.unwrap();
let out = graph
.node(AGENT_NODE)
.unwrap()
.run(NodeContext::new(state.clone(), NodeConfig::default()))
.await
.unwrap();
spec.apply_single(&mut state, AGENT_NODE, out.updates)
.unwrap();
let route = match edges[0] {
Edge::Conditional { router, .. } => router(state.clone()).await.unwrap(),
_ => unreachable!(),
};
assert_eq!(route, Route::End);
let msgs: Vec<ChatMessage> = state.get_as(MESSAGES_CHANNEL).unwrap().unwrap();
assert_eq!(msgs.len(), 4);
assert_eq!(msgs[3].content.as_deref(), Some("echoed: hello"));
}
use crate::journal::{Clock, Journal};
use crate::replay::ReplaySource;
fn recording_journal() -> Journal {
Journal::new("run-react-test", "thread-react-test", Clock::System)
}
#[test]
fn recording_and_replaying_variants_share_the_react_topology() {
let model: Arc<dyn ChatModel> = Arc::new(ScriptedModel::new(vec![]));
let journal = recording_journal();
let source = ReplaySource::new(&journal.snapshot());
let recording =
create_react_agent_with_recording(model.clone(), registry(), journal.clone()).unwrap();
let replaying =
create_react_agent_replaying(model.clone(), registry(), source, journal).unwrap();
for graph in [recording, replaying] {
assert_eq!(graph.node_count(), 2);
assert_eq!(graph.entry_point(), AGENT_NODE);
let agent_edges = graph.outgoing_edges(AGENT_NODE);
assert_eq!(agent_edges.len(), 1);
assert!(matches!(agent_edges[0], Edge::Conditional { .. }));
let tools_edges = graph.outgoing_edges(TOOLS_NODE);
assert_eq!(tools_edges.len(), 1);
assert!(matches!(
tools_edges[0],
Edge::Direct { from, to } if from == TOOLS_NODE && to == AGENT_NODE
));
}
}
#[tokio::test]
async fn recording_nodes_error_without_the_executor_parent_event() {
let model: Arc<dyn ChatModel> =
Arc::new(ScriptedModel::new(vec![ChatMessage::assistant("done")]));
let graph =
create_react_agent_with_recording(model, registry(), recording_journal()).unwrap();
let state = State::from_value(json!({
MESSAGES_CHANNEL: [serde_json::to_value(ChatMessage::user("hi")).unwrap()]
}))
.unwrap();
let err = graph
.node(AGENT_NODE)
.unwrap()
.run(NodeContext::new(state, NodeConfig::default()))
.await
.unwrap_err();
let message = err.to_string();
assert!(matches!(err, RustyError::Node(_)), "got: {message}");
assert!(message.contains(PARENT_EVENT_KEY), "got: {message}");
let state = State::from_value(json!({
MESSAGES_CHANNEL: [serde_json::to_value(ChatMessage::assistant_tool_calls(vec![
ToolCall::new("c1", "echo", json!({"text": "x"})),
]))
.unwrap()]
}))
.unwrap();
let err = graph
.node(TOOLS_NODE)
.unwrap()
.run(NodeContext::new(state, NodeConfig::default()))
.await
.unwrap_err();
assert!(err.to_string().contains(PARENT_EVENT_KEY), "got: {err}");
}
struct SchemaRecorder {
seen: Mutex<Vec<String>>,
}
#[async_trait]
impl ChatModel for SchemaRecorder {
async fn chat(&self, _messages: &[ChatMessage], tools: &[Value]) -> Result<ChatResponse> {
*self.seen.lock().unwrap() = tools
.iter()
.map(|schema| {
schema
.pointer("/function/name")
.and_then(Value::as_str)
.unwrap_or("")
.to_owned()
})
.collect();
Ok(ChatResponse {
message: ChatMessage::assistant("done"),
model: None,
usage: None,
})
}
}
struct Zeta;
#[async_trait]
impl Tool for Zeta {
fn name(&self) -> &str {
"zeta"
}
fn description(&self) -> &str {
"Alphabetically after echo."
}
fn parameters_schema(&self) -> Value {
json!({"type": "object"})
}
async fn call(&self, _args: Value) -> Result<Value> {
Ok(Value::Null)
}
}
#[tokio::test]
async fn tool_schemas_reach_the_model_in_canonical_name_order() {
let model = Arc::new(SchemaRecorder {
seen: Mutex::new(Vec::new()),
});
let mut forward = ToolRegistry::new();
forward.register(Echo);
forward.register(Zeta);
let mut reverse = ToolRegistry::new();
reverse.register(Zeta);
reverse.register(Echo);
for registry in [forward, reverse] {
let graph = create_react_agent(model.clone(), registry).unwrap();
let state = State::from_value(json!({
MESSAGES_CHANNEL: [serde_json::to_value(ChatMessage::user("hi")).unwrap()]
}))
.unwrap();
graph
.node(AGENT_NODE)
.unwrap()
.run(NodeContext::new(state, NodeConfig::default()))
.await
.unwrap();
assert_eq!(model.seen.lock().unwrap().as_slice(), ["echo", "zeta"]);
}
}
}