Claude Code API

The Interactive Session feature allows the Claude Code API to reuse the same Claude process for multiple requests within the same conversation. This improves performance by avoiding the overhead of creating new processes for each request.

Key Benefits:

• Faster Response Times: Subsequent requests in a conversation typically take 1-3 seconds compared to 5-15 seconds for new processes.
• Context Preservation: The Claude process maintains context between requests, enabling multi-turn conversations.
• Resource Efficiency: Reuses existing processes instead of spawning new ones.

Lifecycle:

1. A request is sent with a conversation_id.
2. If a session exists for that ID, the message is sent to the existing process.
3. If no session exists, a new process is started and associated with that ID.
4. Sessions are automatically cleaned up after 30 minutes of inactivity.

# First request - creates a new session
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{ "model": "claude-3-5-sonnet-20241022", "conversation_id": "my-session-123", "messages": [{ "role": "user", "content": "Hello!" }] }'

# Second request - reuses the same session
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{ "model": "claude-3-5-sonnet-20241022", "conversation_id": "my-session-123", "messages": [{ "role": "user", "content": "What did I just say?" }] }'

The Claude Code API supports the modern OpenAI tools format for AI tool integrations. It does not support the deprecated functions format.

When you include a tools parameter in your request, the API analyzes Claude's response for JSON content (via direct parsing, markdown code blocks, or embedded objects) and converts matching JSON into an OpenAI-compatible tool_calls response.

Note: The API does not execute the tools itself; it only handles the formatting of the tool call request from the model.

{
  "model": "claude-3-5-haiku-20241022",
  "messages": [
    {
      "role": "user",
      "content": "Please preview this URL: https://example.com"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "url_preview",
        "description": "Preview a URL and extract its content",
        "parameters": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "description": "The URL to preview"
            }
          },
          "required": ["url"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

To manage complex agent definitions in Rust, use these patterns:

Type-Safe Tool Lists

Avoid string typos by defining tool sets as constants:

const READONLY_TOOLS: &[&str] = &["Read", "Grep", "Glob"];

Agent Builder Pattern

Implement a custom AgentBuilder struct to provide a fluent API for creating AgentDefinition objects. This encapsulates default values (like model: "sonnet") and provides helper methods for common tool configurations (e.g., .readonly_tools() or .editor_tools()).

Model Selection Strategy

Map task complexity to specific models to optimize cost and performance:

• Simple tasks: haiku
• Medium tasks: sonnet
• Complex tasks: opus

// Example of an Agent Builder pattern
struct AgentBuilder {
    name: String,
    description: String,
    prompt: String,
    tools: Vec<String>,
    model: String,
}

impl AgentBuilder {
    fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            description: String::new(),
            prompt: String::new(),
            tools: Vec::new(),
            model: "sonnet".to_string(),
        }
    }

    fn readonly_tools(mut self) -> Self {
        self.tools = vec!["Read".into(), "Grep".into(), "Glob".into()];
        self
    }

    fn build(self) -> (String, AgentDefinition) {
        ( 
            self.name.clone(), 
            AgentDefinition { 
                description: self.description, 
                prompt: self.prompt, 
                tools: Some(self.tools), 
                model: Some(self.model) 
            } 
        )
    }
}

The Rust SDK provides three ways to define subagents, allowing you to balance flexibility, portability, and type safety:

1. Programmatic Definition (agents()): Define agents directly in your Rust code using AgentDefinition.

   • Pros: Dynamic generation, no file dependencies, version-controlled in code, type-safe.
   • Cons: Cannot be shared across projects or used directly in the CLI.
   • Best for: CI/CD, automated testing, or session-specific agents.

2. File System Definition (.claude/agents/): Define agents in Markdown files within the .claude/agents/ directory.

   • Pros: Team sharing, CLI compatibility, highly reusable.
   • Cons: Requires configuring setting_sources and introduces file dependencies.
   • Best for: Team collaboration and cross-project reuse.

3. Hybrid Approach: Combine both programmatic and file-system definitions.

   • Pros: Maximum flexibility.
   • Cons: Increased management complexity.
   • Best for: Large-scale projects.

The SDK uses a hierarchical trait system to provide a unified interface across different AI providers (like Claude Code or Codex).

• AgentProvider: The top-level abstraction used to discover capabilities, estimate costs, and create sessions. It identifies the ProviderType (e.g., ClaudeCode, Codex, DirectAPI, or Custom).
• AgentSession: The interface for interacting with an active agent. It allows sending UserInput, receiving a stream of AgentEvents, interrupting tasks, and retrieving usage statistics.

This abstraction allows you to write code that works with any agent provider without knowing the underlying implementation details.

#[async_trait]
pub trait AgentProvider: Send + Sync {
    fn provider_type(&self) -> ProviderType;
    async fn create_session(&self, config: SessionConfig) -> Result<Box<dyn AgentSession>>;
    fn capabilities(&self) -> ProviderCapabilities;
    fn can_handle_task(&self, task: &TaskDescriptor) -> bool;
    async fn estimate_cost(&self, task: &TaskDescriptor) -> Result<CostEstimate>;
}

#[async_trait]
pub trait AgentSession: Send + Sync {
    async fn send_input(&mut self, input: UserInput) -> Result<()>;
    fn receive_events(&mut self) -> Pin<Box<dyn Stream<Item = Result<AgentEvent>> + Send + '_>>;
    async fn interrupt(&mut self) -> Result<()>;
    async fn get_usage(&self) -> UsageStats;
    fn metadata(&self) -> &SessionMetadata;
    async fn close(self: Box<Self>) -> Result<()>;
}