Crate serdes_ai

Expand description

§SerdesAI - Type-Safe AI Agent Framework for Rust

SerdesAI is a comprehensive Rust library for building AI agents that interact with large language models (LLMs). It is a complete port of pydantic-ai to Rust, providing type-safe, ergonomic APIs for creating intelligent agents.

§Quick Start

use serdes_ai::prelude::*;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let agent = Agent::builder()
        .model("openai:gpt-4o")
        .system_prompt("You are a helpful assistant.")
        .build()?;

    let result = agent.run("What is the capital of France?", ()).await?;
    println!("{}", result.output());
    Ok(())
}

§Key Features

Type-safe agents with generic dependencies and output types
Multiple LLM providers (OpenAI, Anthropic, Google, Groq, Mistral, Ollama, Bedrock)
Tool/function calling with automatic JSON schema generation
Streaming responses with real-time text updates
Structured outputs with JSON Schema validation
MCP protocol support for Model Context Protocol servers
Embeddings for semantic search and RAG applications
Graph-based workflows for complex multi-step tasks
Evaluation framework for testing and benchmarking agents
Retry strategies with exponential backoff
OpenTelemetry integration for observability

§Feature Flags

Feature	Description	Default
`openai`	OpenAI GPT models	✅
`anthropic`	Anthropic Claude models	✅
`gemini`	Google Gemini models	❌
`groq`	Groq fast inference	❌
`mistral`	Mistral AI models	❌
`ollama`	Local Ollama models	❌
`bedrock`	AWS Bedrock	❌
`mcp`	MCP protocol support	❌
`embeddings`	Embedding models	❌
`graph`	Graph execution engine	❌
`evals`	Evaluation framework	❌
`macros`	Proc macros	✅
`otel`	OpenTelemetry	❌
`full`	All features	❌

§Architecture

SerdesAI is organized as a workspace of focused crates:

serdes_ai_core - Core types, messages, and errors
serdes_ai_agent - Agent implementation and builder
serdes_ai_models - Model trait and implementations
serdes_ai_tools - Tool system and schema generation
serdes_ai_toolsets - Toolset abstractions
serdes_ai_output - Output schema validation
serdes_ai_streaming - Streaming support
serdes_ai_retries - Retry strategies
serdes_ai_mcp - MCP protocol (optional)
serdes_ai_embeddings - Embeddings (optional)
serdes_ai_graph - Graph execution (optional)
serdes_ai_evals - Evaluation framework (optional)
serdes_ai_macros - Procedural macros

§Examples

§Simple Chat

use serdes_ai::prelude::*;

let agent = Agent::builder()
    .model("openai:gpt-4o")
    .system_prompt("You are helpful.")
    .build()?;

let result = agent.run("Hello!", ()).await?;

§With Tools

use serdes_ai::prelude::*;

#[tool(description = "Get weather for a city")]
async fn get_weather(ctx: &RunContext<()>, city: String) -> ToolResult<String> {
    Ok(format!("Weather in {}: 22°C, sunny", city))
}

let agent = Agent::builder()
    .model("openai:gpt-4o")
    .tool(get_weather)
    .build()?;

§Structured Output

use serdes_ai::prelude::*;
use serde::Deserialize;

#[derive(Deserialize, OutputSchema)]
struct Person {
    name: String,
    age: u32,
}

let agent = Agent::builder()
    .model("openai:gpt-4o")
    .output_type::<Person>()
    .build()?;

let result: Person = agent.run("Extract: John is 30 years old", ()).await?.into_output();

§Streaming

use serdes_ai::prelude::*;
use futures::StreamExt;

let mut stream = agent.run_stream("Tell me a story", ()).await?;

while let Some(event) = stream.next().await {
    if let AgentStreamEvent::Text { delta } = event? {
        print!("{}", delta);
    }
}

Re-exports§

