Struct PluginBuilder 

pub struct PluginBuilder { /* private fields */ }

Available on crate feature plugin only.

Builder for creating plugins with a fluent API.

PluginBuilder provides a chainable interface for constructing Plugin instances without manually filling out a PluginConfig struct. Each method configures a single lifecycle callback, and build produces the final Plugin.

End-to-End Example

use adk_plugin::PluginBuilder;
use std::sync::Arc;

let plugin = PluginBuilder::new("audit-trail")
    .before_agent(Box::new(|ctx| {
        Box::pin(async move {
            tracing::info!("agent starting");
            Ok(())
        })
    }))
    .after_agent(Box::new(|ctx| {
        Box::pin(async move {
            tracing::info!("agent finished");
            Ok(())
        })
    }))
    .before_tool(Box::new(|ctx| {
        Box::pin(async move {
            if let Some(name) = ctx.tool_name() {
                tracing::info!(tool = name, "tool invoked");
            }
            Ok(())
        })
    }))
    .after_tool(Box::new(|ctx| {
        Box::pin(async move {
            tracing::info!("tool completed");
            Ok(())
        })
    }))
    .before_model(Box::new(|ctx, request| {
        Box::pin(async move {
            tracing::debug!(model = ?request.model, "sending request to model");
            Ok(request)
        })
    }))
    .after_model(Box::new(|ctx, response| {
        Box::pin(async move {
            tracing::debug!("model responded");
            Ok(None)
        })
    }))
    .close_fn(|| Box::pin(async { tracing::info!("plugin closed") }))
    .build();

assert_eq!(plugin.name(), "audit-trail");

Implementations

impl PluginBuilder

pub fn new(name: impl Into<String>) -> PluginBuilder

Create a new plugin builder with the given name.

The name uniquely identifies this plugin within a PluginManager.

let builder = PluginBuilder::new("my-plugin");

pub fn on_user_message( self, callback: Box<dyn Fn(Arc<dyn InvocationContext>, Content) -> Pin<Box<dyn Future<Output = Result<Option<Content>, AdkError>> + Send>> + Sync + Send>, ) -> PluginBuilder

Set the callback invoked when a user message is received.

The callback can inspect or modify the incoming Content. Return Ok(Some(content)) to replace the message, or Ok(None) to keep the original.

builder.on_user_message(Box::new(|ctx, content| {
    Box::pin(async move {
        tracing::info!(role = %content.role, "user message received");
        Ok(None) // pass through unchanged
    })
}))

pub fn on_event( self, callback: Box<dyn Fn(Arc<dyn InvocationContext>, Event) -> Pin<Box<dyn Future<Output = Result<Option<Event>, AdkError>> + Send>> + Sync + Send>, ) -> PluginBuilder

Set the callback invoked for each event generated by the agent.

The callback can inspect or modify Event objects before they are yielded to the caller. Return Ok(Some(event)) to replace the event, or Ok(None) to keep the original.

builder.on_event(Box::new(|ctx, event| {
    Box::pin(async move {
        tracing::debug!(id = %event.id, "event emitted");
        Ok(None)
    })
}))

pub fn before_run( self, callback: Box<dyn Fn(Arc<dyn InvocationContext>) -> Pin<Box<dyn Future<Output = Result<Option<Content>, AdkError>> + Send>> + Sync + Send>, ) -> PluginBuilder

Set the callback invoked before the agent run starts.

Use this for setup, validation, or early exit. Return Ok(Some(content)) to skip the run entirely and return that content, or Ok(None) to proceed normally.

builder.before_run(Box::new(|ctx| {
    Box::pin(async move {
        tracing::info!("run starting");
        Ok(None) // continue with the run
    })
}))

pub fn after_run( self, callback: Box<dyn Fn(Arc<dyn InvocationContext>) -> Pin<Box<dyn Future<Output = ()> + Send>> + Sync + Send>, ) -> PluginBuilder

Set the callback invoked after the agent run completes.

Use this for cleanup, logging, or metrics collection. This callback is for side effects only and does not emit events.

builder.after_run(Box::new(|ctx| {
    Box::pin(async move {
        tracing::info!("run completed");
    })
}))

pub fn before_agent( self, callback: Box<dyn Fn(Arc<dyn CallbackContext>) -> Pin<Box<dyn Future<Output = Result<Option<Content>, AdkError>> + Send>> + Sync + Send>, ) -> PluginBuilder

Set the callback invoked before agent execution.

Runs each time an agent is about to execute. Useful for tracing, permission checks, or injecting state.

builder.before_agent(Box::new(|ctx| {
    Box::pin(async move {
        tracing::info!("agent starting");
        Ok(())
    })
}))

