agent-protocol

Rust API Client SDK for Agent Protocol

Overview

This is an auto-generated Rust client library for the Agent Protocol. Agent Protocol is a framework-agnostic specification for serving LLM agents in production. It provides standardized APIs for running agents with support for multi-turn interactions, persistent state management, and long-term memory.

Features

• Type-safe API client: Auto-generated from OpenAPI specification
• Async/await support: Built on reqwest with async/await
• Flexible TLS backends: Choose between rustls-tls (default) or native-tls
• Comprehensive API coverage: Full support for all Agent Protocol endpoints including:
  • Agents: Agent discovery, introspection, and schema retrieval
  • Threads: Create and manage persistent conversation threads with state
  • Runs: Execute agents (stateless and stateful, with streaming support)
  • Background Runs: Fire-and-forget or poll for completion
  • Store: Key-value storage for long-term memory with namespace support

Installation

Add this to your Cargo.toml:

[dependencies]
agent-protocol = { version = "0.1.0", features = ["rustls-tls"] }

Or with native TLS:

[dependencies]
agent-protocol = { version = "0.1.0", features = ["native-tls"] }

Version Compatibility

The following table shows the version correspondence between the client and Agent Protocol:

Please ensure you use a compatible client version for your Agent Protocol implementation to avoid compatibility issues.

Usage

Basic Example

use agent_protocol::apis::configuration::Configuration;
use agent_protocol::apis::agents_api;
use agent_protocol::apis::threads_api;
use agent_protocol::models::{ThreadCreate, RunCreate};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create configuration
    let config = Configuration {
        base_path: "http://localhost:8000".to_string(),
        ..Default::default()
    };

    // Get agent information
    let agent = agents_api::get_agent(&config, "my-agent-id").await?;
    println!("Agent: {}", agent.name);

    // Create a thread
    let thread_create = ThreadCreate::new();
    let thread = threads_api::create_thread(&config, thread_create).await?;
    println!("Thread ID: {}", thread.thread_id);

    Ok(())
}

Working with Runs

use agent_protocol::apis::runs_api;
use agent_protocol::models::RunCreate;

// Create a stateless run and wait for output
let run_create = RunCreate::new();
let result = runs_api::create_run_wait(&config, Some(run_create)).await?;
println!("Run result: {:?}", result);

API Categories

Agents

• Search and discover available agents
• Get agent information and capabilities
• Retrieve JSON schemas for agent input/output/state

Threads

• Create and manage persistent conversation threads
• Update thread state and metadata
• Browse thread history (checkpoints)
• Copy or delete threads

Runs (Stateless)

• POST /runs/wait - Create ephemeral run and wait for output
• POST /runs/stream - Create ephemeral run and stream output

Runs (Background)

• Create background runs on existing threads
• Cancel, delete, or wait for background runs
• Stream output from running background runs

Store

• Put/get/delete items with namespace and key
• Search items by namespace and filter
• List available namespaces

Features

• default: Enables rustls-tls feature
• rustls-tls: Use rustls for TLS (default, recommended)
• native-tls: Use native TLS implementation

Development

This SDK is generated from the OpenAPI specification using OpenAPI Generator.

To regenerate the SDK:

# Initialize and update the spec submodule
git submodule update --init --recursive

# Generate the SDK
./scripts/generate_api_sdk.sh

This script:

1. Generates the SDK from spec/openapi.json
2. Copies the generated code to src/generated/
3. Formats the code with cargo fmt

Testing

Run the test suite:

cargo test

Run linter checks:

cargo clippy

Requirements

• Rust 1.85 or later
• OpenAPI Generator CLI (for regeneration)

Resources

• Agent Protocol Documentation
• Agent Protocol OpenAPI Spec
• Agent Protocol GitHub

License

See LICENSE file for details.

Contributing

Contributions are welcome! Please ensure that:

• Code is formatted with cargo fmt
• All tests pass with cargo test
• Clippy checks pass with cargo clippy