use super::hook::{HookStack, RequestPatch};
use super::run::{AgentRun, OutputMode};
use super::runner::AgentRunner;
use super::typed::TypedRun;
use crate::bus::{BusDriver, Dispatcher, ModelHandle};
use crate::{
completion::{CompletionRequest, Document, Message, PromptError, ToolDefinition},
run::response::PromptResponse,
tool::{
ToolCatalog,
server::{ToolServerError, ToolServerHandle},
},
};
use rig_core::completion::ModelRef;
use rig_core::effect::{HandlerDescriptor, HandlerKey, Key, family};
use rig_core::error::ProviderError;
use rig_core::id::ConversationId;
use super::drive::AgentBus;
use rig_core::{message::ToolChoice, wasm_compat::WasmCompatSend};
use std::{collections::BTreeSet, sync::Arc};
use super::UNKNOWN_AGENT_NAME;
pub(crate) struct PreparedCompletionRequest {
pub(crate) request: CompletionRequest,
pub(crate) telemetry_messages: Vec<Message>,
pub(crate) model: ModelHandle,
pub(crate) tool_snapshot: Arc<ToolCatalog>,
pub(crate) advertised_tools: Vec<ToolDefinition>,
pub(crate) executable_tool_names: BTreeSet<String>,
pub(crate) allowed_tool_names: BTreeSet<String>,
pub(crate) output_tool_name: Option<String>,
pub(crate) max_tokens: Option<u64>,
}
pub(crate) async fn build_prepared_completion_request(
runner: &crate::agent::AgentRunner,
ctx: &crate::agent::HookContext,
model: &ModelHandle,
prompt: Message,
chat_history: &[Message],
committed_output_tool: Option<&str>,
request_patch: Option<&RequestPatch>,
) -> Result<PreparedCompletionRequest, ProviderError> {
let record_telemetry_content = runner.config.record_telemetry_content;
let tool_server_handle = &runner.tool_server_handle;
let retrieval_query = prompt.rag_text().or_else(|| {
chat_history
.iter()
.rev()
.find_map(rig_core::completion::Message::rag_text)
});
let mut dynamic_tool_ids = Vec::new();
for (key, kind) in tool_server_handle.retrieval_effects(retrieval_query) {
let ids = crate::agent::engine::dispatch_effect(
&runner.config.hooks,
ctx,
runner.config.bus.dispatcher(),
&key,
kind,
)
.await
.and_then(|outcome| match outcome {
rig_core::effect::Outcome::Documents(rig_core::effect::RetrievedDocuments::Ids(
ids,
)) => Ok(ids.into_iter().map(|(_, id)| id).collect::<Vec<String>>()),
other => Err(crate::agent::engine::wrong_outcome("retrieved ids", &other)),
})
.map_err(|report| {
ProviderError::request(format!("Failed to get tool definitions: {report}"))
})?;
dynamic_tool_ids.extend(ids);
}
let mut tool_snapshot = tool_server_handle.snapshot_with_dynamic(&dynamic_tool_ids);
let mut spec = runner.config.run_spec();
spec.output_tool_description
.clone_from(&runner.output_tool_description);
spec.augment_output_preamble = runner.augment_output_preamble;
let capabilities = model.capabilities();
let committed_output_tool = if unforce_output_tool(runner, &capabilities, &mut spec) {
None
} else {
committed_output_tool
};
let prepared = crate::run::prepare::prepare_request(
&spec,
&capabilities,
chat_history,
tool_snapshot.take_definitions(),
committed_output_tool,
request_patch,
)?;
tool_snapshot.retain_names(&prepared.executable_tool_names);
let advertised_tools = prepared.tools.clone();
let executable_tool_names = prepared.executable_tool_names.clone();
let allowed_tool_names = prepared.allowed_tool_names.clone();
let output_tool_name = prepared.output_tool_name.clone();
let max_tokens = prepared.max_tokens;
let request = prepared.apply(CompletionRequest::new(prompt));
let telemetry_messages = if record_telemetry_content {
request.messages_for_telemetry()
} else {
Vec::new()
};
Ok(PreparedCompletionRequest {
request,
telemetry_messages,
model: model.clone(),
tool_snapshot: Arc::new(tool_snapshot),
advertised_tools,
executable_tool_names,
allowed_tool_names,
output_tool_name,
max_tokens,
})
}
fn unforce_output_tool(
runner: &crate::agent::AgentRunner,
capabilities: &rig_core::completion::ProviderCapabilities,
spec: &mut crate::run::spec::RunSpec,
) -> bool {
let Some(name) = runner.output_tool_name.as_deref() else {
return false;
};
let forced = matches!(
spec.tool_choice,
Some(ToolChoice::Required | ToolChoice::Specific { .. })
);
if !capabilities.rejects_forced_tool_choice || !forced || spec.output_schema.is_none() {
return false;
}
spec.tool_choice = None;
let native = capabilities.composes_native_output_with_tools;
let line = if native {
format!(
"The `{name}` tool is not available for this model. Reply with only the JSON \
object you would have passed to it."
)
} else {
format!("Call the `{name}` tool with your answer instead of replying in text.")
};
spec.preamble = Some(match spec.preamble.take() {
Some(preamble) => format!("{preamble}\n\n{line}"),
None => line,
});
if native {
spec.output_mode = OutputMode::Native;
}
native
}
#[derive(Clone)]
pub struct Agent {
pub(crate) config: AgentConfig,
pub(crate) tool_server_handle: ToolServerHandle,
}
#[derive(Clone)]
pub(crate) struct AgentConfig {
pub(crate) name: Option<String>,
pub(crate) description: Option<String>,
pub(crate) bus: AgentBus,
pub(crate) model_key: Key<family::Completion>,
pub(crate) preamble: Option<String>,
pub(crate) static_context: Vec<Document>,
pub(crate) additional_params: Option<serde_json::Value>,
pub(crate) record_telemetry_content: bool,
pub(crate) max_tokens: Option<u64>,
pub(crate) temperature: Option<f64>,
pub(crate) tool_choice: Option<ToolChoice>,
pub(crate) max_turns: usize,
pub(crate) hooks: HookStack,
pub(crate) output_schema: Option<schemars::Schema>,
pub(crate) output_mode: OutputMode,
pub(crate) memory_key: Option<Key<family::Memory>>,
pub(crate) route_keys: Vec<Key<family::Completion>>,
pub(crate) context_keys: Vec<Key<family::Retrieve>>,
pub(crate) conversation_id: Option<ConversationId>,
pub(crate) anonymous_model: Option<std::sync::Arc<super::drive::AnonymousModel>>,
}
impl AgentConfig {
pub(crate) fn new(bus: AgentBus, model_key: Key<family::Completion>) -> Self {
Self {
name: None,
description: None,
bus,
model_key,
preamble: None,
static_context: vec![],
additional_params: None,
record_telemetry_content: false,
max_tokens: None,
temperature: None,
tool_choice: None,
max_turns: 1,
hooks: HookStack::new(),
route_keys: Vec::new(),
context_keys: Vec::new(),
output_schema: None,
output_mode: OutputMode::default(),
memory_key: None,
conversation_id: None,
anonymous_model: None,
}
}
pub(crate) fn model_handle(&self) -> Result<ModelHandle, rig_core::error::ErrorReport> {
self.bus.dispatcher().bind(&self.model_key)
}
pub(crate) fn model_label(&self) -> ModelRef {
match self
.bus
.dispatcher()
.descriptor(self.model_key.raw())
.map(|descriptor| descriptor.family)
{
Some(rig_core::effect::FamilyDescriptor::Completion { model, .. }) => model,
Some(rig_core::effect::FamilyDescriptor::Tool { .. })
| Some(rig_core::effect::FamilyDescriptor::Embed { .. })
| Some(rig_core::effect::FamilyDescriptor::Memory {})
| Some(rig_core::effect::FamilyDescriptor::Retrieve {})
| Some(rig_core::effect::FamilyDescriptor::Rerank { .. })
| Some(rig_core::effect::FamilyDescriptor::Custom { .. })
| None => ModelRef::new(
self.bus
.model_label(self.model_key.raw())
.unwrap_or(self.model_key.as_str()),
),
}
}
pub(crate) fn model_by_ref(
&self,
label: &ModelRef,
) -> Result<ModelHandle, rig_core::error::ErrorReport> {
self.bus
.dispatcher()
.bind(&self.bus.model_key(label.as_str()))
}
pub(crate) fn memory_handle(
&self,
) -> Option<Result<crate::bus::MemoryHandle, rig_core::error::ErrorReport>> {
self.memory_key
.as_ref()
.map(|key| self.bus.dispatcher().bind(key))
}
}
impl AgentConfig {
pub(crate) fn run_spec(&self) -> crate::run::spec::RunSpec {
crate::run::spec::RunSpec {
preamble: self.preamble.clone(),
static_context: self.static_context.clone(),
additional_params: self.additional_params.clone(),
max_tokens: self.max_tokens,
temperature: self.temperature,
tool_choice: self.tool_choice.clone(),
max_turns: Some(self.max_turns),
max_invalid_tool_call_retries: 0,
output_schema: self
.output_schema
.as_ref()
.map(|schema| schema.as_value().clone()),
output_mode: self.output_mode.clone(),
output_tool_name: None,
output_tool_description: None,
augment_output_preamble: true,
unhandled_invalid_tool_call: crate::run::spec::UnhandledInvalidToolCall::Fail,
}
}
}
impl Agent {
pub fn run_spec(&self) -> crate::run::spec::RunSpec {
self.config.run_spec()
}
}
impl Agent {
pub fn tool_server_handle(&self) -> &crate::tool::server::ToolServerHandle {
&self.tool_server_handle
}
pub fn name(&self) -> Option<&str> {
self.config.name.as_deref()
}
pub fn description(&self) -> Option<&str> {
self.config.description.as_deref()
}
pub(crate) fn name_or_default(&self) -> &str {
self.name().unwrap_or(UNKNOWN_AGENT_NAME)
}
pub fn model_key(&self) -> &Key<family::Completion> {
&self.config.model_key
}
pub fn model_descriptor(&self) -> Option<HandlerDescriptor> {
self.config
.bus
.dispatcher()
.descriptor(self.config.model_key.raw())
}
pub fn model_label(&self) -> Option<ModelRef> {
self.model_descriptor()
.and_then(|descriptor| match descriptor.family {
rig_core::effect::FamilyDescriptor::Completion { model, .. } => Some(model),
rig_core::effect::FamilyDescriptor::Tool { .. }
| rig_core::effect::FamilyDescriptor::Embed { .. }
| rig_core::effect::FamilyDescriptor::Memory {}
| rig_core::effect::FamilyDescriptor::Retrieve {}
| rig_core::effect::FamilyDescriptor::Rerank { .. }
| rig_core::effect::FamilyDescriptor::Custom { .. } => None,
})
}
pub fn register_model(
&self,
label: impl Into<ModelRef>,
model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>,
) -> ModelRef {
let label = label.into();
self.config.bus.register_model(&label, model);
label
}
pub fn set_model_label(&mut self, label: impl Into<ModelRef>) {
self.config.model_key = self.config.bus.model_key(label.into().as_str());
self.config.anonymous_model = None;
}
pub fn set_model(
&mut self,
model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>,
) {
let anonymous = self.config.bus.register_anonymous_model(model);
self.config.model_key = anonymous.key().clone();
self.config.anonymous_model = Some(anonymous);
}
pub fn owner(&self) -> &str {
self.config.bus.owner()
}
pub fn with_model_label(mut self, label: impl Into<ModelRef>) -> Self {
self.set_model_label(label);
self
}
pub fn with_model(
mut self,
model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>,
) -> Self {
self.set_model(model);
self
}
pub fn required_row(&self) -> rig_core::effect::EffectRow {
use rig_core::effect::EffectFamily;
let mut row = rig_core::effect::EffectRow::new();
row.insert(
self.config.model_key.raw().clone(),
EffectFamily::Completion,
);
for route in &self.config.route_keys {
row.insert(route.raw().clone(), EffectFamily::Completion);
}
if let Some(memory) = &self.config.memory_key {
row.insert(memory.raw().clone(), EffectFamily::Memory);
}
for (_, tool) in self.tool_server_handle.toolset().iter() {
row.insert(tool.key().raw().clone(), EffectFamily::Tool);
}
for key in self.tool_server_handle.retrieval_keys() {
row.insert(key, EffectFamily::Retrieve);
}
for context in &self.config.context_keys {
row.insert(context.raw().clone(), EffectFamily::Retrieve);
}
row
}
pub fn program_names(&self) -> Vec<String> {
let mut names = self.config.hooks.names();
for descriptor in self.config.bus.dispatcher().descriptors() {
names.extend(descriptor.layers);
}
names
}
pub fn bus_config(&self) -> Option<rig_core::serve::ServingPolicy> {
self.config.bus.config()
}
pub fn handler_descriptor(&self, key: &HandlerKey) -> Option<HandlerDescriptor> {
self.config.bus.dispatcher().descriptor(key)
}
pub fn owns_bus(&self) -> bool {
self.config.bus.owns_driver()
}
pub fn into_parts(self) -> Result<AgentParts, Agent> {
let Agent {
mut config,
tool_server_handle,
} = self;
let detached = config.bus.detached();
let bus = std::mem::replace(&mut config.bus, detached);
let registrar = bus.registrar().clone();
match bus.try_into_parts() {
Ok((dispatcher, driver)) => Ok(AgentParts {
dispatcher,
registrar,
driver,
agent: Agent {
config,
tool_server_handle,
},
}),
Err(bus) => {
config.bus = bus;
Err(Agent {
config,
tool_server_handle,
})
}
}
}
pub async fn tool_definitions(
&self,
prompt: Option<String>,
) -> Result<Vec<ToolDefinition>, ToolServerError> {
self.tool_server_handle.tool_defs(prompt).await
}
}
impl Agent {
pub fn prompt(&self, prompt: impl Into<Message>) -> AgentRunner {
AgentRunner::from_agent(self, prompt)
}
pub fn resume(&self, run: AgentRun) -> AgentRunner {
AgentRunner::resuming(self, run)
}
#[tracing::instrument(skip(self, prompt, chat_history), fields(agent_name = self.name_or_default()))]
pub async fn chat(
&self,
prompt: impl Into<Message> + WasmCompatSend,
chat_history: &mut Vec<Message>,
) -> Result<PromptResponse, PromptError> {
let response = AgentRunner::from_agent(self, prompt)
.history(chat_history.clone())
.await?;
if let Some(messages) = &response.messages {
chat_history.extend(messages.iter().cloned());
}
Ok(response)
}
pub fn prompt_typed<T>(&self, prompt: impl Into<Message>) -> TypedRun<T>
where
T: JsonSchema + DeserializeOwned + WasmCompatSend,
{
TypedRun::native(self, prompt)
}
}
use schemars::JsonSchema;
use serde::de::DeserializeOwned;
#[cfg(test)]
mod request_identity_tests;
pub struct AgentParts {
pub dispatcher: Dispatcher,
pub registrar: crate::bus::Registrar,
pub driver: BusDriver,
pub agent: Agent,
}