AGENTS.md

This file provides guidance to agents or humans when working with code in this repository.

Architecture Overview

This is an Anthropic Claude API client library written in Rust, designed with a modular architecture that separates concerns between the client and API endpoint managers. The library implements a chain-style API pattern similar to modern cloud SDKs.

Core Structure

anthropic-rust/src/
├── lib.rs                 # Library entry point with re-exports
├── client.rs              # Main Client with builder pattern, HTTP handling
├── message.rs             # Message API manager (create, stream, count_tokens)
├── batch.rs               # Message Batches API manager
├── model.rs               # Models API manager
└── types/                 # Type definitions
    ├── mod.rs             # Module exports
    ├── messages.rs        # Messages API types (requests, responses, content blocks)
    ├── batches.rs         # Batch API types
    └── models.rs          # Models API types

Key Design Patterns:

• Manager-style API: client.messages().create(request).await
• Builder pattern: Client::builder().api_key(key).build()?
• Request builders: CreateMessageRequest::builder().model("...").build()?

Client

The Client struct is the primary entry point:

• Manages HTTP client, API key, base URL, and API version
• Provides manager accessor methods: messages(), batches(), models()
• Supports custom configuration via ClientBuilder
• Handles request/response serialization and error handling
• Supports beta feature flags via beta() method

Message (API Manager)

Message provides access to the Messages API:

• create() - send a message and get a complete response
• create_stream() - SSE streaming for incremental responses
• count_tokens() - pre-flight token estimation

Batch (API Manager)

Batch provides access to the Message Batches API:

• create() - create a new batch of message requests
• get() - retrieve batch status
• list() - list all batches
• cancel() - cancel a processing batch
• delete() - delete a completed batch

Model (API Manager)

Model provides access to the Models API:

• list() - list available models
• get() - get details for a specific model

Type System

• All types are exported from types::*
• Request/response types mirror the Anthropic API structure
• Content blocks support: text, image, document, tool_use, tool_result, thinking, redacted_thinking
• Stream types use async-stream for Server-Sent Events parsing
• Full support for tool use, extended thinking, and caching

Development Commands

Building and Testing

# Build the library
cargo build

# Check compilation (faster)
cargo check

# Run tests
cargo test

Running Examples

# Basic message example
cargo run --example messages

# Streaming example
cargo run --example streaming

# Batches example
cargo run --example batches

# Models example
cargo run --example models

Workspace Structure

This is a Cargo workspace with:

• Main library: anthropic-rust/
• Examples: examples/*/ (each is its own crate)

Development Rules

Core Reference Materials:

• Anthropic Claude API documentation (primary reference)
• Official Anthropic API specifications

Development Workflow:

1. Compilation: Always compile after code changes with cargo check or cargo build
2. Testing: Write unit tests for new functionality, run with cargo test
3. Examples: Create examples for each API capability in examples/[name]/
4. Documentation: Keep docs concise and current

Environment Variables:

Examples expect:

• ANTHROPIC_API_KEY - API key for Anthropic Claude API
• ANTHROPIC_BASE_URL - Optional base URL override

Load via .env file using dotenvy::dotenv().

Adding New API Endpoints

1. Add type definitions in types/[name].rs if needed
2. Add API manager struct in [name].rs with methods
3. Add manager accessor to Client in client.rs
4. Update types/mod.rs and lib.rs to export new types
5. Create example in examples/[name]/
6. Update documentation

API Coverage Status

Currently implemented:

• Messages API (/v1/messages)
• Streaming Messages API (SSE)
• Token Counting API (/v1/messages/count_tokens)
• Message Batches API (/v1/messages/batches)
• Models API (/v1/models)

Features supported:

• Text generation
• Vision (images)
• Documents (PDF, text)
• Tool use (function calling)
• Extended thinking
• Prompt caching
• Server-side tools (web search)