Guia Rápido

Este guia mostra como começar a usar ADK-Rust. Você criará seu primeiro agente de IA em menos de 10 minutos.

Pré-requisitos

Antes de começar, certifique-se de ter:

• Rust 1.85.0 ou posterior (rustup update stable)
• Uma chave de API do Google para Gemini

Passo 1: Criar um Novo Projeto

Crie um novo projeto Rust:

cargo new my_agent
cd my_agent

A estrutura do seu projeto ficará assim:

my_agent/
├── Cargo.toml
├── src/
│   └── main.rs
└── .env          # Você criará este para sua chave de API

Passo 2: Adicionar Dependências

Atualize seu Cargo.toml com as dependências necessárias:

[package]
name = "my_agent"
version = "0.1.0"
edition = "2024"

[dependencies]
adk-rust = "0.2.0"
tokio = { version = "1.40", features = ["full"] }
dotenvy = "0.15"

Instale as dependências:

cargo build

Passo 3: Configurar Sua Chave de API

Este projeto usa a API do Gemini, que requer uma chave de API. Se você não tiver uma, crie uma chave no Google AI Studio.

Crie um arquivo .env na raiz do seu projeto:

Linux / macOS:

echo 'GOOGLE_API_KEY=your-api-key-here' > .env

Windows (PowerShell):

echo GOOGLE_API_KEY=your-api-key-here > .env

Dica de Segurança: Adicione .env ao seu .gitignore para evitar o commit da sua chave de API.

Passo 4: Escreva Seu Agente

Substitua o conteúdo de src/main.rs por:

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

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    // Carrega variáveis de ambiente do arquivo .env
    dotenvy::dotenv().ok();
    
    // Obtém a chave de API do ambiente
    let api_key = std::env::var("GOOGLE_API_KEY")
        .expect("GOOGLE_API_KEY environment variable not set");

    // Cria o modelo Gemini
    let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?;

    // Constrói seu agente
    let agent = LlmAgentBuilder::new("my_assistant")
        .description("A helpful AI assistant")
        .instruction("You are a friendly and helpful assistant. Answer questions clearly and concisely.")
        .model(Arc::new(model))
        .build()?;

    // Executa o agente com o launcher CLI
    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

Passo 5: Execute Seu Agente

Inicie seu agente no modo de console interativo:

cargo run

Você verá um prompt onde poderá conversar com seu agente:

🤖 Agente pronto! Digite suas perguntas (ou 'exit' para sair).

Você: Olá! Com o que você pode me ajudar?
Assistente: Olá! Eu sou um assistente de IA prestativo. Posso ajudar você com:
- Respondendo perguntas sobre vários tópicos
- Explicando conceitos
- Fornecendo informações e sugestões
- Tendo uma conversa amigável

O que você gostaria de saber?

Você: exit
👋 Adeus!

Passo 6: Adicionar uma Ferramenta

Vamos aprimorar seu agente com a ferramenta Google Search para dar-lhe acesso a informações em tempo real:

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

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    dotenvy::dotenv().ok();
    
    let api_key = std::env::var("GOOGLE_API_KEY")
        .expect("GOOGLE_API_KEY environment variable not set");

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

    // Build agent with Google Search tool
    let agent = LlmAgentBuilder::new("search_assistant")
        .description("An assistant that can search the web")
        .instruction("You are a helpful assistant. Use the search tool to find current information when needed.")
        .model(Arc::new(model))
        .tool(Arc::new(GoogleSearchTool::new()))  // Add search capability
        .build()?;

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

    Ok(())
}

Inicie seu agent novamente no modo console interativo:

cargo run

Agora você pode pedir ao seu agent para pesquisar na web:

Você: Como está o tempo em Tóquio hoje?
Assistant: Deixe-me procurar essa informação...
[Using GoogleSearchTool]
Com base nas informações atuais, Tóquio está com...

Executando como um Servidor Web

Para uma interface baseada na web, execute com o comando serve:

cargo run -- serve

Isso inicia o servidor na porta padrão 8080. Acesse-o em http://localhost:8080.

