use std::{
collections::{HashMap, HashSet},
sync::Arc,
};
use async_trait::async_trait;
use schemars::JsonSchema;
use serde::{de::DeserializeOwned, Serialize};
use serde_json::{json, Map, Value};
use url::form_urlencoded::byte_serialize;
use crate::{
CreateRequest, Error, EventStream, FunctionTool, Input, Marona, McpConnection, Result,
RoutingOptions, RunEvent, RuntimeResponse, ToolChoice, ToolContext, VoiceOptions,
};
#[async_trait]
pub trait LifecycleHooks: Send + Sync {
async fn on_start(&self, _context: &AgentContext, _input: &Input) -> Result<()> {
Ok(())
}
async fn on_event(&self, _context: &AgentContext, _event: &RunEvent) -> Result<()> {
Ok(())
}
async fn on_complete(&self, _context: &AgentContext, _result: &RunResult) -> Result<()> {
Ok(())
}
async fn on_error(&self, _context: &AgentContext, _error: &Error) -> Result<()> {
Ok(())
}
}
#[derive(Debug, Clone, Default)]
pub struct AgentContext {
pub user_id: Option<String>,
pub session_id: String,
pub agent_name: String,
pub metadata: Map<String, Value>,
}
#[derive(Clone)]
pub enum AgentTool {
Function(FunctionTool),
Delegation {
name: String,
description: String,
agent: Arc<Agent>,
},
}
impl std::fmt::Debug for AgentTool {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Function(value) => formatter.debug_tuple("Function").field(value).finish(),
Self::Delegation {
name,
description,
agent,
} => formatter
.debug_struct("Delegation")
.field("name", name)
.field("description", description)
.field("agent", &agent.name)
.finish(),
}
}
}
#[derive(Debug, Clone)]
pub struct Handoff {
pub name: String,
pub description: String,
pub agent: Arc<Agent>,
}
pub fn handoff(
agent: Arc<Agent>,
name: impl Into<String>,
description: impl Into<String>,
) -> Handoff {
Handoff {
agent,
name: name.into(),
description: description.into(),
}
}
#[derive(Clone)]
pub struct Agent {
pub(crate) marona: Marona,
pub name: String,
pub description: Option<String>,
pub model: String,
pub instructions: String,
pub hub_tools: Option<McpConnection>,
pub tools: Vec<AgentTool>,
pub handoffs: Vec<Handoff>,
pub peers: Vec<crate::A2APeer>,
pub tool_choice: ToolChoice,
pub voice: Option<VoiceOptions>,
pub modalities: Vec<String>,
pub output_modalities: Vec<String>,
pub routing: Option<RoutingOptions>,
pub metadata: Map<String, Value>,
pub max_turns: u32,
pub hooks: Option<Arc<dyn LifecycleHooks>>,
}
impl std::fmt::Debug for Agent {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter
.debug_struct("Agent")
.field("name", &self.name)
.field("model", &self.model)
.field("tools", &self.tools)
.field("handoffs", &self.handoffs)
.field("peers", &self.peers)
.finish_non_exhaustive()
}
}
impl Agent {
pub fn new(marona: &Marona, name: impl Into<String>) -> Self {
Self {
marona: marona.clone(),
name: name.into(),
description: None,
model: "marona/auto".into(),
instructions: String::new(),
hub_tools: None,
tools: vec![],
handoffs: vec![],
peers: vec![],
tool_choice: ToolChoice::Auto,
voice: None,
modalities: vec![],
output_modalities: vec![],
routing: None,
metadata: Map::new(),
max_turns: 20,
hooks: None,
}
}
pub fn description(mut self, value: impl Into<String>) -> Self {
self.description = Some(value.into());
self
}
pub fn model(mut self, value: impl Into<String>) -> Self {
self.model = value.into();
self
}
pub fn instructions(mut self, value: impl Into<String>) -> Self {
self.instructions = value.into();
self
}
pub fn hub_tools(mut self, value: McpConnection) -> Self {
self.hub_tools = Some(value);
self
}
pub fn tool(mut self, value: FunctionTool) -> Self {
self.tools.push(AgentTool::Function(value));
self
}
pub fn agent_tool(mut self, value: AgentTool) -> Self {
self.tools.push(value);
self
}
pub fn handoff(mut self, value: Handoff) -> Self {
self.handoffs.push(value);
self
}
pub fn peer(mut self, value: crate::A2APeer) -> Self {
self.peers.push(value);
self
}
pub fn tool_choice(mut self, value: ToolChoice) -> Self {
self.tool_choice = value;
self
}
pub fn routing(mut self, value: RoutingOptions) -> Self {
self.routing = Some(value);
self
}
pub fn voice(mut self, value: VoiceOptions) -> Self {
self.voice = Some(value);
self
}
pub fn modalities(mut self, values: impl IntoIterator<Item = impl Into<String>>) -> Self {
self.modalities = values.into_iter().map(Into::into).collect();
self
}
pub fn output_modalities(
mut self,
values: impl IntoIterator<Item = impl Into<String>>,
) -> Self {
self.output_modalities = values.into_iter().map(Into::into).collect();
self
}
pub fn metadata(mut self, value: Map<String, Value>) -> Self {
self.metadata = value;
self
}
pub fn hooks(mut self, value: Arc<dyn LifecycleHooks>) -> Self {
self.hooks = Some(value);
self
}
pub fn max_turns(mut self, value: u32) -> Self {
self.max_turns = value;
self
}
pub fn as_tool(
self: &Arc<Self>,
name: impl Into<String>,
description: impl Into<String>,
) -> AgentTool {
AgentTool::Delegation {
name: name.into(),
description: description.into(),
agent: self.clone(),
}
}
}
#[derive(Debug, Clone)]
pub struct RunResult {
pub output: Value,
pub last_agent: String,
pub active_agent: String,
pub agent_runs: Vec<crate::AgentRun>,
pub usage: Map<String, Value>,
pub routing: Map<String, Value>,
pub trace_id: Option<String>,
pub a2a_events: Vec<Value>,
pub response: RuntimeResponse,
}
pub struct Runner;
impl Runner {
pub async fn run(
agent: &Agent,
input: impl Into<Input>,
user_id: Option<&str>,
session_id: Option<&str>,
) -> Result<RunResult> {
validate_graph(agent)?;
let input = input.into();
let session_id = session_id.unwrap_or("default").to_owned();
let context = AgentContext {
user_id: user_id.map(str::to_owned),
session_id: session_id.clone(),
agent_name: agent.name.clone(),
metadata: agent.metadata.clone(),
};
if let Some(hooks) = &agent.hooks {
hooks.on_start(&context, &input).await?;
}
let conversation_id = scoped_conversation(user_id.unwrap_or("anonymous"), &session_id);
let mut request = request_for(agent, input, user_id, &conversation_id);
let functions = function_map(agent);
let response = loop {
match agent.marona.responses.create(request.clone()).await {
Ok(response) => {
let calls = response
.agent
.get("function_tool_calls")
.and_then(Value::as_array)
.cloned()
.unwrap_or_default();
if calls.is_empty() {
break response;
}
let mut results = Vec::new();
for call in calls {
let name = call.get("name").and_then(Value::as_str).unwrap_or("");
let (tool, owner) = functions.get(name).ok_or_else(|| {
Error::Tool(format!("function tool '{name}' is unavailable"))
})?;
let arguments = call.get("arguments").cloned().unwrap_or_else(|| json!({}));
let output = tool
.invoke(arguments.clone(), tool_context(owner, user_id, &session_id))
.await?;
results.push(json!({"call_id":call.get("call_id"),"name":name,"arguments":arguments,"output":output}));
}
request
.metadata
.insert("marona_function_tool_results".into(), json!(results));
}
Err(error) => {
if let Some(hooks) = &agent.hooks {
hooks.on_error(&context, &error).await?;
}
return Err(error);
}
}
};
let active = response
.agent
.get("active_agent")
.and_then(Value::as_str)
.unwrap_or(&agent.name)
.to_owned();
let last = response
.agent
.get("last_agent")
.and_then(Value::as_str)
.unwrap_or(&active)
.to_owned();
let runs = response
.agent
.get("runs")
.and_then(Value::as_array)
.into_iter()
.flatten()
.filter_map(|value| serde_json::from_value(value.clone()).ok())
.collect();
let result = RunResult {
output: response.output.clone(),
last_agent: last,
active_agent: active,
agent_runs: runs,
usage: response.usage.clone(),
routing: response.routing.clone(),
trace_id: response
.agent
.get("trace_id")
.and_then(Value::as_str)
.map(str::to_owned),
a2a_events: vec![],
response,
};
if let Some(hooks) = &agent.hooks {
hooks.on_complete(&context, &result).await?;
}
Ok(result)
}
pub async fn run_typed<I, O>(
agent: &Agent,
input: &I,
user_id: Option<&str>,
session_id: Option<&str>,
) -> Result<O>
where
I: Serialize + JsonSchema,
O: DeserializeOwned + JsonSchema,
{
let input_value =
serde_json::to_value(input).map_err(|e| Error::Validation(e.to_string()))?;
let result = Self::run(agent, Input::Message(json!({"role":"user","content":[{"type":"input_text","text":input_value.to_string()}]})), user_id, session_id).await?;
serde_json::from_value(result.output)
.map_err(|e| Error::Validation(format!("output validation failed: {e}")))
}
pub async fn stream(
agent: &Agent,
input: impl Into<Input>,
user_id: Option<&str>,
session_id: Option<&str>,
) -> Result<EventStream> {
validate_graph(agent)?;
let conversation = scoped_conversation(
user_id.unwrap_or("anonymous"),
session_id.unwrap_or("default"),
);
agent
.marona
.responses
.stream(request_for(agent, input.into(), user_id, &conversation))
.await
}
}
fn request_for(
agent: &Agent,
input: Input,
user_id: Option<&str>,
conversation_id: &str,
) -> CreateRequest {
let mut request = CreateRequest::new(agent.model.clone(), input);
request.tools = agent.hub_tools.clone();
request.user_id = user_id.map(str::to_owned);
request.conversation_id = Some(conversation_id.to_owned());
request.developer_instructions = Some(agent.instructions.clone());
request.routing = agent.routing.clone();
request.tool_choice = agent.tool_choice;
request.metadata.insert("marona_agent".into(), json!({"name":agent.name,"modalities":agent.modalities,"output_modalities":agent.output_modalities,"voice":agent.voice,"tool_choice":agent.tool_choice,"tools_enabled":agent.hub_tools.is_some() || !agent.tools.is_empty() || !agent.peers.is_empty()}));
request
.metadata
.insert("marona_multi_agent".into(), graph_value(agent));
let functions = function_map(agent)
.values()
.map(|(tool, _)| tool.definition())
.collect::<Vec<_>>();
if !functions.is_empty() {
request
.metadata
.insert("marona_function_tools".into(), json!(functions));
}
request
}
pub(crate) fn function_map(agent: &Agent) -> HashMap<String, (FunctionTool, Agent)> {
fn visit(
agent: &Agent,
values: &mut HashMap<String, (FunctionTool, Agent)>,
seen: &mut HashSet<String>,
) {
if !seen.insert(agent.name.clone()) {
return;
}
for item in &agent.tools {
match item {
AgentTool::Function(tool) => {
values.insert(tool.name.clone(), (tool.clone(), agent.clone()));
}
AgentTool::Delegation { agent, .. } => visit(agent, values, seen),
}
}
for peer in &agent.peers {
let tool = peer.function_tool();
values.insert(tool.name.clone(), (tool, agent.clone()));
}
for handoff in &agent.handoffs {
visit(&handoff.agent, values, seen);
}
}
let mut values = HashMap::new();
visit(agent, &mut values, &mut HashSet::new());
values
}
pub(crate) fn tool_context(agent: &Agent, user_id: Option<&str>, session_id: &str) -> ToolContext {
ToolContext {
user_id: user_id.map(str::to_owned),
session_id: session_id.to_owned(),
developer_id: None,
permissions: agent
.metadata
.get("permissions")
.and_then(Value::as_array)
.into_iter()
.flatten()
.filter_map(Value::as_str)
.map(str::to_owned)
.collect(),
approved_tools: agent
.metadata
.get("approved_tools")
.and_then(Value::as_array)
.into_iter()
.flatten()
.filter_map(Value::as_str)
.map(str::to_owned)
.collect(),
metadata: agent.metadata.clone(),
}
}
fn scoped_conversation(user: &str, session: &str) -> String {
["rust", user, session]
.into_iter()
.map(|value| byte_serialize(value.as_bytes()).collect::<String>())
.collect::<Vec<_>>()
.join(":")
}
pub(crate) fn graph_value(agent: &Agent) -> Value {
let (root, agents) = collect_agents(agent);
json!({"version":1,"root":root,"agents":agents,"limits":{"max_turns":agent.max_turns,"max_agent_calls":10,"max_handoffs":5,"max_depth":4,"timeout_ms":60000}})
}
#[cfg(feature = "realtime")]
pub(crate) fn realtime_tool_definitions(agent: &Agent) -> Vec<Value> {
let mut tools = Vec::new();
for value in &agent.tools {
match value {
AgentTool::Function(tool) => tools.push(provider_tool(
&tool.name,
&tool.description,
tool.input_schema.clone(),
)),
AgentTool::Delegation {
name, description, ..
} => tools.push(provider_tool(name, description, delegated_schema())),
}
}
for peer in &agent.peers {
let tool = peer.function_tool();
tools.push(provider_tool(
&tool.name,
&tool.description,
tool.input_schema,
));
}
for value in &agent.handoffs {
tools.push(provider_tool(
&value.name,
&value.description,
delegated_schema(),
));
}
tools
}
#[cfg(feature = "realtime")]
fn provider_tool(name: &str, description: &str, parameters: Value) -> Value {
json!({
"type": "function",
"name": name,
"description": description,
"parameters": parameters,
})
}
#[cfg(feature = "realtime")]
fn delegated_schema() -> Value {
json!({
"type": "object",
"properties": {
"input": {
"type": "string",
"description": "The bounded task or transfer context for the target agent."
}
},
"required": ["input"],
"additionalProperties": false,
})
}
fn collect_agents(root: &Agent) -> (String, Map<String, Value>) {
fn visit(
agent: &Agent,
values: &mut Map<String, Value>,
ids: &mut HashMap<String, String>,
) -> String {
if let Some(id) = ids.get(&agent.name) {
return id.clone();
}
let id = format!("agent_{}", ids.len());
ids.insert(agent.name.clone(), id.clone());
let mut delegations = Vec::new();
let mut functions = Vec::new();
for tool in &agent.tools {
match tool {
AgentTool::Function(value) => functions.push(value.definition()),
AgentTool::Delegation {
name,
description,
agent,
} => {
let target = visit(agent, values, ids);
delegations.push(json!({"name":name,"description":description,"target":target,"history":"none","timeout_ms":60000}));
}
}
}
for peer in &agent.peers {
functions.push(peer.function_tool().definition());
}
let handoffs = agent.handoffs.iter().map(|value| {
let target = visit(&value.agent, values, ids);
json!({"name":value.name,"description":value.description,"target":target,"history":"full"})
}).collect::<Vec<_>>();
values.insert(id.clone(), json!({"name":agent.name,"description":agent.description,"model":agent.model,"instructions":agent.instructions,
"routing":agent.routing,"tool_choice":agent.tool_choice,"max_turns":agent.max_turns,"modalities":agent.modalities,
"output_modalities":agent.output_modalities,"voice":agent.voice,"hub_tools":agent.hub_tools.is_some(),
"function_tools":functions,"delegations":delegations,"handoffs":handoffs,"metadata":agent.metadata}));
id
}
let mut values = Map::new();
let root_id = visit(root, &mut values, &mut HashMap::new());
(root_id, values)
}
fn validate_graph(root: &Agent) -> Result<()> {
fn visit(
agent: &Agent,
visiting: &mut HashSet<String>,
complete: &mut HashSet<String>,
) -> Result<()> {
if complete.contains(&agent.name) {
return Ok(());
}
if !visiting.insert(agent.name.clone()) {
return Err(Error::Validation(format!(
"agent graph contains a cycle at '{}'",
agent.name
)));
}
for tool in &agent.tools {
if let AgentTool::Delegation { agent, .. } = tool {
visit(agent, visiting, complete)?;
}
}
for handoff in &agent.handoffs {
visit(&handoff.agent, visiting, complete)?;
}
visiting.remove(&agent.name);
complete.insert(agent.name.clone());
Ok(())
}
visit(root, &mut HashSet::new(), &mut HashSet::new())
}