Hello Agent

The simplest possible Heartbit agent. This example creates a single AgentRunner, sends it one prompt, and prints the result along with token usage statistics.

Prerequisites

• ANTHROPIC_API_KEY environment variable set with a valid API key

Running

export ANTHROPIC_API_KEY="sk-..."
cargo run -p heartbit --example hello_agent

Source

use std::sync::Arc;

use heartbit::{AgentRunner, AnthropicProvider};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key =
        std::env::var("ANTHROPIC_API_KEY").expect("set ANTHROPIC_API_KEY environment variable");
    let provider = Arc::new(AnthropicProvider::new(api_key, "claude-sonnet-4-20250514"));

    let agent = AgentRunner::builder(provider)
        .name("greeter")
        .system_prompt("You are a friendly assistant. Be concise.")
        .max_turns(1)
        .max_tokens(1024)
        .build()?;

    let output = agent.execute("Say hello in three languages.").await?;
    println!("{}", output.result);
    eprintln!(
        "[tokens: {} in / {} out, {} tool calls]",
        output.tokens_used.input_tokens, output.tokens_used.output_tokens, output.tool_calls_made
    );

    Ok(())
}

Walkthrough

Provider setup — AnthropicProvider::new takes an API key and model ID. Wrap it in Arc so it can be shared across agent internals.

Builder pattern — AgentRunner::builder(provider) starts the builder chain. Key settings:

• name("greeter") — identifies the agent in logs and events
• system_prompt(...) — sets the system message that shapes agent behavior
• max_turns(1) — limits the agent to a single LLM call (no tool-use loop)
• max_tokens(1024) — caps the response length

Execution — agent.execute("...") sends the user message and runs the agent loop. It returns an AgentOutput containing:

• result — the final text response
• tokens_used — input/output token counts
• tool_calls_made — number of tool invocations (zero here since no tools are configured)

What to expect

The agent responds with a greeting in three languages (the exact languages may vary), followed by a token usage summary on stderr:

Hello! (English)
Bonjour! (French)
Hola! (Spanish)
[tokens: 42 in / 28 out, 0 tool calls]