Quickstart

Get a Paladin agent running in under five minutes.

Prerequisites

Complete Installation first and set your LLM API key:

export OPENAI_API_KEY="sk-..."

Create a New Project

cargo new my-paladin-agent
cd my-paladin-agent

Add Paladin to Cargo.toml:

[dependencies]
paladin-ai-core   = "0.5.0"
paladin-ports     = "0.5.0"
paladin-llm       = { version = "0.5.0", features = ["llm-openai"] }
tokio             = { version = "1", features = ["full"] }

Your First Paladin Agent

Replace src/main.rs with the following:

// src/main.rs -- Hello, Paladin!
use paladin_ai_core::application::services::paladin::paladin_builder::PaladinBuilder;
use paladin_ai_core::application::services::paladin::paladin_execution_service::PaladinExecutionService;
use paladin_ports::output::llm_port::LlmPort;
use paladin_llm::openai::OpenAIAdapter;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Create an LLM adapter (reads OPENAI_API_KEY from env)
    let llm_port: Arc<dyn LlmPort> = Arc::new(OpenAIAdapter::from_env()?);

    // 2. Build the Paladin using the fluent builder
    let paladin = PaladinBuilder::new(llm_port.clone())
        .system_prompt("You are a concise and helpful assistant.")
        .name("HelloPaladin")
        .model("gpt-4")
        .temperature(0.7)
        .max_loops(1)
        .build()
        .await?;

    // 3. Create an execution service
    let service = PaladinExecutionService::new(llm_port, Default::default(), None, None);

    // 4. Execute with a prompt
    let result = service.execute(&paladin, "Say hello in one sentence.").await?;

    println!("Output : {}", result.output);
    println!("Tokens : {}", result.token_count);
    println!("Time   : {}ms", result.execution_time_ms);

    Ok(())
}

Run it:

cargo run

Expected output (exact wording varies):

Output : Hello! I am your AI assistant, ready to help.
Tokens : 18
Time   : 342ms

Running the Built-in Examples

The Paladin workspace ships with ready-to-run examples:

# Clone the workspace if you haven't already
git clone https://github.com/DF3NDR/paladin-dev-env.git
cd paladin-dev-env

# Start backing services (Redis, MinIO) -- optional for basic examples
make services-up

# Run the basic Paladin example
cargo run --example basic_paladin

# Sequential multi-agent pipeline
cargo run --example formation_sequential

# Concurrent multi-agent execution
# cargo run --example phalanx_concurrent

Understanding the Output

PaladinExecutionService::execute returns a PaladinResult with these fields:

What's Next?