Quickstart

Prerequisites

Before you begin, make sure you have:

Rust 1.70 or higher installed
An Anthropic API key, Google AI API key (Gemini), or OpenAI API key
Basic familiarity with async Rust and Tokio

Installation

Add PiCrust to your project’s Cargo.toml:

[dependencies]
picrust = { path = "path/to/picrust" }
tokio = { version = "1", features = ["full"] }
anyhow = "1.0"

Environment Setup

Set up your LLM provider credentials:

# For Anthropic Claude
export ANTHROPIC_API_KEY="sk-ant-..."
export ANTHROPIC_MODEL="claude-sonnet-4-5@20250929"

# Or for Google Gemini
export GEMINI_API_KEY="..."
export GEMINI_MODEL="gemini-3-flash-preview"

# Or for OpenAI
export OPENAI_API_KEY="sk-..."
export OPENAI_MODEL="gpt-4o"

Your First Agent

Create a new file src/main.rs and add the following code:

use std::sync::Arc;
use picrust::{
    agent::{AgentConfig, StandardAgent},
    llm::{AnthropicProvider, LlmProvider},
    runtime::AgentRuntime,
    session::AgentSession,
    tools::ToolRegistry,
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 1. Create LLM provider (reads ANTHROPIC_API_KEY and ANTHROPIC_MODEL from env)
    let llm: Arc<dyn LlmProvider> = Arc::new(AnthropicProvider::from_env()?);

    // 2. Create runtime (manages all agents)
    let runtime = AgentRuntime::new();

    // 3. Create session (persists conversation)
    let session = AgentSession::new(
        "my-session",      // unique ID
        "assistant",       // agent type
        "My Assistant",    // display name
        "A helpful agent", // description
    )?;

    // 4. Configure and create agent
    let config = AgentConfig::new("You are a helpful assistant.")
        .with_streaming(true);
    let agent = StandardAgent::new(config, llm);

    // 5. Spawn agent
    let handle = runtime
        .spawn(session, |internals| agent.run(internals))
        .await;

    // 6. Send input and receive output
    let mut rx = handle.subscribe();
    handle.send_input("Hello!").await?;

    // 7. Process output stream
    loop {
        match rx.recv().await {
            Ok(chunk) => {
                use picrust::core::OutputChunk;
                match chunk {
                    OutputChunk::TextDelta(text) => print!("{}", text),
                    OutputChunk::Done => break,
                    OutputChunk::Error(e) => eprintln!("Error: {}", e),
                    _ => {}
                }
            }
            Err(_) => break,
        }
    }

    Ok(())
}

Run Your Agent

Execute your agent:

cargo run

You should see the agent’s response stream to your terminal.

Understanding the Code

Let’s break down what’s happening:

1. LLM Provider

let llm: Arc<dyn LlmProvider> = Arc::new(AnthropicProvider::from_env()?);

Creates an LLM provider that reads credentials from environment variables. The SDK supports multiple providers (Claude, Gemini) through the LlmProvider trait.

2. Agent Runtime

let runtime = AgentRuntime::new();

The runtime manages agent lifecycles. It spawns agents as async tasks and maintains a registry of running agents.

3. Session

let session = AgentSession::new(
    "my-session",
    "assistant",
    "My Assistant",
    "A helpful agent",
)?;

Sessions persist conversation history to disk automatically (in ./sessions/{id}/). This enables conversation continuity across restarts.

4. Agent Configuration

let config = AgentConfig::new("You are a helpful assistant.")
    .with_streaming(true);
let agent = StandardAgent::new(config, llm);

AgentConfig defines agent behavior. StandardAgent is the main agent implementation that handles the request-response loop.

5. Spawning

let handle = runtime
    .spawn(session, |internals| agent.run(internals))
    .await;

Spawns the agent as an async task and returns a handle for communication.

6. Communication

let mut rx = handle.subscribe();  // Subscribe BEFORE sending
handle.send_input("Hello!").await?;

Critical Pattern: Always subscribe to the output stream before sending input. Otherwise, you’ll miss early output chunks.

7. Output Processing

match chunk {
    OutputChunk::TextDelta(text) => print!("{}", text),
    OutputChunk::Done => break,
    OutputChunk::Error(e) => eprintln!("Error: {}", e),
    _ => {}
}

The agent streams output in chunks. TextDelta contains text tokens, Done signals completion.

Adding Tools

Let’s make the agent more useful by adding file access:

