Agents

What is an Agent?

An agent is an autonomous entity that can understand natural language instructions, make decisions, and use tools to accomplish tasks. In PiCrust, agents are the core building blocks of your agentic applications.

Agent Lifecycle

Initialization

Create an agent instance with your LLM provider configuration:

let agent = Agent::new("api-key").await?;

Tool Registration

Add tools that the agent can use:

agent.add_tool(ReadFile::new());
agent.add_tool(BashExecutor::new());

Execution

Execute tasks and get responses:

let response = agent.execute("Analyze this file").await?;

Cleanup

Resources are automatically cleaned up when the agent is dropped.

Agent Configuration

Configure agent behavior with various options:

use picrust::{Agent, AgentConfig};

let config = AgentConfig {
    model: "claude-3-5-sonnet-20241022",
    max_tokens: 4096,
    temperature: 0.7,
    ..Default::default()
};

let agent = Agent::with_config("api-key", config).await?;

Agent Capabilities

Decision Making

Agents can analyze situations and make autonomous decisions:

agent.execute(
    "Look at the error logs and determine the root cause"
).await?;

Tool Usage

Agents automatically select and use appropriate tools:

// Agent will use ReadFile tool automatically
agent.execute("What's in the config.json file?").await?;

Context Retention

Maintain conversation context across multiple interactions:

let session = agent.create_session().await?;

session.send("Read the README").await?;
session.send("Summarize what you just read").await?;
// Agent remembers the README content

Best Practices

Provide Clear Instructions

Give agents specific, actionable instructions:Good: “Read the config.json file and extract the database URL”Bad: “Do something with the config”

Enable Only Necessary Tools

Only register tools that the agent needs to reduce complexity and improve safety:

// Only add file reading, not writing
agent.add_tool(ReadFile::new());

Handle Errors Gracefully

Always handle potential errors from agent operations:

match agent.execute("task").await {
    Ok(response) => println!("{}", response),
    Err(e) => eprintln!("Agent error: {}", e),
}

Use Appropriate Models

Choose the right model for your use case:

Claude Opus: Complex reasoning tasks
Claude Sonnet: Balanced performance and cost
Gemini: Multimodal capabilities

Advanced Features

Custom System Prompts

Customize the agent’s behavior with system prompts:

let config = AgentConfig {
    system_prompt: "You are a helpful code review assistant...",
    ..Default::default()
};

Hooks and Callbacks

Add hooks to monitor agent behavior:

agent.on_tool_use(|tool_name, args| {
    println!("Agent used tool: {}", tool_name);
});

Get Started

Core Concepts

Features

Tools

Permissions

Hooks

MCP

LLM Providers

Advanced

Integration

What is an Agent?

Agent Lifecycle

Agent Configuration

Agent Capabilities

Decision Making

Tool Usage

Context Retention

Best Practices

Advanced Features

Custom System Prompts

Hooks and Callbacks

Next Steps

Tools

MCP Integration

​What is an Agent?

​Agent Lifecycle

​Agent Configuration

​Agent Capabilities

​Decision Making

​Tool Usage

​Context Retention

​Best Practices

​Advanced Features

​Custom System Prompts

​Hooks and Callbacks

​Next Steps

Tools

MCP Integration

What is an Agent?

Agent Lifecycle

Agent Configuration

Agent Capabilities

Decision Making

Tool Usage

Context Retention

Best Practices

Advanced Features

Custom System Prompts

Hooks and Callbacks

Next Steps