prelude

Prelude module for common imports

Structs

`Agent`

Core Agent implementation

The Agent struct is the main runtime entry point for registering skills, wiring handlers, and dispatching runtime messages. Protocol surfaces such as A2A and AG-UI compose around this type via adapter modules.

Methods

`new_runtime`

fn new_runtime(name: &str) -> SdkResult<Self>

Create a new runtime-first agent.

`new`

fn new(name: &str) -> SdkResult<Self>

Create a new agent (alias of new_runtime)

`new_with_config`

fn new_with_config(config: AgentConfig) -> SdkResult<Self>

Create agent with custom configuration

`with_service`

fn with_service<T>(self, service: T) -> Self

`get_service`

fn get_service<T>(&self) -> Option<Arc<T>>

`has_service`

fn has_service<T>(&self) -> bool

`add_skill`

fn add_skill(&mut self, skill_id: &str) -> SkillEntryBuilder<'_>

`skill`

fn skill<F, Fut>(&mut self, name: &str, handler: F) -> SkillEntryBuilder<'_>
where
    F: Fn + Send + Sync + ?,
    Fut: Future + Send + ?

`register_notification`

fn register_notification<F, Fut>(&mut self, name: &str, handler: F) -> SdkResult<()>
where
    F: Fn + Send + Sync + ?,
    Fut: Future + Send + ?

`config`

fn config(&self) -> &AgentConfig

`list_skills`

fn list_skills(&self) -> Vec<String>

`list_notifications`

fn list_notifications(&self) -> Vec<String>

`skill_registry`

fn skill_registry(&self) -> &SkillRegistry

Get read-only reference to the skill registry.

`set_message_handler`

fn set_message_handler<F, Fut>(&mut self, handler: F)
where
    F: Fn + Send + Sync + ?,
    Fut: Future + Send + ?

`dispatch_message`

async fn dispatch_message(&self, msg_ctx: MessageContext, task_ctx: Option<TaskContext>) -> SdkResult<RuntimeResponse>

Unified entrypoint to route a built MessageContext through the active handler.

`AgentConfig`

Agent Configuration

Configuration for agent behavior, capabilities, and response patterns.

Response Modes

The agent supports different response patterns:

Stateful (default): Creates Task responses for conversation continuity
Stateless: Prefers lightweight Message responses for API-style interactions

Examples

use agent_sdk::agent::AgentConfig;

// Default stateful agent
let config = AgentConfig::default();

// Stateless agent for API-style interactions
let config = AgentConfig::new("api-agent", "API Agent")
    .stateless();

Fields

Field	Type	Description
`name`	`String`
`description`	`String`
`version`	`String`
`storage_prefix`	`Option<String>`	Optional storage namespace prefix used by shared task-storage backends.
`max_message_size`	`u64`
`streaming`	`bool`
`batch_processing`	`bool`
`concurrent_tasks`	`Option<u32>`
`stateless_methods`	`bool`	Prefer stateless responses (Message) over stateful (Task) for methods
`base_url`	`Option<String>`	Base URL for constructing absolute `AgentInterface` URLs in the agent card.
`history_policy`	`Option<HistoryPolicyConfig>`	Optional history policy used for durable continuation preparation.

Methods

`new`

fn new<impl Into<String>, impl Into<String>>(name: impl Into, description: impl Into) -> Self

Create a new agent configuration

Arguments

name - Agent name
description - Agent description

Examples

use agent_sdk::agent::AgentConfig;

let config = AgentConfig::new("my-agent", "My Agent Description");

`stateless`

fn stateless(self) -> Self

Configure agent for stateless method responses

When enabled, methods will prefer lightweight Message responses over Task responses for API-style interactions.

Examples

use agent_sdk::agent::AgentConfig;

let config = AgentConfig::new("api-agent", "API Agent")
    .stateless();

`stateful`

fn stateful(self) -> Self

Configure agent for stateful method responses (default)

Methods will create Task responses for conversation continuity.

Examples

use agent_sdk::agent::AgentConfig;

let config = AgentConfig::default()
    .stateful(); // Explicit stateful (default behavior)

`with_base_url`

fn with_base_url<impl Into<String>>(self, url: impl Into) -> Self

Set the base URL for absolute AgentInterface URLs in the agent card.

The A2A v1.0 spec requires absolute URLs in AgentInterface.url. When set, the SDK produces {base_url}/jsonrpc instead of /jsonrpc.

`with_history_policy`

fn with_history_policy(self, policy: HistoryPolicyConfig) -> Self

Attach a history policy for pre/post-turn continuation preparation.

`ServiceContainer`

Minimal service container for dependency injection

Allows agents to accept optional services through clean dependency injection without hardcoding specific service fields in the Agent struct.

Examples

use agent_sdk::services::ServiceContainer;
use std::sync::Arc;

#[derive(Clone)]
struct MyService {
    name: String,
}

let mut container = ServiceContainer::new();
container.register(MyService { name: "test".to_string() });

let service: Option<Arc<MyService>> = container.get();
assert!(service.is_some());

Methods

`new`

fn new() -> Self

Create a new empty service container

`register`

fn register<T>(&mut self, service: T)

Services are stored by their type and can be retrieved later using the same type signature.

Arguments

service - The service instance to register

Examples

# use agent_sdk::services::ServiceContainer;
# #[derive(Clone)]
# struct DatabaseService;
let mut container = ServiceContainer::new();
container.register(DatabaseService);

`get`

fn get<T>(&self) -> Option<Arc<T>>

Get a service from the container

Returns an Arc-wrapped service if found, or None if the service type is not registered.

Returns