use picrust::tools::common::*;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let llm: Arc<dyn LlmProvider> = Arc::new(AnthropicProvider::from_env()?);
    let runtime = AgentRuntime::new();

    // Create and register tools
    let mut tools = ToolRegistry::new();
    tools.register(ReadTool::new()?);
    tools.register(WriteTool::new()?);
    tools.register(BashTool::new()?);
    let tools = Arc::new(tools);

    let session = AgentSession::new("session-1", "coder", "Code Assistant", "")?;

    // Add tools to config
    let config = AgentConfig::new("You are a helpful coding assistant.")
        .with_tools(tools)
        .with_streaming(true);

    let agent = StandardAgent::new(config, llm);
    let handle = runtime.spawn(session, |internals| agent.run(internals)).await;

    let mut rx = handle.subscribe();
    handle.send_input("Create a hello.rs file with a hello world program").await?;

    // Process output
    loop {
        match rx.recv().await {
            Ok(chunk) => {
                use picrust::core::OutputChunk;
                match chunk {
                    OutputChunk::TextDelta(text) => print!("{}", text),
                    OutputChunk::ToolStart { name, .. } => {
                        println!("\n[Using tool: {}]", name);
                    }
                    OutputChunk::Done => break,
                    OutputChunk::Error(e) => eprintln!("Error: {}", e),
                    _ => {}
                }
            }
            Err(_) => break,
        }
    }

    Ok(())
}

Now the agent can read files, write files, and execute shell commands!

Switching Providers

All three providers are interchangeable — just swap one line:

use picrust::llm::{AnthropicProvider, GeminiProvider, OpenAIProvider};

// Anthropic Claude (default)
let llm: Arc<dyn LlmProvider> = Arc::new(AnthropicProvider::from_env()?);

// Google Gemini
let llm: Arc<dyn LlmProvider> = Arc::new(GeminiProvider::from_env()?);

// OpenAI
let llm: Arc<dyn LlmProvider> = Arc::new(OpenAIProvider::from_env()?);

The rest of the code stays the same regardless of which provider you use.

When using OpenAI, disable prompt caching (it’s an Anthropic-specific feature) and use the OpenAI env vars:

export OPENAI_API_KEY="sk-..."
export OPENAI_MODEL="gpt-4o"
# Optional: custom endpoint (proxy, Azure, etc.)
# export OPENAI_BASE_URL="https://my-proxy.example.com/v1/responses"

let config = AgentConfig::new().with_prompt_caching(false);

Handling Permissions

By default, tools require user permission. Handle permission requests:

loop {
    match rx.recv().await {
        Ok(chunk) => {
            use picrust::core::OutputChunk;
            match chunk {
                OutputChunk::TextDelta(text) => print!("{}", text),

                OutputChunk::PermissionRequest { tool_name, action, .. } => {
                    println!("\n[Permission needed: {} wants to {}]", tool_name, action);

                    // Approve the request
                    handle.send_permission_response(
                        tool_name,
                        true,   // allowed
                        false   // don't remember
                    ).await?;
                }

                OutputChunk::Done => break,
                _ => {}
            }
        }
        Err(_) => break,
    }
}

Or skip permissions for trusted scenarios (use with caution):

let config = AgentConfig::new("You are a helpful assistant.")
    .with_dangerous_skip_permissions(true)  // Skip all permission checks
    .with_streaming(true);

Viewing Conversation History

All conversations are automatically saved to disk. View them:

use picrust::session::AgentSession;

// Load and display history
let history = AgentSession::get_history("my-session")?;

for message in history {
    println!("{}: {:?}", message.role, message.content);
}

Complete Example

Here’s a complete interactive agent:

