use super::hook::{HookStack, RequestPatch};
use super::runner::AgentRunner;
use super::typed::TypedRun;
use crate::handlers::{Handlers, ModelHandle};
use crate::run::spec::RunSpec;
use crate::run::{AgentRun, OutputMode};
use crate::{
completion::{CompletionRequest, Message, PromptError, ToolDefinition},
run::response::PromptResponse,
tool::{ToolCatalog, server::ToolServerHandle},
};
use rig_core::completion::ModelRef;
use rig_core::effect::{HandlerDescriptor, HandlerKey, Key, family};
use rig_core::error::ProviderError;
use rig_core::{message::ToolChoice, wasm_compat::WasmCompatSend};
use std::sync::{
Arc,
atomic::{AtomicU64, AtomicUsize, Ordering},
};
use super::UNKNOWN_AGENT_NAME;
pub(crate) struct PreparedCompletionRequest {
pub(crate) model: ModelHandle,
pub(crate) tool_snapshot: Arc<ToolCatalog>,
pub(crate) policy: crate::run::TurnPolicy,
pub(crate) max_tokens: Option<u64>,
}
pub(crate) fn retrieval_query(prompt: &Message, history: &[Arc<Message>]) -> Option<String> {
prompt
.rag_text()
.or_else(|| history.iter().rev().find_map(|message| message.rag_text()))
}
pub(crate) async fn build_prepared_completion_request(
runner: &crate::agent::AgentRunner,
ctx: &crate::agent::HookContext,
model: &ModelHandle,
prompt: Arc<Message>,
chat_history: &[Arc<Message>],
committed_output_tool: Option<&str>,
request_patch: Option<&RequestPatch>,
) -> Result<(CompletionRequest, PreparedCompletionRequest), ProviderError> {
let tool_server_handle = &runner.tool_server_handle;
let retrieval_query = retrieval_query(&prompt, chat_history);
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, ctx, &key, kind)
.await
.and_then(crate::tool::server::retrieved_ids)
.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 capabilities = model.capabilities();
let unforced = unforce_output_tool(&runner.config.spec, &capabilities);
let (spec, committed_output_tool) = match &unforced {
Some((spec, true)) => (spec, None),
Some((spec, false)) => (spec, committed_output_tool),
None => (&*runner.config.spec, committed_output_tool),
};
let crate::run::PreparedRequest {
request, policy, ..
} = crate::run::prepare::prepare_request(
spec,
&capabilities,
prompt,
chat_history,
tool_snapshot.take_definitions(),
committed_output_tool,
request_patch,
)?;
tool_snapshot.retain_names(policy.executable());
let prepared = PreparedCompletionRequest {
model: model.clone(),
tool_snapshot: Arc::new(tool_snapshot),
policy,
max_tokens: request.max_tokens,
};
Ok((request, prepared))
}
fn unforce_output_tool(
spec: &RunSpec,
capabilities: &rig_core::completion::ProviderCapabilities,
) -> Option<(RunSpec, bool)> {
let name = spec.output_tool_name.as_deref()?;
let forced = matches!(
spec.tool_choice,
Some(ToolChoice::Required | ToolChoice::Specific { .. })
);
if !capabilities.rejects_forced_tool_choice || !forced || spec.output_schema.is_none() {
return None;
}
let mut spec = spec.clone();
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;
}
Some((spec, 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) handlers: Handlers,
pub(crate) owner: Arc<str>,
pub(crate) anonymous_models: Arc<AtomicUsize>,
pub(crate) model_key: Key<family::Completion>,
pub(crate) spec: Arc<RunSpec>,
pub(crate) record_telemetry_content: bool,
pub(crate) hooks: HookStack,
pub(crate) route_keys: Vec<Key<family::Completion>>,
pub(crate) context_keys: Vec<Key<family::Retrieve>>,
pub(crate) anonymous_model: Option<Arc<AnonymousModel>>,
pub(crate) memory: Option<super::memory::Memory>,
pub(crate) conversation: Option<String>,
}
static NEXT_AGENT: AtomicU64 = AtomicU64::new(0);
pub(crate) fn default_owner() -> String {
format!("agent#{}", NEXT_AGENT.fetch_add(1, Ordering::Relaxed))
}
pub(crate) struct AnonymousModel {
key: Key<family::Completion>,
handlers: Handlers,
}
impl Drop for AnonymousModel {
fn drop(&mut self) {
self.handlers.deregister(self.key.raw());
}
}
#[track_caller]
pub(crate) fn register_generated(registered: Result<(), rig_core::error::ErrorReport>) {
if let Err(report) = registered {
let caller = std::panic::Location::caller();
tracing::error!(%report, %caller, "a generated key changed family; the registration was refused");
}
}
impl AgentConfig {
pub(crate) fn new(handlers: Handlers, model_key: Key<family::Completion>) -> Self {
Self {
name: None,
description: None,
handlers,
owner: Arc::from(""),
anonymous_models: Arc::default(),
model_key,
spec: Arc::new(RunSpec {
max_turns: Some(1),
..RunSpec::new()
}),
record_telemetry_content: false,
hooks: HookStack::new(),
route_keys: Vec::new(),
context_keys: Vec::new(),
anonymous_model: None,
memory: None,
conversation: None,
}
}
pub(crate) fn spec_mut(&mut self) -> &mut RunSpec {
Arc::make_mut(&mut self.spec)
}
pub(crate) fn max_turns(&self) -> usize {
self.spec.effective_max_turns()
}
pub(crate) fn model_handle(&self) -> Result<ModelHandle, rig_core::error::ErrorReport> {
self.handlers.bind(&self.model_key)
}
pub(crate) fn model_label(&self) -> ModelRef {
match self.handlers.descriptor(self.model_key.raw()) {
Some(HandlerDescriptor {
family: rig_core::effect::FamilyDescriptor::Completion { model, .. },
..
}) => model,
_ => {
let key = self.model_key.as_str();
let label = key
.strip_prefix(&*self.owner)
.and_then(|rest| rest.strip_prefix("/model:"));
ModelRef::new(label.unwrap_or(key))
}
}
}
pub(crate) fn model_by_ref(
&self,
label: &ModelRef,
) -> Result<ModelHandle, rig_core::error::ErrorReport> {
self.handlers.bind(&self.model_key_for(label.as_str()))
}
pub(crate) fn key<F: rig_core::effect::Family>(&self, suffix: &str) -> Key<F> {
Key::new_unchecked(self.raw_key(suffix))
}
pub(crate) fn raw_key(&self, suffix: &str) -> HandlerKey {
HandlerKey::from(format!("{}/{suffix}", self.owner))
}
pub(crate) fn model_key_for(&self, label: &str) -> Key<family::Completion> {
self.key(rig_core::effect::model_key(label).as_str())
}
pub(crate) fn register_model(
&self,
label: &ModelRef,
model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>,
) -> Key<family::Completion> {
let key = self.model_key_for(label.as_str());
let adapter = rig_core::serve::adapters::ModelAdapter::new(label.clone(), model.into());
register_generated(self.handlers.register(key.raw().clone(), adapter));
key
}
pub(crate) fn select_anonymous_model(
&mut self,
model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>,
) {
let n = self.anonymous_models.fetch_add(1, Ordering::SeqCst);
let key = self.register_model(&ModelRef::new(format!("anonymous#{n}")), model);
self.model_key = key.clone();
self.anonymous_model = Some(Arc::new(AnonymousModel {
key,
handlers: self.handlers.clone(),
}));
}
pub(crate) fn select_model_label(&mut self, label: ModelRef) {
self.model_key = self.model_key_for(label.as_str());
self.anonymous_model = None;
}
}
impl Agent {
pub fn run_spec(&self) -> RunSpec {
RunSpec::clone(&self.config.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 register_model(
&self,
label: impl Into<ModelRef>,
model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>,
) -> ModelRef {
let label = label.into();
self.config.register_model(&label, model);
label
}
pub fn set_model_label(&mut self, label: impl Into<ModelRef>) {
self.config.select_model_label(label.into());
}
pub fn set_model(
&mut self,
model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>,
) {
self.config.select_anonymous_model(model);
}
pub fn owner(&self) -> &str {
&self.config.owner
}
pub fn handlers(&self) -> &Handlers {
&self.config.handlers
}
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);
}
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.handlers.descriptors() {
names.extend(descriptor.layers);
}
names
}
pub fn handler_descriptor(&self, key: &HandlerKey) -> Option<HandlerDescriptor> {
self.config.handlers.descriptor(key)
}
pub async fn tool_definitions(
&self,
prompt: Option<String>,
) -> Result<Vec<Arc<ToolDefinition>>, ProviderError> {
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.iter().cloned())
.await?;
chat_history.extend(response.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;