agentcore 0.1.1

Quick Start

use std::sync::Arc;
use agentcore::{AgentBuilder, AnthropicProvider, ReadFileTool, GlobTool};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let provider = Arc::new(AnthropicProvider::from_api_key(
        std::env::var("ANTHROPIC_API_KEY")?,
    ));

    let output = AgentBuilder::new()
        .provider(provider)
        .model("claude-sonnet-4-20250514")
        .instruction_prompt("Find all Rust source files and describe what this project does.")
        .tool(ReadFileTool)
        .tool(GlobTool)
        .run()
        .await?;

    println!("{}", output.response_raw);
    Ok(())
}

Use Cases

Example applications built with this project.

Consider setting your LLM provider's environment variables for key, model or base URL.

Project Scanner

Scans a directory and outputs a JSON summary with project description and languages used.

make use-case name=project-scanner -- ./

Output:

{
  "summary": "A minimal Rust framework for building agentic LLM applications with tool use",
  "languages": ["Rust"]
}

Deep Research

Spawns three researcher sub-agents in parallel, then aggregates their findings into a structured decision. Requires BRAVE_API_KEY for web search.

make use-case name=deep-research args="What constitutes a good life?"

Output:

{
  "title": "What Constitutes a Good Life: A Multi-Perspective Analysis",
  "research": "A good life emerges from the convergence of philosophical wisdom, scientific research, and cultural understanding. Key elements include meaningful relationships and social connections, a sense of purpose and personal growth, physical and mental well-being, contributing to something beyond oneself, and living in accordance with personal values. While cultural contexts vary, common themes across traditions emphasize virtue, balance, gratitude, and the cultivation of both inner fulfillment and positive impact on others."
}

API

Configure an AgentBuilder with a provider, model, tools, and prompt, then call .run() to get an AgentOutput. Stream Events during execution.

LlmProvider

Connect to any LLM. Providers own a reqwest::Client for connection pooling and SSE streaming.

use agentcore::{AnthropicProvider, MistralProvider, LiteLlmProvider};

let provider = AnthropicProvider::from_api_key(key);
let provider = MistralProvider::from_api_key(key);
let provider = LiteLlmProvider::from_api_key(key);

let client = reqwest::Client::new();                        // share a connection pool
let provider = AnthropicProvider::new(key, client);

AgentBuilder

One builder for everything — agent definition, runtime context, and execution.

use agentcore::AgentBuilder;

let output = AgentBuilder::new()
    .identity_prompt("You are a helpful assistant.")
    .instruction_prompt("What does src/main.rs do?")
    .model("claude-sonnet-4-20250514")
    .tool(ReadFileTool)
    .provider(provider)
    .run()
    .await?;

Prompt types

Use {key} placeholders in the identity prompt and fill them with template_variable (or template_variables).

Sub-agents

Use .build() to get Arc<dyn Agent> for registration as a sub-agent. Without .model(), a sub-agent inherits its parent's model at runtime. Clone the builder to create multiple similar agents:

let researcher_base = AgentBuilder::new()
    .model("claude-haiku-4-5-20251001")
    .identity_prompt("Research this topic.")
    .tool(brave_search_tool())
    .max_turns(3);

let r1 = researcher_base.clone().name("researcher_1").build()?;
let r2 = researcher_base.clone().name("researcher_2").build()?;

let output = AgentBuilder::new()
    .name("orchestrator")
    .identity_prompt("Coordinate research.")
    .sub_agent(r1)
    .sub_agent(r2)

Guardrails

Limit agent execution to prevent runaway cost or duration.

Behavior prompts

Agents ship with default behavior prompts appended to the identity prompt. Override any:

use agentcore::BehaviorPrompt;

AgentBuilder::new()
    .behavior_prompt(BehaviorPrompt::TaskExecution, "Follow instructions exactly.")
    .behavior_prompt(BehaviorPrompt::OutputEfficiency, "Always respond in JSON.")

Sessions

Record every message exchanged during a run to disk as JSONL. The agent is not aware of this — recording happens transparently in the framework.

AgentBuilder::new()
    .session_dir(PathBuf::from("./data"))

Each run writes <dir>/sessions/<id>/transcript.jsonl — one JSON line per user message, assistant response, and tool result, with timestamps and token usage.

Events

Emitted via AgentBuilder.event_handler() during execution.

Tools

Define what the agent can do. Read-only tools run concurrently.

use agentcore::{ToolBuilder, ToolResult};

let tool = ToolBuilder::new("greet", "Say hello")
    .schema(json!({...}))
    .read_only(true)
    .handler(|input, ctx| Box::pin(async move {
        Ok(ToolResult::success("Hello!"))
    }))
    .build();

Built-in tools:

AgentOutput

The result of .run().

output.response_raw            // free-form LLM text
output.response                // validated JSON if output_schema was set
output.statistics.costs        // total USD spent
output.statistics.input_tokens // total input tokens
output.statistics.output_tokens// total output tokens
output.statistics.requests     // number of LLM calls
output.statistics.tool_calls   // number of tool executions
output.statistics.turns        // number of agentic turns

With .output_schema(), the agent returns validated JSON in output.response:

let output = AgentBuilder::new()
    .output_schema(json!({
        "type": "object",
        "properties": { "category": { "type": "string" } },
        "required": ["category"]
    }))
    .max_schema_retries(3)  // retry if agent doesn't comply (default: 3)

    .run().await?;

output.response.unwrap()["category"]  // "billing"

Development

make                   # build
make test              # unit tests
make test_integration  # integration tests (requires LLM provider)
make fmt               # format code
make use-case          # list use cases
make bump              # bump patch version (part=minor or part=major)
make publish           # publish to crates.io (runs tests first)
make litellm           # start LiteLLM proxy

Environment

Use cases and integration tests pick up the LLM provider from these environment variables:

Anthropic

Mistral

LiteLLM proxy