Agent-Computer Interface (ACI) : Concevoir des Outils pour les Agents IA

Qu'est-ce que l'Agent-Computer Interface (ACI) ?

Pendant des décennies, le HCI (Human-Computer Interface) a guidé la conception d'interfaces pour les humains : boutons bien placés, feedback visuel, navigation intuitive. Aujourd'hui, les agents IA interagissent avec les systèmes informatiques via des outils (fonctions, API, commandes). Ils ont besoin de leur propre discipline de design.

L'ACI (Agent-Computer Interface) est l'ensemble des principes et pratiques pour concevoir des interfaces que les agents IA peuvent utiliser efficacement. C'est le HCI des agents.

Pourquoi l'ACI est crucial

Un agent IA ne « voit » pas vos interfaces graphiques. Il lit des descriptions textuelles d'outils et décide lequel appeler avec quels paramètres. La qualité de cette interface textuelle détermine directement les performances de l'agent.

La dernière ligne est cruciale : un humain peut explorer une interface, cliquer partout, lire un tutoriel. Un agent doit comprendre l'outil et l'utiliser correctement dès la première tentative. Cela impose un standard de clarté beaucoup plus élevé.

Les 5 Principes Fondamentaux du Design ACI

Principe 1 : Simplicité — Un outil, une action

Chaque outil doit faire une seule chose et la faire bien. C'est le principe UNIX appliqué aux agents.

❌ Mauvais design :

# Un outil fourre-tout qui fait tout
tools = [{
    "name": "manage_database",
    "description": "Gère la base de données : créer, lire, mettre à jour, supprimer des enregistrements, créer des tables, modifier le schéma, exporter des données",
    "input_schema": {
        "type": "object",
        "properties": {
            "action": {"type": "string", "enum": ["create", "read", "update", "delete", "create_table", "alter_table", "export"]},
            "table": {"type": "string"},
            "data": {"type": "object"},
            "query": {"type": "string"},
            "format": {"type": "string"}
        }
    }
}]

✅ Bon design :

# Des outils atomiques et ciblés
tools = [
    {
        "name": "find_records",
        "description": "Recherche des enregistrements dans une table selon des critères de filtrage. Retourne une liste d'objets correspondants, triés par date de création décroissante. Maximum 100 résultats par appel.",
        "input_schema": {
            "type": "object",
            "properties": {
                "table": {
                    "type": "string",
                    "description": "Nom de la table. Tables disponibles : users, orders, products, reviews.",
                    "enum": ["users", "orders", "products", "reviews"]
                },
                "filters": {
                    "type": "object",
                    "description": "Paires clé-valeur pour filtrer. Ex: {\"status\": \"active\", \"country\": \"FR\"}"
                },
                "limit": {
                    "type": "integer",
                    "description": "Nombre max de résultats (1-100). Défaut : 20.",
                    "default": 20
                }
            },
            "required": ["table"]
        }
    },
    {
        "name": "update_record",
        "description": "Met à jour un enregistrement existant identifié par son ID. Retourne l'enregistrement mis à jour avec ses nouvelles valeurs.",
        "input_schema": {
            "type": "object",
            "properties": {
                "table": {
                    "type": "string",
                    "enum": ["users", "orders", "products", "reviews"]
                },
                "record_id": {
                    "type": "string",
                    "description": "L'identifiant unique de l'enregistrement à modifier."
                },
                "updates": {
                    "type": "object",
                    "description": "Champs à modifier avec leurs nouvelles valeurs. Ex: {\"status\": \"shipped\", \"tracking_id\": \"ABC123\"}"
                }
            },
            "required": ["table", "record_id", "updates"]
        }
    }
]

Principe 2 : Clarté — Des descriptions qui ne laissent aucun doute

La description d'un outil est la seule documentation que l'agent voit. Elle doit répondre à ces questions :

1. →Que fait l'outil ? (première phrase, action claire)
2. →Quand l'utiliser ? (cas d'usage principaux)
3. →Que retourne-t-il ? (format de la réponse)
4. →Quelles sont les limites ? (edge cases, quotas)

