Skip to main content

​
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 Shadow Agent SDK, agents are the core building blocks of your agentic applications.

​
Agent Lifecycle

1

Initialization

Create an agent instance with your LLM provider configuration:
let agent = Agent::new("api-key").await?;
2

Tool Registration

Add tools that the agent can use:
agent.add_tool(ReadFile::new());
agent.add_tool(BashExecutor::new());
3

Execution

Execute tasks and get responses:
let response = agent.execute("Analyze this file").await?;
4

Cleanup

Resources are automatically cleaned up when the agent is dropped.

​
Agent Configuration

Configure agent behavior with various options: 
use shadow_agent_sdk::{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

Give agents specific, actionable instructions:Good: “Read the config.json file and extract the database URL”Bad: “Do something with the config”
Only register tools that the agent needs to reduce complexity and improve safety:
// Only add file reading, not writing
agent.add_tool(ReadFile::new());
Always handle potential errors from agent operations:
match agent.execute("task").await {
    Ok(response) => println!("{}", response),
    Err(e) => eprintln!("Agent error: {}", e),
}
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);
});

​
Next Steps

Tools

Learn about available tools

MCP Integration

Extend agents with MCP