pub use direct::model_request;
pub use direct::model_request_stream;
pub use direct::model_request_stream_sync;
pub use direct::model_request_sync;
pub use direct::DirectError;
pub use direct::ModelSpec;
pub use direct::StreamedResponseSync;
pub use serdes_ai_core as core;
pub use serdes_ai_agent as agent;
pub use serdes_ai_models as models;
pub use serdes_ai_providers as providers;
pub use serdes_ai_tools as tools;
pub use serdes_ai_toolsets as toolsets;
pub use serdes_ai_output as output;
pub use serdes_ai_streaming as streaming;
pub use serdes_ai_retries as retries;
pub use serdes_ai_mcp as mcp;mcp
pub use serdes_ai_embeddings as embeddings;embeddings
pub use serdes_ai_graph as graph;graph
pub use serdes_ai_evals as evals;evals

Modules§

direct: Direct model request functions for imperative API access.
prelude: Convenient prelude for common imports.

Structs§

Agent: The main agent type.
AgentBuilder: Builder for creating agents.
AgentRun: Active agent run that can be iterated.
AgentRunResult: Result of an agent run.
AgentStream: Streaming agent execution.
AnthropicModelanthropic: Anthropic Claude model.
ApprovalRequiredToolset: Requires approval for tool calls.
BedrockModelbedrock: AWS Bedrock model client.
BinaryContent: Binary content container for file data.
BuiltinToolCallPart: A builtin tool call from a model (web search, code execution, etc.).
BuiltinToolReturnPart: Return from a builtin tool with structured content.
Caseevals: A single evaluation test case.
CodeExecutionResult: Result from code execution.
CombinedToolset: Combines multiple toolsets into one.
ContainsScorerevals: Evaluator that checks if output contains a substring.
ConversationId: Type-safe wrapper for a conversation ID.
Datasetevals: A collection of test cases.
DynamicToolset: Toolset that can have tools added/removed at runtime.
Edgegraph: An edge between two nodes with an optional condition.
Endgraph: End marker with result value.
EvalCaseevals: Legacy eval case for backward compatibility.
EvalRunnerevals: Evaluation runner.
EvalSuiteevals: A collection of evaluation test cases.
EvaluationReportevals: Full evaluation report.
ExactMatchScorerevals: Evaluator that checks for exact string match.
ExponentialBackoff: Exponential backoff with optional jitter.
ExtendedModelConfig: Extended configuration options for model building.
ExternalToolset: Toolset for externally-executed tools.
FilePart: A file response from a model.
FileSearchResult: A single file search result.
FileSearchResults: File search results from a builtin file search tool.
FilteredToolset: Filters tools from a toolset based on a predicate.
FixedDelay: Fixed delay between retries.
FunctionToolset: A toolset backed by function-based tools.
GeminiModelgemini: Google AI / Vertex AI model.
Graphgraph: A graph for multi-agent workflows.
GraphExecutorgraph: Graph executor with optional persistence and instrumentation.
GraphRunContextgraph: Context passed to nodes during execution.
GraphRunResultgraph: Result of a graph run.
GroqModelgroq: Groq model client.
LinearBackoff: Linear backoff.
McpClientmcp: MCP client for connecting to servers.
McpToolsetmcp: Toolset that wraps an MCP server’s tools.
MistralModelmistral: Mistral AI model client.
ModelConfig: Configuration for creating a model from a string spec.
ModelRequest: A complete model request containing multiple parts.
ModelResponse: A complete model response containing multiple parts.
ModelSettings: Settings for model generation.
ObjectJsonSchema: JSON Schema for an object type (tool parameters).
OllamaModelollama: Ollama model client.
OpenAIChatModelopenai: OpenAI Chat Completions model.
PartDeltaEvent: Event containing a delta update for a part.
PartEndEvent: Event indicating a part has ended.
PartStartEvent: Event indicating a new part has started.
PrefixedToolset: Adds a prefix to all tool names.
PreparedToolset: Prepares/modifies tool definitions at runtime.
RenamedToolset: Renames specific tools in a toolset.
RequestUsage: Token usage for a single request.
ResponseStream: Stream that filters to complete responses.
RetryConfig: Configuration for retry behavior.
RunContext: Context for an agent run.
RunId: Type-safe wrapper for a run ID.
RunOptions: Options for a run.
RunUsage: Accumulated usage for an entire run.
SchemaBuilder: Schema builder for manual schema construction.
StructuredOutputSchema: Schema for structured output using serde.
SystemPromptPart: System prompt part.
TextOutputSchema: Schema for plain text output.
TextPart: Text content part.
ThinkingPart: Thinking/reasoning content part.
ToolCallId: Type-safe wrapper for a tool call ID.
ToolCallPart: Tool call part.
ToolDefinition: Complete tool definition sent to the model.
ToolRegistry: Registry of tools that can be called by an agent.
ToolReturnPart: Tool return part.
ToolsetInfo: Information about a toolset for serialization.
ToolsetTool: A tool that belongs to a toolset.
UsageLimits: Usage limits for a run.
WebSearchResult: A single web search result.
WebSearchResults: Web search results from a builtin search tool.
WrapperToolset: Wrapper that allows custom pre/post processing.
XmlFormatOptions: Options for XML formatting.