Some(Arc<T>) - The service if found
None - If no service of type T is registered

Examples

# use agent_sdk::services::ServiceContainer;
# use std::sync::Arc;
# #[derive(Clone)]
# struct DatabaseService { pub name: String }
# let mut container = ServiceContainer::new();
# container.register(DatabaseService { name: "test".to_string() });
let service: Option<Arc<DatabaseService>> = container.get();
if let Some(db) = service {
    println!("Database: {}", db.name);
}

`has`

fn has<T>(&self) -> bool

Check if a service type is registered

Returns

true - If a service of type T is registered
false - If no service of type T is found

Examples

# use agent_sdk::services::ServiceContainer;
# #[derive(Clone)]
# struct CacheService;
let container = ServiceContainer::new();
assert!(!container.has::<CacheService>());

`len`

fn len(&self) -> usize

Get the number of registered services

`is_empty`

fn is_empty(&self) -> bool

Check if the container is empty

`clear`

fn clear(&mut self)

Remove all services from the container

`SkillCall`

Skill Call Information

Extracted from DataPart when a structured skill call is detected.

Fields

Field	Type	Description
`skill_id`	`String`
`parameters`	`serde_json::Value`

`SkillDefinition`

Protocol-independent skill definition.

This is the single source of truth for skill metadata inside the SDK. Protocol adapters (A2A AgentSkill, MCP, etc.) convert from this type.

Fields

Field	Type	Description
`id`	`String`
`name`	`String`
`description`	`String`
`input_modes`	`Vec<String>`
`output_modes`	`Vec<String>`
`schema`	`Option<serde_json::Value>`
`examples`	`Option<Vec<String>>`
`tags`	`Option<Vec<String>>`
`instructions`	`Option<String>`	Behavioral guidance injected into LLM context when this skill is activated.
`expose`	`bool`	Whether the skill is visible on the discovery card (default: true).
`llm_callable`	`bool`	Whether the LLM can invoke this skill’s handler via `read_skill` tool (default: false).

`SkillEntryBuilder`

Fluent builder for skill registration.

Created via [SkillRegistry::add_skill] / [crate::Agent::add_skill], or [SkillRegistry::skill] / [crate::Agent::skill] when providing a handler. Finalize with .register().

Methods

`handler`

fn handler<F, Fut>(self, handler: F) -> Self
where
    F: Fn + Send + Sync + ?,
    Fut: Future + Send + ?

Attach an async handler. Omit for metadata-only skills (discovery card + LLM awareness).

`display_name`

fn display_name<S>(self, name: S) -> Self

`description`

fn description<S>(self, desc: S) -> Self

`schema`

fn schema(self, schema: Value) -> Self

`examples`

fn examples(self, examples: Vec<String>) -> Self

`example`

fn example<S>(self, example: S) -> Self

`tags`

fn tags(self, tags: &[&str]) -> Self

`tag`

fn tag<S>(self, tag: S) -> Self

`input_modes`

fn input_modes(self, modes: &[&str]) -> Self

`output_modes`

fn output_modes(self, modes: &[&str]) -> Self

`json_only`

fn json_only(self) -> Self

`text_only`

fn text_only(self) -> Self

`instructions`

fn instructions<S>(self, text: S) -> Self

Set behavioral instructions (injected into LLM context when skill is activated).

`expose`

fn expose(self, visible: bool) -> Self

Control whether the skill is visible on the discovery card (default: true).

`llm_callable`

fn llm_callable(self, callable: bool) -> Self

Control whether the LLM can invoke this skill via read_skill tool (default: false).

`register`

fn register(self) -> SdkResult<()>

Finalize registration.

Enums

`MessageType`

Message Type Classification

Classifies incoming messages based on their Part composition to determine the appropriate handling strategy (tool-like vs conversational vs hybrid).

Variants

Variant	Description
`Data`	Pure DataPart - structured tool calls
`Text`	Pure TextPart - conversational interactions
`Mixed`	Multiple part types - hybrid interactions

`SdkError`

SDK-specific error types

Wraps underlying A2A protocol errors and adds SDK-specific error cases for better error handling and user experience.

Variants

Variant	Description
`A2AProtocol(error::A2AError)`	A2A protocol error
`Configuration { ... }`	Configuration error
`AgentInitialization { ... }`	Agent initialization error
`SkillRegistration { ... }`	Skill registration error
`MethodExecution { ... }`	Method execution error
`Serialization(serde_json::Error)`	Serialization error
`Io(Error)`	IO error
`Generic(anyhow::Error)`	Generic error
`FeatureNotEnabled { ... }`	Feature not enabled
`InvalidInput { ... }`	Invalid input

Methods

`configuration`

fn configuration<impl Into<String>>(details: impl Into) -> Self

Create a configuration error

`agent_initialization`

fn agent_initialization<impl Into<String>>(reason: impl Into) -> Self

Create an agent initialization error

`skill_registration`

fn skill_registration<impl Into<String>, impl Into<String>>(skill: impl Into, reason: impl Into) -> Self

Create a skill registration error

`method_execution`

fn method_execution<impl Into<String>, impl Into<String>>(method: impl Into, details: impl Into) -> Self

Create a method execution error

`feature_not_enabled`

fn feature_not_enabled<impl Into<String>>(feature: impl Into) -> Self

Create a feature not enabled error

`invalid_input`

fn invalid_input<impl Into<String>>(details: impl Into) -> Self

Create an invalid input error

`is_recoverable`

fn is_recoverable(&self) -> bool

Check if error is recoverable

`category`

fn category(&self) -> &''static str

Get error category for monitoring/logging