# ✅ Description exemplaire
{
    "name": "search_customers",
    "description": (
        "Recherche des clients par nom, email ou identifiant. "
        "Utiliser cet outil quand l'utilisateur demande des informations sur un client spécifique. "
        "Retourne une liste de clients correspondants avec leurs informations de contact et historique d'achats récent. "
        "La recherche est insensible à la casse et supporte les correspondances partielles pour le nom et l'email. "
        "Retourne un maximum de 10 résultats. Si aucun client trouvé, retourne une liste vide."
    )
}

Principe 3 : Prévisibilité — Comportement cohérent

Les outils doivent suivre des conventions cohérentes : nommage, format de retour, gestion d'erreurs. L'agent apprend ces patterns et les généralise.

# ✅ Conventions cohérentes sur tous les outils
# - Nommage : verbe_nom (find_orders, create_invoice, update_customer)
# - Retour : toujours { "success": bool, "data": ..., "error": str|null }
# - Erreurs : toujours { "success": false, "error": "message descriptif", "suggestion": "..." }

Principe 4 : Récupérabilité — Erreurs informatives

Quand un outil échoue, le message d'erreur doit aider l'agent à se corriger.

# ❌ Erreur inutile
{"error": "Invalid input"}

# ✅ Erreur exploitable par un agent
{
    "success": False,
    "error": "Le champ 'date_start' a un format invalide : '2026-13-01'. Le mois doit être entre 01 et 12.",
    "suggestion": "Utilisez le format YYYY-MM-DD avec un mois valide. Exemple : '2026-03-01'.",
    "received": "2026-13-01",
    "expected_format": "YYYY-MM-DD"
}

Principe 5 : Composabilité — Des outils qui fonctionnent ensemble

Les sorties d'un outil doivent pouvoir servir d'entrées à un autre, sans transformation manuelle.

# L'agent peut chaîner naturellement :
# 1. find_customer(email="alice@example.com") → retourne customer_id
# 2. get_orders(customer_id="cust_123") → retourne liste de commandes
# 3. get_order_details(order_id="ord_456") → retourne détails

Bonnes Pratiques pour les Descriptions d'Outils

La description d'un outil est le point de contact unique entre l'agent et la fonctionnalité. Voici les éléments à systématiquement inclure.

Template de description d'outil

{
    "name": "verbe_nom",
    "description": (
        "[Action principale en une phrase.] "
        "[Quand utiliser cet outil.] "
        "[Ce que retourne l'outil — format et structure.] "
        "[Limites, quotas, edge cases.] "
        "[Quand NE PAS utiliser cet outil — rediriger vers le bon outil.]"
    )
}

Design des Paramètres : Réduire la Charge Cognitive

Les paramètres sont le langage par lequel l'agent communique avec l'outil. Chaque décision de design impacte la fiabilité de l'agent.

Règle 1 : Enums plutôt que texte libre

# ❌ L'agent peut générer n'importe quoi
"status": {"type": "string", "description": "Le statut de la commande"}

# ✅ L'agent choisit parmi des options valides
"status": {
    "type": "string",
    "description": "Statut de la commande à filtrer.",
    "enum": ["pending", "confirmed", "shipped", "delivered", "cancelled"]
}

Règle 2 : Valeurs par défaut sensées

# ✅ L'agent n'a pas besoin de spécifier tous les paramètres
"limit": {
    "type": "integer",
    "description": "Nombre de résultats à retourner (1-100). Défaut : 20.",
    "default": 20
},
"sort_by": {
    "type": "string",
    "description": "Champ de tri. Défaut : 'created_at'.",
    "default": "created_at",
    "enum": ["created_at", "updated_at", "name", "amount"]
}

Règle 3 : Formats explicites

# ❌ Ambigu
"date": {"type": "string", "description": "La date"}

# ✅ Format spécifié avec exemple
"date": {
    "type": "string",
    "description": "Date au format ISO 8601 (YYYY-MM-DD). Ex: '2026-03-19'."
}

Règle 4 : Minimiser les paramètres requis

Ne rendez obligatoire que ce qui est strictement nécessaire. Tout le reste devrait avoir une valeur par défaut.

# ✅ Un seul paramètre requis, le reste est optionnel avec des défauts
"required": ["query"],
"properties": {
    "query": {"type": "string", "description": "Texte de recherche."},
    "category": {"type": "string", "enum": [...], "description": "Filtrer par catégorie. Défaut : toutes."},
    "limit": {"type": "integer", "default": 10},
    "include_archived": {"type": "boolean", "default": False}
}

