Outils intégrés

ADK-Rust fournit plusieurs outils intégrés qui étendent les capacités des agents sans nécessiter d’implémentation personnalisée. Ces outils sont prêts à l’emploi et s’intègrent parfaitement au framework d’agents.

Les outils natifs des fournisseurs sont désormais déclarés via le API Tool standard au lieu de blocs GenerateContentConfig.extensions spécifiques aux fournisseurs. Cela signifie que vous pouvez combiner des outils natifs tels que Gemini Google Search, Anthropic Web Search ou la recherche web Responses de OpenAI avec des instances FunctionTool ordinaires au sein du même agent.

Présentation

GoogleSearchTool

GoogleSearchTool permet aux agents d’effectuer des recherches sur le Web à l’aide de Google Search. Cet outil est géré en interne par les modèles Gemini via la fonctionnalité d’ancrage, ce qui signifie que la recherche est effectuée côté serveur par le modèle lui-même.

Utilisation de base

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

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("GOOGLE_API_KEY")?;
    let model = GeminiModel::new(&api_key, "gemini-3.7-flash")?;

    // Create the GoogleSearchTool
    let search_tool = GoogleSearchTool;

    // Add to agent
    let agent = LlmAgentBuilder::new("research_assistant")
        .description("An assistant that can search the web for information")
        .instruction(
            "You are a research assistant. When asked about current events, \
             recent news, or factual information, use the google_search tool \
             to find accurate, up-to-date information."
        )
        .model(Arc::new(model))
        .tool(Arc::new(search_tool))
        .build()?;

    println!("Agent created with Google Search capability!");
    Ok(())
}

Fonctionnement

Contrairement aux outils de fonction classiques, GoogleSearchTool fonctionne différemment :

1. Exécution côté serveur : la recherche est effectuée par la fonctionnalité d’ancrage de Gemini, et non localement
2. Invocation automatique : le modèle décide quand effectuer une recherche en fonction de la requête
3. Résultats intégrés : les résultats de recherche sont directement incorporés à la réponse du modèle

L’implémentation de l’outil renvoie une erreur s’il est appelé directement, car la recherche réelle s’effectue au sein de l’API Gemini :

// This is handled internally - you don't call it directly
async fn execute(&self, _ctx: Arc<dyn ToolContext>, _args: Value) -> Result<Value> {
    Err(AdkError::tool("GoogleSearch is handled internally by Gemini"))
}

Détails de l’outil

Cas d’utilisation

• Événements actuels : « Que s’est-il passé dans les actualités aujourd’hui ? »
• Requêtes factuelles : « Quelle est la population de Tokyo ? »
• Informations récentes : « Quelles sont les dernières avancées en IA ? »
• Tâches de recherche : « Trouver des informations sur les tendances des énergies renouvelables »

Exemples de requêtes

// The agent will automatically use Google Search for queries like:
// - "What's the weather forecast for New York this week?"
// - "Who won the latest championship game?"
// - "What are the current stock prices for tech companies?"

AgentTool

AgentTool encapsule n’importe quel agent comme un outil appelable, permettant une composition de délégation-et-retour : l’appelant invoque un enfant, reçoit son résultat, puis reprend son exécution. Les deltas d’état et d’artefacts émis par l’enfant sont fusionnés dans l’événement de l’outil parent. La session enfant applique également chaque événement immédiatement, de sorte que les étapes ultérieures d’un workflow délégué voient les modifications précédentes de l’état et de l’historique.

Les valeurs par défaut héritées restent isolées et rétrocompatibles. Les équipes portables activent explicitement les instantanés de l’historique et de l’état du parent, la transmission de la mémoire, la propagation des échecs, une profondeur de délégation finie, des projections exactes de l’état et de l’historique, ainsi que l’exécution interne des transferts entre enfants enregistrés. Un transfert entre enfants consommé reste visible comme événement, mais son action de transfert est supprimée avant la transmission, afin que le Runner parent ne puisse pas l’exécuter deux fois. Les métadonnées de requête, l’annulation, les portées, les secrets, les artefacts et l’état partagé parallèle suivent la politique de transmission configurée. AgentTool lui-même n’exécute pas la boucle globale de transfert du Runner ; un TeamSpec compilé fournit le registre exact des transferts imbriqués pour les topologies mixtes. Les équipes compilées activent également la transmission des événements imbriqués afin que l’activité déléguée reste visible dans le flux d’événements parent ; le AgentTool autonome conserve la sortie d’événements héritée, sauf si forward_events(true) est sélectionné.

