Início rápido

Crie seu primeiro agente de IA em menos de 5 minutos.

Pré-requisitos

• Rust 1.95.0 ou posterior (rustup update stable)
• Uma chave do Google API (obtenha uma aqui)

Etapa 1: Estruture Seu Projeto

cargo install cargo-adk
cargo adk new my_agent
cd my_agent

Isso gera um projeto funcional com as dependências corretas e o código inicial.

Outros Modelos

# 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

# A2A protocol agent with builder API
cargo adk new my_agent --template a2a

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

# Add optional addons to any template
cargo adk new my_agent --template tools --addon docker --addon ci

Dica: Use a flag --addon para compor templates com addons opcionais como docker, ci, telemetry e mais. Veja a página Composable Templates para a lista completa de 9 addons e 5 padrões enterprise.

Etapa 2: Adicione sua chave API

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

Etapa 3: Execute

cargo run

É isso — você tem um agente funcionando. Converse com ele no seu 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.

---

Alternativa sem configuração — adk::run()

Se você só quer executar um agente rápido sem scaffold, use a 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(())
}

Isso lida com a detecção do provider para providers compilados, criação de sessão, construção do agente e execução em uma única chamada. Ótimo para scripts, protótipos e experimentos rápidos.

---

Entendendo o código gerado

O src/main.rs scaffolded:

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(())
}

---

Adicionando Ferramentas Personalizadas

A maneira mais rápida de adicionar ferramentas é a macro #[tool]. Adicione adk-tool às suas dependências:

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

Em seguida, defina uma ferramenta — o comentário de documentação se torna a descrição, e a struct de argumentos se torna o esquema JSON:

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" }))
}

A macro gera uma struct GetWeather que implementa Tool. Adicione-a ao seu 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()?;

Dica: Ou crie um projeto com ferramentas já configuradas: cargo adk new my-agent --template tools

Ferramentas Integradas

ADK também inclui ferramentas prontas para uso:

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

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

---

Executando como um Servidor Web

Crie um projeto de servidor quando quiser servir HTTP:

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

O template básico padrão usa o iniciador de console leve para instalações mais rápidas.

---

Usando Outros Modelos

Ative provedores por meio de flags de recurso. A build padrão permanece apenas Gemini para instalações rápidas, então adicione somente o provedor de que você precisa:

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

Ou crie com um provedor: 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"))?;

Modelos Suportados

---

Próximos Passos

• LlmAgent Configuração — todas as opções de configuração
• Ferramentas de Função — crie ferramentas personalizadas com #[tool]
• Agentes de Workflow — pipelines sequenciais, paralelos e em loop
• Sessões — gerencie o estado da conversa
• Callbacks — personalize o comportamento do agente

---

Anterior: Introdução | Próximo: LlmAgent