Gestion d'Erreurs pour les Agents

Les messages d'erreur sont un canal de communication critique avec l'agent. Contrairement à un humain qui peut interpréter un code d'erreur vague, un agent a besoin d'informations structurées pour se corriger.

Les 4 composantes d'un bon message d'erreur ACI

{
    "success": False,
    "error": {
        # 1. Quoi : description claire du problème
        "message": "Le client avec l'ID 'cust_999' n'existe pas.",
        
        # 2. Pourquoi : contexte sur la cause
        "reason": "L'identifiant ne correspond à aucun enregistrement dans la base clients.",
        
        # 3. Comment corriger : suggestion actionnable
        "suggestion": "Vérifiez l'identifiant. Utilisez search_customers pour trouver le bon ID.",
        
        # 4. Contexte : données utiles pour le prochain appel
        "context": {
            "received_id": "cust_999",
            "similar_ids": ["cust_099", "cust_990"]
        }
    }
}

Anti-patterns de gestion d'erreurs

# ❌ Erreurs inutiles pour un agent
"Error 500: Internal Server Error"
"Something went wrong"
"Invalid request"
"null"

# ✅ Erreurs exploitables
"Le paramètre 'email' est requis mais n'a pas été fourni. Ajoutez un email valide au format user@domain.com."
"Le montant 150.00 dépasse la limite de remboursement de 100.00 pour cette commande. Le montant maximum remboursable est 100.00."
"Aucun produit trouvé avec le filtre category='electronics'. Catégories disponibles : books, clothing, home, food."

Patterns de Composition d'Outils

Quand combiner vs séparer les outils

Exemple : pipeline de composition

import anthropic

client = anthropic.Anthropic()

# L'agent résout "Rembourse la dernière commande d'Alice" en 3 appels :
# Étape 1 : trouver le client
# Étape 2 : obtenir sa dernière commande
# Étape 3 : effectuer le remboursement

tools = [
    {
        "name": "search_customers",
        "description": "Recherche des clients par nom ou email. Retourne une liste de clients avec leur ID, nom et email.",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "Nom ou email du client à rechercher."
                }
            },
            "required": ["query"]
        }
    },
    {
        "name": "get_recent_orders",
        "description": "Récupère les commandes récentes d'un client. Retourne les commandes triées par date décroissante avec id, date, montant, statut.",
        "input_schema": {
            "type": "object",
            "properties": {
                "customer_id": {
                    "type": "string",
                    "description": "L'identifiant unique du client (format: cust_XXX)."
                },
                "limit": {
                    "type": "integer",
                    "description": "Nombre de commandes à retourner. Défaut : 5.",
                    "default": 5
                }
            },
            "required": ["customer_id"]
        }
    },
    {
        "name": "create_refund",
        "description": "Crée un remboursement pour une commande. Le remboursement est traité sous 3-5 jours ouvrés. Retourne l'ID du remboursement et le montant remboursé.",
        "input_schema": {
            "type": "object",
            "properties": {
                "order_id": {
                    "type": "string",
                    "description": "L'identifiant de la commande à rembourser (format: ord_XXX)."
                },
                "reason": {
                    "type": "string",
                    "description": "Motif du remboursement.",
                    "enum": ["customer_request", "defective_product", "wrong_item", "late_delivery"]
                }
            },
            "required": ["order_id", "reason"]
        }
    }
]

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "Rembourse la dernière commande d'Alice, elle a demandé un remboursement."}]
)

Étude de Cas : Transformer une API REST en Outils Agent-Friendly

Tester Vos Outils avec un Agent

L'évaluation est la boucle de feedback du design ACI. Sans tests systématiques, vous optimisez à l'aveugle.

Les 3 niveaux de test

import anthropic

client = anthropic.Anthropic()

def test_tool_selection(prompt: str, expected_tool: str, tools: list) -> bool:
    """Teste si l'agent sélectionne le bon outil pour un prompt donné."""
    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=512,
        tools=tools,
        messages=[{"role": "user", "content": prompt}]
    )
    
    tool_calls = [block for block in response.content if block.type == "tool_use"]
    if not tool_calls:
        return False
    
    return tool_calls[0].name == expected_tool