use std::sync::Arc;
use std::io::{self, Write};
use picrust::{
    agent::{AgentConfig, StandardAgent},
    llm::{AnthropicProvider, LlmProvider},
    runtime::AgentRuntime,
    session::AgentSession,
    tools::{ToolRegistry, common::*},
    core::OutputChunk,
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Setup
    let llm: Arc<dyn LlmProvider> = Arc::new(AnthropicProvider::from_env()?);
    let runtime = AgentRuntime::new();

    let mut tools = ToolRegistry::new();
    tools.register(ReadTool::new()?);
    tools.register(WriteTool::new()?);
    tools.register(BashTool::new()?);
    let tools = Arc::new(tools);

    let session = AgentSession::new(
        "interactive-session",
        "assistant",
        "Interactive Assistant",
        "",
    )?;

    let config = AgentConfig::new("You are a helpful assistant.")
        .with_tools(tools)
        .with_streaming(true);

    let agent = StandardAgent::new(config, llm);
    let handle = runtime.spawn(session, |internals| agent.run(internals)).await;

    // Interactive loop
    println!("Agent ready! Type 'exit' to quit.\n");

    loop {
        print!("> ");
        io::stdout().flush()?;

        let mut input = String::new();
        io::stdin().read_line(&mut input)?;
        let input = input.trim();

        if input == "exit" {
            break;
        }

        if input.is_empty() {
            continue;
        }

        // Subscribe and send
        let mut rx = handle.subscribe();
        handle.send_input(input).await?;

        // Process output
        loop {
            match rx.recv().await {
                Ok(chunk) => match chunk {
                    OutputChunk::TextDelta(text) => print!("{}", text),
                    OutputChunk::ToolStart { name, .. } => {
                        print!("\n[Tool: {}] ", name);
                    }
                    OutputChunk::PermissionRequest { tool_name, action, .. } => {
                        println!("\n[Permission: {} - {}]", tool_name, action);
                        handle.send_permission_response(tool_name, true, false).await?;
                    }
                    OutputChunk::Done => {
                        println!("\n");
                        break;
                    }
                    OutputChunk::Error(e) => {
                        eprintln!("Error: {}", e);
                        break;
                    }
                    _ => {}
                },
                Err(_) => break,
            }
        }
    }

    Ok(())
}

Next Steps

Now that you have a working agent, explore more features:

Core Concepts

Learn about Runtime, Sessions, and Agent States

Built-in Tools

Explore all available tools

Permission System

Understand the three-tier permission system

Hooks

Intercept and modify agent behavior

Common Issues

”Permission denied” errors

Make sure to handle OutputChunk::PermissionRequest or use:

.with_dangerous_skip_permissions(true)

No output streaming

Remember to subscribe before sending input:

let mut rx = handle.subscribe();  // Do this first!
handle.send_input("Hello").await?;  // Then this

API key not found

Set the env vars for your chosen provider:

# Anthropic
export ANTHROPIC_API_KEY="your-key"
export ANTHROPIC_MODEL="claude-sonnet-4-5@20250929"

# Gemini
export GEMINI_API_KEY="your-key"
export GEMINI_MODEL="gemini-3-flash-preview"

# OpenAI
export OPENAI_API_KEY="your-key"
export OPENAI_MODEL="gpt-4o"

What’s Next?

You’ve built your first agent! Continue learning:

Architecture Overview - Understand the system design
Streaming & History - Critical patterns for UIs
Custom Tools - Build your own tools
Tauri Integration - Build desktop apps

Ready to dive deeper? Explore the Core Concepts next!

Get Started

Core Concepts

Features

Tools

Permissions

Hooks

MCP

LLM Providers

Advanced

Integration

Prerequisites

Installation

Environment Setup

Your First Agent

Run Your Agent

Understanding the Code

1. LLM Provider

2. Agent Runtime

3. Session

4. Agent Configuration

5. Spawning

6. Communication

7. Output Processing

Adding Tools

Switching Providers

Handling Permissions

Viewing Conversation History

Complete Example

Next Steps

Core Concepts

Built-in Tools

Permission System

Hooks

Common Issues

”Permission denied” errors

No output streaming

API key not found

What’s Next?

​Prerequisites

​Installation

​Environment Setup

​Your First Agent

​Run Your Agent

​Understanding the Code

​1. LLM Provider

​2. Agent Runtime

​3. Session

​4. Agent Configuration

​5. Spawning

​6. Communication

​7. Output Processing

​Adding Tools

​Switching Providers

​Handling Permissions

​Viewing Conversation History

​Complete Example

​Next Steps

Core Concepts

Built-in Tools

Permission System

Hooks

​Common Issues

​”Permission denied” errors

​No output streaming

​API key not found

​What’s Next?

Prerequisites

Installation

Environment Setup

Your First Agent

Run Your Agent

Understanding the Code

1. LLM Provider

2. Agent Runtime

3. Session

4. Agent Configuration

5. Spawning

6. Communication

7. Output Processing

Adding Tools

Switching Providers

Handling Permissions

Viewing Conversation History

Complete Example

Next Steps

Common Issues

”Permission denied” errors

No output streaming

API key not found

What’s Next?