Para especificar uma porta personalizada:

cargo run -- serve --port 3000

Isso inicia o servidor na porta 3000. Acesse-o em http://localhost:3000.

Entendendo o Código

Vamos detalhar o que cada parte faz:

Imports

use adk_rust::prelude::*;  // GeminiModel, LlmAgentBuilder, Arc, etc.
use adk_rust::Launcher;    // CLI launcher for console/server modes
use std::sync::Arc;        // Thread-safe reference counting pointer

• prelude::* importa todos os tipos comumente usados: GeminiModel, LlmAgentBuilder, Arc, tipos de erro e mais
• Launcher fornece a interface CLI para executar agents
• Arc (Atomic Reference Counted) permite o compartilhamento seguro do model e do agent entre tarefas async

Criação do Modelo

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

Cria uma instância do GeminiModel que implementa o Llm trait. O model:

• Lida com a autenticação usando sua API key
• Gerencia as respostas de streaming do LLM
• Suporta function calling para Tools

Construção do Agente

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

O padrão builder configura seu agent:

Launcher

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

O Launcher gerencia o runtime:

• Modo Console (padrão): Chat interativo no seu terminal
• Modo Servidor (-- serve): REST API com interface web
• Gerencia o session state, streaming responses e o graceful shutdown

Usando Outros Modelos

adk-rust oferece suporte a múltiplos provedores LLM prontos para uso. Habilite-os via feature flags no seu Cargo.toml:

[dependencies]
adk-rust = { version = "0.2.0", features = ["openai", "anthropic", "deepseek", "groq", "ollama"] }

Defina a chave de API apropriada para o seu provedor:

# OpenAI
export OPENAI_API_KEY="your-api-key"

# Anthropic
export ANTHROPIC_API_KEY="your-api-key"

# DeepSeek
export DEEPSEEK_API_KEY="your-api-key"

# Groq
export GROQ_API_KEY="your-api-key"

# Ollama (nenhuma chave necessária, apenas execute: ollama serve)

OpenAI

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

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    dotenvy::dotenv().ok();

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

    let agent = LlmAgentBuilder::new("assistant")
        .instruction("You are a helpful assistant.")
        .model(Arc::new(model))
        .build()?;

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

    Ok(())
}

Anthropic

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

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    dotenvy::dotenv().ok();

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

    let agent = LlmAgentBuilder::new("assistant")
        .instruction("You are a helpful assistant.")
        .model(Arc::new(model))
        .build()?;

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

    Ok(())
}

DeepSeek

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

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    dotenvy::dotenv().ok();

    let api_key = std::env::var("DEEPSEEK_API_KEY")?;

    // Modelo de chat padrão
    let model = DeepSeekClient::chat(api_key)?;

    // Ou use reasoner para raciocínio de cadeia de pensamento
    // let model = DeepSeekClient::reasoner(api_key)?;

    let agent = LlmAgentBuilder::new("assistant")
        .instruction("You are a helpful assistant.")
        .model(Arc::new(model))
        .build()?;

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

    Ok(())
}

Groq (Inferência Ultrarrápida)

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

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    dotenvy::dotenv().ok();

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

    let agent = LlmAgentBuilder::new("assistant")
        .instruction("You are a helpful assistant.")
        .model(Arc::new(model))
        .build()?;

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

    Ok(())
}

Ollama (Modelos Locais)

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

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    dotenvy::dotenv().ok();

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

    let agent = LlmAgentBuilder::new("assistant")
        .instruction("You are a helpful assistant.")
        .model(Arc::new(model))
        .build()?;

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

    Ok(())
}

Modelos Suportados

Próximos Passos

Agora que você tem seu primeiro Agent em execução, explore estes tópicos:

• Configuração do LlmAgent - Todas as opções de configuração
• Function Tools - Crie ferramentas personalizadas
• Workflow Agents - Construa pipelines de várias etapas
• Sessions - Gerencie o estado da conversa
• Callbacks - Personalize o comportamento do Agent

---

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