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 OpenAI API para este passo a passo

Etapa 1: Estruture um servidor OpenAI

cargo install cargo-adk
cargo adk new quickstart_agent --template api --provider openai
cd quickstart_agent

Isso cria um projeto Rust completo com um agente OpenAI, sessões em memória, o runtime ADK HTTP, endpoints de streaming e a interface de desenvolvimento incorporada.

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 with the embedded runtime UI
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 modelos com complementos opcionais como docker, ci, telemetry e outros. Consulte a página Modelos composáveis para ver a lista completa de 9 complementos e 5 padrões empresariais.

Etapa 2: Adicione sua chave API

cp .env.example .env
# Open .env and replace the OPENAI_API_KEY placeholder.

O .gitignore gerado exclui .env. Mantenha a chave local e nunca faça commit dela.

Etapa 3: Execute o agente

cargo run

Abra http://127.0.0.1:8080/ui/. O agente aparece automaticamente; não é necessário criar uma sessão nem chamar um endpoint primeiro.

Etapa 4: Teste-o na interface de runtime

Insira um prompt como:

Explain what this agent can do in three concise Markdown bullets.

A resposta é transmitida para a conversa. Use o inspetor à direita para revisar a topologia de execução, a linha do tempo ordenada de eventos, as alterações de estado, os artefatos, as sessões, os recursos do protocolo e a telemetria sem sair da página.

Esta gravação usa a demonstração de equipe portátil para que a transferência animada seja fácil de visualizar. Seu agente criado pelo scaffold usa a mesma interface de runtime com uma topologia de um nó.

Verifique o runtime HTTP separadamente se quiser um teste rápido:

curl -fsS http://127.0.0.1:8080/api/health

Agora você tem um executável que executa o agente, gerencia sessões, transmite eventos e disponibiliza sua própria interface de teste. Não é necessária uma instalação separada de frontend.

Prefere um agente somente pelo terminal?

Use o modelo de console OpenAI:

cargo adk new quickstart_console --template openai
cd quickstart_console
cp .env.example .env   # replace the OPENAI_API_KEY placeholder
cargo run

---

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

Se você quer apenas executar rapidamente um agente sem usar scaffolding, use o comando de uma linha:

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 gerencia a detecção de provedores compilados, a criação de sessões, a construção do agente e a execução em uma única chamada. Ideal para scripts, protótipos e experimentos rápidos.

---

Entendendo o código gerado

O API do scaffold's src/main.rs cria um LlmAgent comum e, em seguida, o monta no servidor padrão. A configuração importante é:

use adk_rust::prelude::*;
use adk_rust::server::{ServerConfig, create_app};
use adk_rust::session::InMemorySessionService;
use std::sync::Arc;

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

    let model = adk_rust::model::openai::OpenAIClient::new(
        adk_rust::model::openai::OpenAIConfig::new(&api_key, "gpt-5.6-terra"),
    )?;

    let agent: Arc<dyn Agent> = Arc::new(
        LlmAgentBuilder::new("quickstart_agent")
            .description("REST API agent")
            .instruction("You are a helpful assistant accessible via REST API.")
            .model(Arc::new(model))
            .build()?,
    );

    let config = ServerConfig::new(
        Arc::new(adk_rust::SingleAgentLoader::new(agent)),
        Arc::new(InMemorySessionService::new()),
    );
    let app = create_app(config);

    let listener = tokio::net::TcpListener::bind("127.0.0.1:8080").await?;
    axum::serve(listener, app).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.1.0"
schemars = "1"
serde = { version = "1", features = ["derive"] }

Em seguida, defina uma ferramenta — o comentário da documentação se torna a descrição, e a estrutura 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 estrutura GetWeather que implementa Tool. Adicione-a ao seu agente:

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 básico com as 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 disponibilizar HTTP:

cargo adk new my-api --template api --provider openai
cd my-api
cp .env.example .env
cargo run

Abra http://127.0.0.1:8080/ui/. O modelo básico padrão usa, em vez disso, o inicializador leve do console.

---

Usando Outros Modelos

Habilite provedores por meio de sinalizadores de recursos. A compilação padrão permanece exclusiva para Gemini, para instalações rápidas; portanto, adicione apenas o provedor de que precisa:

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

Ou crie um projeto básico 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.6-terra"))?;

Anthropic

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

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::gpt_oss_120b(api_key))?;

Ollama (Local)

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

Modelos Compatíveis

---

Próximas etapas

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

---

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