pub fn after_agent( self, callback: Box<dyn Fn(Arc<dyn CallbackContext>) -> Pin<Box<dyn Future<Output = Result<Option<Content>, AdkError>> + Send>> + Sync + Send>, ) -> PluginBuilder

Set the callback invoked after agent execution.

Runs each time an agent finishes. Useful for logging duration, collecting metrics, or post-processing results.

builder.after_agent(Box::new(|ctx| {
    Box::pin(async move {
        tracing::info!("agent finished");
        Ok(())
    })
}))

pub fn before_model( self, callback: Box<dyn Fn(Arc<dyn CallbackContext>, LlmRequest) -> Pin<Box<dyn Future<Output = Result<BeforeModelResult, AdkError>> + Send>> + Sync + Send>, ) -> PluginBuilder

Set the callback invoked before an LLM call.

The callback receives the LlmRequest and can modify it or skip the call entirely by returning a pre-built response.

builder.before_model(Box::new(|ctx, request| {
    Box::pin(async move {
        tracing::debug!(model = ?request.model, "calling model");
        Ok(request) // pass through unchanged
    })
}))

pub fn after_model( self, callback: Box<dyn Fn(Arc<dyn CallbackContext>, LlmResponse) -> Pin<Box<dyn Future<Output = Result<Option<LlmResponse>, AdkError>> + Send>> + Sync + Send>, ) -> PluginBuilder

Set the callback invoked after an LLM call.

The callback receives the LlmResponse and can modify or replace it. Return Ok(Some(response)) to replace, or Ok(None) to keep the original.

builder.after_model(Box::new(|ctx, response| {
    Box::pin(async move {
        tracing::debug!("model responded");
        Ok(None) // keep original response
    })
}))

pub fn on_model_error( self, callback: Box<dyn Fn(Arc<dyn CallbackContext>, LlmRequest, String) -> Pin<Box<dyn Future<Output = Result<Option<LlmResponse>, AdkError>> + Send>> + Sync + Send>, ) -> PluginBuilder

Set the callback invoked when an LLM call returns an error.

The callback receives the original LlmRequest and the error message. Return Ok(Some(response)) to provide a fallback response, or Ok(None) to propagate the error.

builder.on_model_error(Box::new(|ctx, request, error| {
    Box::pin(async move {
        tracing::warn!(error = %error, "model error, no fallback");
        Ok(None) // propagate the error
    })
}))

pub fn before_tool( self, callback: Box<dyn Fn(Arc<dyn CallbackContext>) -> Pin<Box<dyn Future<Output = Result<Option<Content>, AdkError>> + Send>> + Sync + Send>, ) -> PluginBuilder

Set the callback invoked before tool execution.

Runs each time a tool is about to execute. The CallbackContext provides tool_name() and tool_input() for tool-specific logic.

builder.before_tool(Box::new(|ctx| {
    Box::pin(async move {
        if let Some(name) = ctx.tool_name() {
            tracing::info!(tool = name, "tool starting");
        }
        Ok(())
    })
}))

pub fn after_tool( self, callback: Box<dyn Fn(Arc<dyn CallbackContext>) -> Pin<Box<dyn Future<Output = Result<Option<Content>, AdkError>> + Send>> + Sync + Send>, ) -> PluginBuilder

Set the callback invoked after tool execution.

Runs each time a tool finishes. Useful for logging results, collecting metrics, or auditing tool usage.

builder.after_tool(Box::new(|ctx| {
    Box::pin(async move {
        tracing::info!("tool completed");
        Ok(())
    })
}))

pub fn on_tool_error( self, callback: Box<dyn Fn(Arc<dyn CallbackContext>, Arc<dyn Tool>, Value, String) -> Pin<Box<dyn Future<Output = Result<Option<Value>, AdkError>> + Send>> + Sync + Send>, ) -> PluginBuilder

Set the callback invoked when a tool returns an error.

The callback receives the tool name, the error, and the CallbackContext. Use this to log failures or provide fallback values.

builder.on_tool_error(Box::new(|ctx, tool_name, error| {
    Box::pin(async move {
        tracing::warn!(tool = %tool_name, error = %error, "tool failed");
        Ok(None) // propagate the error
    })
}))

pub fn close_fn( self, f: impl Fn() -> Pin<Box<dyn Future<Output = ()> + Send>> + Send + Sync + 'static, ) -> PluginBuilder

Set the async cleanup function called when the plugin is closed.

Use this to release resources, flush buffers, or perform final cleanup.

builder.close_fn(|| Box::pin(async {
    tracing::info!("plugin shutting down");
}))

pub fn build(self) -> Plugin

Consume the builder and produce a Plugin.

Only callbacks that were explicitly set will be active; all others remain None.