# Suite de tests de sélection
selection_tests = [
    ("Trouve le client Pierre Martin", "search_customers"),
    ("Quelle est la dernière commande de cust_123 ?", "get_recent_orders"),
    ("Rembourse la commande ord_456", "create_refund"),
    ("Où en est la livraison de ma commande ?", "get_shipping_status"),
]

for prompt, expected in selection_tests:
    result = test_tool_selection(prompt, expected, tools)
    status = "✅" if result else "❌"
    print(f"{status} '{prompt}' → attendu: {expected}")

Métriques clés à suivre

• →Taux de sélection correcte : % de fois où l'agent choisit le bon outil (cible : > 95%)
• →Taux de paramètres valides : % de paramètres syntaxiquement et sémantiquement corrects (cible : > 93%)
• →Taux de résolution : % de tâches complètes résolues avec succès (cible : > 90%)
• →Nombre moyen d'appels : appels d'outils nécessaires par tâche (moins = mieux)

Checklist de Design ACI

Avant de mettre un outil en production pour un agent, vérifiez chaque point :

Nommage

• → Nom au format verbe_nom (action claire)
• → Nom cohérent avec les autres outils du même ensemble
• → Pas d'abréviations ambiguës

Description

• → Première phrase = action principale
• → Cas d'usage précisé (quand utiliser)
• → Format de retour documenté
• → Limites et quotas mentionnés
• → Redirection vers d'autres outils si pertinent

Paramètres

• → Enums plutôt que texte libre quand possible
• → Valeurs par défaut pour les paramètres optionnels
• → Formats spécifiés avec exemples
• → Minimum de paramètres requis

Erreurs

• → Messages d'erreur descriptifs (quoi, pourquoi, comment corriger)
• → Suggestions actionnables
• → Données contextuelles (valeurs valides, IDs similaires)

Tests

• → Tests de sélection sur > 20 prompts variés
• → Tests de paramètres sur les edge cases
• → Tests end-to-end sur des scénarios réels

En Résumé

L'ACI est une discipline émergente mais essentielle. Les agents IA ne fonctionnent qu'aussi bien que les outils qu'on leur donne. En appliquant les 5 principes (simplicité, clarté, prévisibilité, récupérabilité, composabilité), en soignant vos descriptions et en testant itérativement, vous transformez des API médiocres en interfaces que vos agents utilisent avec fiabilité.

Le passage de 47 endpoints REST à 12 outils bien conçus n'est pas une simplification — c'est un changement de paradigme : on passe d'une interface orientée développeur à une interface orientée agent.

Pour approfondir l'utilisation des outils avec Claude, consultez notre guide du Tool Use. Pour les patterns d'architecture d'agents, voir notre article sur les architectures d'agents Claude. Et pour le protocole MCP qui standardise la communication agent-outil, explorez nos patterns MCP avancés.

Questions Fréquentes

Quelle est la différence entre HCI et ACI ?

HCI (Human-Computer Interface) optimise les interactions pour les humains : visuels, clics, retours intuitifs. ACI (Agent-Computer Interface) optimise pour les agents IA : descriptions textuelles claires, paramètres non ambigus, messages d'erreur exploitables, et opérations atomiques. Un bon HCI ne garantit pas un bon ACI.

Combien d'outils un agent devrait-il avoir à disposition ?

Il n'y a pas de nombre magique, mais le principe est : le minimum nécessaire avec le maximum de clarté. Dans la pratique, 8 à 15 outils bien conçus couvrent la plupart des cas. Au-delà de 20 outils, la performance de sélection de l'agent se dégrade significativement.

Faut-il découper un outil complexe en plusieurs outils simples ?

Oui, dans la majorité des cas. Un outil qui fait une seule chose bien est préférable à un outil multi-usage avec des paramètres conditionnels. L'exception : quand les actions sont toujours exécutées ensemble et que les séparer créerait des problèmes de cohérence.

Comment tester si mes outils sont bien conçus pour un agent ?

Trois méthodes complémentaires : 1) tests de sélection (l'agent choisit-il le bon outil pour la tâche ?), 2) tests de paramètres (l'agent remplit-il correctement les paramètres ?), 3) tests end-to-end (l'agent accomplit-il la tâche complète ?). Mesurez le taux de réussite sur un jeu de scénarios représentatifs.