Démarrage rapide

Créez votre premier agent d’IA en moins de 5 minutes.

Prérequis

• Rust 1.95.0 ou version ultérieure (rustup update stable)
• Une clé OpenAI API pour cette présentation

Étape 1 : Créer l’ossature d’un serveur OpenAI

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

Cela crée un projet Rust complet avec un agent OpenAI, des sessions en mémoire, le runtime ADK HTTP, des points de terminaison de diffusion en continu et l’interface de développement intégrée.

Autres modèles

# 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

Conseil : Utilisez l’option --addon pour composer des modèles avec des modules complémentaires facultatifs tels que docker, ci, telemetry, et bien d’autres. Consultez la page Modèles composables pour obtenir la liste complète des 9 modules complémentaires et des 5 modèles d’entreprise.

Étape 2 : Ajoutez votre clé API

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

Le .gitignore généré exclut .env. Conservez la clé en local et ne la validez jamais dans le dépôt.

Étape 3 : Exécutez l’agent

cargo run

Ouvrez http://127.0.0.1:8080/ui/. L’agent apparaît automatiquement ; vous n’avez pas besoin de créer une session ni d’appeler un point de terminaison au préalable.

Étape 4 : Testez-le dans l’interface utilisateur d’exécution

Saisissez une invite telle que :

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

La réponse s’affiche progressivement dans la conversation. Utilisez l’inspecteur à droite pour examiner la topologie d’exécution, la chronologie ordonnée des événements, les changements d’état, les artefacts, les sessions, les capacités du protocole et la télémétrie sans quitter la page.

Cet enregistrement utilise la démonstration d’équipe portable afin que le transfert animé soit facile à observer. Votre agent généré utilise la même interface utilisateur d’exécution avec une topologie à un nœud.

Vérifiez séparément l’exécution HTTP si vous souhaitez effectuer un test de bon fonctionnement :

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

Vous disposez maintenant d’un exécutable unique qui exécute l’agent, gère les sessions, diffuse les événements et fournit sa propre interface de test. Aucune installation frontend distincte n’est requise.

Vous préférez un agent utilisable uniquement depuis un terminal ?

Utilisez plutôt le modèle 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

---

Alternative sans configuration — adk::run()

Si vous souhaitez simplement exécuter rapidement un agent sans générer de structure, utilisez la commande en une ligne :

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

Cela gère la détection des fournisseurs compilés, la création de sessions, la construction de l’agent et son exécution en un seul appel. Idéal pour les scripts, les prototypes et les expérimentations rapides.

---

Comprendre le code généré

Le API du scaffold construit un LlmAgent ordinaire via src/main.rs, puis l’intègre au serveur standard. Le câblage important est le suivant :

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

---

Ajouter des outils personnalisés

La manière la plus rapide d’ajouter des outils consiste à utiliser la macro #[tool]. Ajoutez adk-tool à vos dépendances :

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

Définissez ensuite un outil — le commentaire de documentation devient la description, et la structure des arguments devient le schéma 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" }))
}

La macro génère une structure GetWeather qui implémente Tool. Ajoutez-la à votre 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()?;

Conseil : vous pouvez aussi créer un projet avec des outils déjà configurés : cargo adk new my-agent --template tools

Outils intégrés

ADK inclut également des outils prêts à l’emploi :

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

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

---

Exécuter en tant que serveur web

Créez un projet serveur lorsque vous souhaitez assurer le service de HTTP :

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

Ouvrez http://127.0.0.1:8080/ui/. Le modèle de base par défaut utilise plutôt le lanceur léger de la console.

---

Utiliser d’autres modèles

Activez les fournisseurs via des indicateurs de fonctionnalité. La compilation par défaut reste limitée à Gemini pour accélérer les installations ; ajoutez donc uniquement le fournisseur dont vous avez besoin :

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

Vous pouvez également créer un projet avec un fournisseur : 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"))?;

Modèles pris en charge

---

Étapes suivantes

• LlmAgent Configuration — toutes les options de configuration
• Outils de fonction — créer des outils personnalisés avec #[tool]
• Agents de workflow — pipelines séquentiels, parallèles et en boucle
• Sessions — gérer l’état de la conversation
• Rappels — personnaliser le comportement de l’agent

---

Précédent : Introduction | Suivant : LlmAgent