Enums§

AgentStreamEvent: Events emitted during streaming.
BuiltinToolReturnContent: Content returned from builtin tools.
EndStrategy: Strategy for handling tool calls when output is ready.
EvaluationResultevals: Result of an evaluation.
FinishReason: Reason why the model stopped generating.
GraphErrorgraph: Errors that can occur during graph execution.
ModelRequestPart: Individual parts of a model request.
ModelResponsePart: Individual parts of a model response.
ModelResponsePartDelta: Delta content for different part types.
ModelResponseStreamEvent: Stream event for model responses.
NodeResultgraph: Result of a node execution.
ResponseDelta: Delta types for applying to partial response.
SerdesAiError: The main error type for serdes-ai operations.
StepResult: Result of a single step.
UserContent: User message content.
XmlFormatError: Error type for XML formatting operations.

Traits§

AbstractToolset: Abstract toolset trait - collection of tools with shared management.
BaseNodegraph: Base trait for all graph nodes.
EmbeddingModelembeddings: Core trait for embedding models.
Evaluatorevals: Core evaluator trait.
Model: Core model trait.
OutputSchema: Trait for output schemas that can validate model responses.
RetryStrategy: Trait for retry strategies.
Tool: Core trait for all tools.

Functions§

build_model_extended: Build a model with extended configuration options.
build_model_with_config: Build a model with custom configuration.
format_as_xml: Format a serializable value as XML.
format_as_xml_with_options: Format with full options control.
version: Returns the current version of serdes-ai.
version_tuple: Returns version information as a tuple (major, minor, patch).

Type Aliases§

BoxedToolset: Boxed toolset for dynamic dispatch.
EmbeddingResultembeddings: Result type for embedding operations.
GraphResultgraph: Result type for graph operations.
ToolResult: Result of a tool execution.
ValidationResult: Result type for output validation.

Attribute Macros§

agent_macromacros: Attribute macro for agent definitions. Attribute macro for defining agents.
toolmacros: Attribute macro for tool functions. Attribute macro for creating tools from functions.

Derive Macros§

OutputSchemamacros: Derive macro for output schemas. Derive macro for implementing the OutputSchema trait.
Toolmacros: Derive macro for tools. Derive macro for implementing the Tool trait.

Crate serdes_ai

Crate serdes_ai Copy item path

§SerdesAI - Type-Safe AI Agent Framework for Rust

§Quick Start

§Key Features

§Feature Flags

§Architecture

§Examples

§Simple Chat

§With Tools

§Structured Output

§Streaming

Re-exports§

Modules§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Attribute Macros§

Derive Macros§

Crate serdes_ai