Pour une réécriture contrôlée, utilisez output_state_keys indépendamment de la projection d’entrée state_keys. state_merge_policy(RejectConflicts) compare la valeur actuelle du parent à l’instantané pris au début de la délégation et rejette atomiquement les écritures en conflit. artifact_prefixes applique le même principe de liste blanche aux noms d’artefacts. Les valeurs par défaut autonomes conservent la règle du dernier écrivain gagnant, avec une sortie sans restriction pour assurer la rétrocompatibilité ; les équipes compilées choisissent explicitement leur politique exacte pour chaque arête.

Utilisation de base

use adk_rust::prelude::*;
use adk_tool::AgentTool;
use std::sync::Arc;

let sub_agent = LlmAgentBuilder::new("summarizer")
    .description("Summarizes text content")
    .instruction("Summarize the provided text concisely.")
    .model(model.clone())
    .build()?;

let agent_tool = AgentTool::new(Arc::new(sub_agent));

let coordinator = LlmAgentBuilder::new("coordinator")
    .instruction("Use the summarizer tool when asked to summarize content.")
    .model(model.clone())
    .tool(Arc::new(agent_tool))
    .build()?;

Fonctionnement

1. L’agent parent décide d’appeler l’agent encapsulé en tant qu’outil
2. AgentTool crée un contexte d’invocation avec StreamingMode::None
3. Le sous-agent s’exécute jusqu’à son terme et accumule l’intégralité de sa réponse
4. Le texte de la réponse est renvoyé à l’agent parent
5. Les deltas d’état et les deltas d’artefacts sont transmis au contexte parent

Détails de l’outil

Comportement clé

• Les sous-agents s’exécutent en interne en mode non streaming afin de capturer les réponses de manière fiable
• Les modifications d’état (output_key) du sous-agent sont propagées à la session parente
• Les artefacts enregistrés par le sous-agent sont transmis au contexte parent
• Consultez Systèmes multi-agents pour en savoir plus sur les modèles de composition d’agents

ExitLoopTool

ExitLoopTool est un outil de contrôle utilisé avec LoopAgent pour signaler quand un processus itératif doit se terminer. Lorsqu’il est appelé, il définit l’indicateur escalate, ce qui provoque la sortie de la boucle.

Utilisation de base

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

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("GOOGLE_API_KEY")?;
    let model = GeminiModel::new(&api_key, "gemini-3.7-flash")?;

    // Create an agent with ExitLoopTool for iterative refinement
    let refiner = LlmAgentBuilder::new("content_refiner")
        .description("Iteratively improves content quality")
        .instruction(
            "Review the content and improve it. Check for:\n\
             1. Clarity and readability\n\
             2. Grammar and spelling\n\
             3. Logical flow\n\n\
             If the content meets all quality standards, call the exit_loop tool.\n\
             Otherwise, provide an improved version."
        )
        .model(Arc::new(model))
        .tool(Arc::new(ExitLoopTool::new()))
        .build()?;

    // Use in a LoopAgent
    let loop_agent = LoopAgent::new(
        "iterative_refiner",
        vec![Arc::new(refiner)],
    ).with_max_iterations(5);

    println!("Loop agent created with exit capability!");
    Ok(())
}

Fonctionnement

1. L’agent évalue s’il doit continuer ou quitter
2. Lorsqu’il est prêt à quitter, l’agent appelle exit_loop
3. L’outil définit actions.escalate = true et actions.skip_summarization = true
4. LoopAgent détecte l’indicateur d’escalade et arrête les itérations

Détails de l’outil

Bonnes pratiques

1. Critères de sortie clairs : Définissez des conditions spécifiques dans l’instruction de l’agent
2. Définissez toujours max_iterations : Prévenez les boucles infinies par mesure de sécurité
3. Instructions pertinentes : Aidez l’agent à comprendre quand quitter

// Good: Clear exit criteria
.instruction(
    "Improve the text until it:\n\
     - Has no grammatical errors\n\
     - Is under 100 words\n\
     - Uses active voice\n\
     When all criteria are met, call exit_loop."
)

// Avoid: Vague criteria
.instruction("Improve the text. Exit when done.")

LoadArtifactsTool

