Kowalski Agent Template

A flexible foundation for building custom AI agents in the Kowalski ecosystem. This crate provides a robust agent base, builder patterns, configuration, and ready-to-use templates for rapid agent development.

Description

kowalski-agent-template is designed to make it easy to create new, specialized AI agents by composing tools, task handlers, and configuration. It provides a TemplateAgent abstraction, a builder for ergonomic construction, and a set of templates (such as general-purpose and research agents) to jumpstart development.

Dependencies

kowalski-core — Core agent abstractions, tools, and types
kowalski-tools — Ready-to-use tools (web search, PDF, data, code, etc.)
tokio — Async runtime
reqwest — HTTP client
serde — Serialization/deserialization
serde_json — JSON support
async-trait — Async trait support
log — Logging
thiserror — Error handling
futures — Async utilities
bytes — Byte buffers
tower, tower-http — Middleware and HTTP utilities
tracing, tracing-subscriber — Structured logging and tracing
url — URL parsing
regex — Regular expressions
markdown — Markdown parsing
env_logger — Logging backend

Architecture

kowalski-agent-template/
├── src/
│   ├── agent.rs        # TemplateAgent and TaskHandler traits
│   ├── builder.rs      # AgentBuilder for ergonomic agent construction
│   ├── config.rs       # TemplateAgentConfig and defaults
│   ├── lib.rs          # Library entry point
│   └── templates/      # Predefined agent templates
│       ├── general.rs  # General-purpose agent template
│       ├── research.rs # Research-focused agent template
│       └── mod.rs

TemplateAgent: Core agent abstraction with tool/task handler registration and execution
AgentBuilder: Builder pattern for ergonomic agent construction
Templates: Predefined agent blueprints for common use cases
Config: Extensible configuration for agent behavior and system prompts

Core Functionality & Examples

1. TemplateAgent: The Extensible Agent

The TemplateAgent struct provides a flexible base for building custom agents. It supports:

Tool registration (for pluggable capabilities)
Task handler registration (for custom logic)
System prompt configuration
Async task execution

use kowalski_agent_template::agent::TemplateAgent;
use kowalski_core::tools::{Tool, ToolInput, ToolOutput};
use kowalski_core::config::Config;

let config = Config::default();
let agent = TemplateAgent::new(config).await?;
// Register tools and handlers as needed

2. AgentBuilder: Ergonomic Construction

The AgentBuilder pattern allows you to fluently compose an agent with custom tools, prompts, and settings.

use kowalski_agent_template::builder::AgentBuilder;
use kowalski_tools::web::WebSearchTool;

let builder = AgentBuilder::new()
    .await
    .with_system_prompt("You are a helpful assistant.")
    .with_tool(WebSearchTool::new("duckduckgo".to_string()))
    .with_temperature(0.5);

let agent = builder.build().await?;

3. Configuration

The TemplateAgentConfig struct provides flexible configuration for agent behavior, including concurrency, timeouts, user agent, and system prompt.

use kowalski_agent_template::config::TemplateAgentConfig;

let config = TemplateAgentConfig::default();
println!("System prompt: {}", config.system_prompt);

4. Templates: Ready-to-Use Agent Blueprints

GeneralTemplate

A general-purpose agent with basic tools (web search, PDF processing) and customizable prompt/temperature.

use kowalski_agent_template::templates::general::GeneralTemplate;

let builder = GeneralTemplate::create_default_agent().await?;
let agent = builder.build().await?;

You can also create a custom general agent:

let builder = GeneralTemplate::create_agent(
    vec![Box::new(WebSearchTool::new("duckduckgo".to_string()))],
    Some("You are a specialized assistant for web research.".to_string()),
    Some(0.5)
).await?;
let agent = builder.build().await?;

ResearchTemplate

A research-focused agent with web search and PDF analysis tools, and a research-oriented system prompt.

use kowalski_agent_template::templates::research::ResearchTemplate;

let builder = ResearchTemplate::create_agent().await?;
let agent = builder.build().await?;

How to Extend

Add new tools: Implement the Tool trait and register with your agent or builder.
Add new task handlers: Implement the TaskHandler trait for custom logic.
Create new templates: Compose new agent blueprints in the templates/ directory.
Customize configuration: Use or extend TemplateAgentConfig for new settings.

Future Enhancements

More agent templates for specific domains (e.g., coding, data analysis, customer support)
Dynamic tool loading and plugin support
Advanced orchestration (multi-agent, federated agents)
Persistent agent state and conversation history
Integration with external APIs and databases
Enhanced configuration and environment support

kowalski-agent-template 0.5.0