quickstart

Quickstart

Create your first AI agent in under 5 minutes.

Prerequisites

• Rust 1.85.0 or later (rustup update stable)
• A Google API key (get one here)

Step 1: Scaffold Your Project

cargo install cargo-adk
cargo adk new my_agent
cd my_agent

This generates a working project with the right dependencies and boilerplate.

Other Templates

# Agent with custom tools using #[tool] macro
cargo adk new my_agent --template tools

# RAG agent with Gemini embeddings and in-memory vector search
cargo adk new my_agent --template rag

# REST API server ready for deployment
cargo adk new my_agent --template api

# OpenAI GPT-5-mini agent
cargo adk new my_agent --template openai

# Use any provider with any template
cargo adk new my_agent --template tools --provider anthropic

Template	What you get
basic	Gemini agent with interactive console (default)
tools	Agent with #[tool] macro custom tools + schemars schema generation
rag	RAG pipeline — Gemini embeddings, in-memory vector store, document ingestion
api	Axum REST server with health check, ready for docker build
openai	OpenAI GPT-5-mini agent with console

Step 2: Add Your API Key

cp .env.example .env
# Edit .env and add your GOOGLE_API_KEY

Step 3: Run

cargo run

That's it — you have a working agent. Chat with it in your terminal.

ADK Console Mode
Agent: my_agent
Type your message and press Enter. Ctrl+C to exit.

> Hello! What can you help me with?

I'm a helpful AI assistant. I can help you with answering questions,
explaining concepts, and having a friendly conversation.

---

Zero-Config Alternative — adk::run()

If you just want to run a quick agent without scaffolding, use the one-liner:

use adk_rust::run;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    dotenvy::dotenv().ok();
    // Minimal default: set GOOGLE_API_KEY. Add provider features for OpenAI/Anthropic.
    let response = run("You are a helpful assistant.", "Explain Rust in one sentence.").await?;
    println!("{response}");
    Ok(())
}

This handles provider detection for compiled providers, session creation, agent building, and execution in a single call. Great for scripts, prototypes, and quick experiments.

---

Understanding the Generated Code

The scaffolded src/main.rs:

use adk_rust::prelude::*;
use adk_rust::Launcher;
use std::sync::Arc;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    dotenvy::dotenv().ok();
    let api_key = std::env::var("GOOGLE_API_KEY")?;

    let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?;

    let agent = LlmAgentBuilder::new("my_agent")
        .description("A helpful AI assistant")
        .instruction("You are a friendly assistant. Be concise and helpful.")
        .model(Arc::new(model))
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;
    Ok(())
}

Part	What it does
prelude::*	Imports core types: GeminiModel, LlmAgentBuilder, Arc, etc.
GeminiModel::new()	Creates an LLM client with API key auth and streaming
LlmAgentBuilder	Builder pattern: name, description, instruction (system prompt), model, tools
Launcher	Runs the agent in console mode by default; use the api template for HTTP serving

---

Adding Custom Tools

The fastest way to add tools is the #[tool] macro. Add adk-tool to your dependencies:

[dependencies]
adk-tool = "0.8.0"
schemars = "1"
serde = { version = "1", features = ["derive"] }

Then define a tool — the doc comment becomes the description, the args struct becomes the JSON schema:

use adk_tool::{tool, AdkError};
use schemars::JsonSchema;
use serde::Deserialize;
use serde_json::{json, Value};

#[derive(Deserialize, JsonSchema)]
struct WeatherArgs {
    /// The city to look up
    city: String,
}

/// Get the current weather for a city.
#[tool]
async fn get_weather(args: WeatherArgs) -> std::result::Result<Value, AdkError> {
    Ok(json!({ "temp": 22, "city": args.city, "condition": "sunny" }))
}

The macro generates a GetWeather struct implementing Tool. Add it to your agent:

let agent = LlmAgentBuilder::new("weather_agent")
    .instruction("Use the get_weather tool for weather questions.")
    .model(Arc::new(model))
    .tool(Arc::new(GetWeather))  // Generated by #[tool]
    .build()?;

Tip: Or scaffold a project with tools already set up: cargo adk new my-agent --template tools

Built-in Tools

ADK also includes ready-to-use tools:

// Google Search (handled server-side by Gemini)
.tool(Arc::new(GoogleSearchTool::new()))

// Exit a LoopAgent
.tool(Arc::new(ExitLoopTool::new()))

---

Running as a Web Server

Scaffold a server project when you want HTTP serving:

cargo adk new my-api --template api
cd my-api
cargo run

The default basic template uses the lightweight console launcher for fastest installs.

---

Using Other Models

Enable providers via feature flags. The default build stays Gemini-only for fast installs, so add only the provider you need:

[dependencies]
adk-rust = { version = "0.8.0", features = ["openai"] }

Or scaffold with a provider: cargo adk new my-agent --provider openai

OpenAI

let api_key = std::env::var("OPENAI_API_KEY")?;
let model = OpenAIClient::new(OpenAIConfig::new(api_key, "gpt-5-mini"))?;

Anthropic

let api_key = std::env::var("ANTHROPIC_API_KEY")?;
let model = AnthropicClient::new(AnthropicConfig::new(api_key, "claude-sonnet-4-6"))?;

DeepSeek

let api_key = std::env::var("DEEPSEEK_API_KEY")?;
let model = DeepSeekClient::chat(api_key)?;         // standard
// let model = DeepSeekClient::reasoner(api_key)?;   // chain-of-thought

Groq

let api_key = std::env::var("GROQ_API_KEY")?;
let model = GroqClient::new(GroqConfig::llama70b(api_key))?;

Ollama (Local)

// Requires: ollama serve && ollama pull llama3.2
let model = OllamaModel::new(OllamaConfig::new("llama3.2"))?;

Supported Models

Provider	Model Examples	Feature Flag
Gemini	gemini-2.5-flash, gemini-2.5-pro, gemini-3-pro-preview	(default)
OpenAI	gpt-5, gpt-5-mini, gpt-4.1	openai
Anthropic	claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5	anthropic
DeepSeek	deepseek-chat, deepseek-reasoner	deepseek
Groq	meta-llama/llama-4-scout-17b-16e-instruct, llama-3.3-70b-versatile	groq
Ollama	qwen3.6:35b-a3b, qwen3.5, llama3.2:3b	ollama

---

Next Steps

• LlmAgent Configuration — all configuration options
• Function Tools — create custom tools with #[tool]
• Workflow Agents — sequential, parallel, loop pipelines
• Sessions — manage conversation state
• Callbacks — customize agent behavior

---

Previous: Introduction | Next: LlmAgent