LoadArtifactsTool permet aux agents de récupérer des artefacts enregistrés par leur nom. Cela est utile lorsque les agents doivent accéder à des fichiers, des images ou d’autres données binaires précédemment enregistrées.

Utilisation de base

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

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("GOOGLE_API_KEY")?;
    let model = GeminiModel::new(&api_key, "gemini-3.7-flash")?;

    // Create agent with artifact loading capability
    let agent = LlmAgentBuilder::new("document_analyzer")
        .description("Analyzes stored documents")
        .instruction(
            "You can load and analyze stored artifacts. \
             Use the load_artifacts tool to retrieve documents by name. \
             The tool accepts an array of artifact names."
        )
        .model(Arc::new(model))
        .tool(Arc::new(LoadArtifactsTool::new()))
        .build()?;

    println!("Agent created with artifact loading capability!");
    Ok(())
}

Détails de l’outil

Paramètres

L’outil attend un objet JSON avec un tableau artifact_names :

{
  "artifact_names": ["document.txt", "image.png", "data.json"]
}

Format de réponse

L’outil renvoie un objet contenant les artefacts chargés :

{
  "artifacts": [
    {
      "name": "document.txt",
      "content": "The text content of the document..."
    },
    {
      "name": "image.png",
      "content": {
        "mime_type": "image/png",
        "data": "base64-encoded-data..."
      }
    },
    {
      "name": "missing.txt",
      "error": "Artifact not found"
    }
  ]
}

Exigences

Pour que LoadArtifactsTool fonctionne, vous avez besoin de :

1. Un ArtifactService configuré dans le runner
2. Des artefacts précédemment enregistrés auprès du service
3. L’outil ajouté à l’agent

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

// Set up artifact service
let artifact_service = Arc::new(InMemoryArtifactService::new());

// Configure runner with artifact service
let runner = Runner::new(agent)
    .with_artifact_service(artifact_service);

Combinaison d’outils intégrés

Vous pouvez utiliser plusieurs outils intégrés ensemble :

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

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("GOOGLE_API_KEY")?;
    let model = GeminiModel::new(&api_key, "gemini-3.7-flash")?;

    // Create agent with multiple built-in tools
    let agent = LlmAgentBuilder::new("research_agent")
        .description("Research agent with search and artifact capabilities")
        .instruction(
            "You are a research agent. You can:\n\
             - Search the web using google_search for current information\n\
             - Load stored documents using load_artifacts\n\
             Use these tools to help answer questions comprehensively."
        )
        .model(Arc::new(model))
        .tool(Arc::new(GoogleSearchTool))
        .tool(Arc::new(LoadArtifactsTool::new()))
        .build()?;

    println!("Multi-tool agent created!");
    Ok(())
}

Création d’outils intégrés personnalisés

Vous pouvez créer vos propres outils en suivant le même modèle que les outils intégrés, en implémentant le trait Tool :

use adk_rust::prelude::*;
use async_trait::async_trait;
use serde_json::{json, Value};
use std::sync::Arc;

pub struct MyCustomTool;

impl MyCustomTool {
    pub fn new() -> Self {
        Self
    }
}

#[async_trait]
impl Tool for MyCustomTool {
    fn name(&self) -> &str {
        "my_custom_tool"
    }

    fn description(&self) -> &str {
        "Description of what this tool does"
    }

    async fn execute(&self, ctx: Arc<dyn ToolContext>, args: Value) -> Result<Value> {
        // Your tool logic here
        Ok(json!({ "result": "success" }))
    }
}

Référence API

GoogleSearchTool

impl GoogleSearchTool {
    /// Create a new GoogleSearchTool instance
    pub fn new() -> Self;
}

ExitLoopTool

impl ExitLoopTool {
    /// Create a new ExitLoopTool instance
    pub fn new() -> Self;
}

LoadArtifactsTool

impl LoadArtifactsTool {
    /// Create a new LoadArtifactsTool instance
    pub fn new() -> Self;
}

impl Default for LoadArtifactsTool {
    fn default() -> Self;
}

Voir aussi

• Outils de fonctions - Créer des outils de fonctions personnalisés
• Outils MCP - Utiliser des serveurs MCP comme fournisseurs d’outils
• Agents de workflow - Utiliser ExitLoopTool avec LoopAgent
• Artefacts - Gérer des données binaires avec des artefacts

---

Précédent : ← Outils de fonctions | Suivant : Outils de navigateur →