Notes pratiques : Ingénierie des harnais : L’agent nu : Pourquoi votre framework vous contrôle

Utilisez ceci comme une version révisée destinée aux opérateurs des idées présentées dans « Harness Engineering: The Naked Agent: Why Your Framework Hands You a Loop, Not a Harness — I » : étapes claires, emplacements de code ordonnés et notes de récupération qui survivent au transfert.

Partie 1 : Un cycle d’agent simplifié semble puissant jusqu’à ce que du trafic réel le sollicite. Voici pourquoi les pannes en production proviennent généralement du manque de mécanisme de gestion autour du modèle, et non du modèle lui-même.

Dans la Partie 1, une étape simplifiée fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un enregistrement exemplaire, un cas de panne et la note de réversion avant d’élargir le périmètre. Documentez ensemble le parcours normal et le parcours de récupération. Les tentatives de réessai, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’améliorations ultérieures. Prévoyez un budget de tokens par tour et par session. Les outils agents élargissent fortement le contexte ; des plafonds stricts empêchent que les démonstrations ne se transforment en factures inattendues.

La plupart des échecs des agents ne sont pas imputables au modèle. Ils proviennent de l’absence d’une couche disciplinaire autour de celui-ci. Voici à quoi ressemble un agent IA sans mécanismes de contrôle dans le Claude Agent SDK et LangChain Deep Agents, ainsi que les trois manières spécifiques dont il échoue sous une charge réelle.

Il est préférable de considérer la plupart des échecs des agents comme une surface mesurable. Capturez un enregistrement exemplaire, un cas d’échec et des notes de correction avant d’élargir le périmètre. Préférez des unités petites et testables plutôt que des scripts complexes. Lorsqu’une étape échoue, l’erreur doit indiquer une seule responsabilité et non un processus embrouillé. Fixez des limites de tokens par tour et par session. Les outils d’agents élargissent agressivement le contexte ; des plafonds stricts empêchent que les démonstrations se transforment en factures inattendues.

Le modèle n’est pas la variable

Le modèle fonctionne le mieux lorsqu’il est considéré comme une surface mesurable. Capturez un exemple réussi, un cas d’échec et la note de réversion avant d’élargir le périmètre. Considérez cette étape comme un contrat entre les entrées et les sorties validées. Nommez les artefacts, définites des critères de succès et refusez toute mise en œuvre partielle silencieuse. Fixez un budget de tokens par tour et par session. Les outils agents élargissent lourdement le contexte ; des plafonds stricts empêchent que les démonstrations se transforment en factures inattendues.

Que signifie réellement « nu »

Le concept de « surface mesurable » fonctionne le mieux lorsque l’on traite le stage What naked comme une telle. Capturez un exemple réussi, un cas d’échec ainsi que la note de réversion avant d’élargir le périmètre. Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe d’une démonstration à des environnements partagés. Mettez à disposition des outils dotés de schémas restreints et de labels explicites indiquant les effets secondaires. Les hôtes doivent savoir quels appels modifient l’état avant d’approuver automatiquement.

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY
TOOLS = [
    {"name": "search_flights",
     "description": "Search flights between two cities for a date.",
     "input_schema": {"type": "object", "properties": {
         "origin": {"type": "string"}, "destination": {"type": "string"},
         "date": {"type": "string", "description": "YYYY-MM-DD"}},
         "required": ["origin", "destination", "date"]}},
    {"name": "book_flight",
     "description": "Book a specific flight.",
     "input_schema": {"type": "object", "properties": {
         "flight_id": {"type": "string"}, "passenger_name": {"type": "string"}},
         "required": ["flight_id", "passenger_name"]}},
]
def run_naked(user_msg: str) -> str:
    messages = [{"role": "user", "content": user_msg}]
    while True:                                   # ① no iteration cap
        resp = client.messages.create(
            model="claude-sonnet-4-6", max_tokens=1024,
            tools=TOOLS, messages=messages,
        )
        if resp.stop_reason != "tool_use":
            return resp.content[0].text
        call = next(b for b in resp.content if b.type == "tool_use")
        result = dispatch(call.name, call.input)
                                             # ② direct side effect, no check
        messages.extend([
                                             # ③ whole history, every turn
            {"role": "assistant", "content": resp.content},
            {"role": "user", "content": [{"type": "tool_result",
                "tool_use_id": call.id, "content": result}]},
        ])

L’agent naked dans le Claude Agent SDK

L’agent nu en phase de test fonctionne le mieux lorsqu’il est considéré comme une surface mesurable. Capturez un enregistrement idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre. Conservez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les indicateurs fonctionnels doivent être regroupés en un seul endroit que les opérateurs peuvent auditer sans devoir lire l’ensemble du système. Exposez des outils dotés de schémas restreints et de labels explicites indiquant les effets secondaires. Les hôtes doivent savoir quels appels modifient l’état avant de valider automatiquement. L’agent nu en phase de test fonctionne le mieux lorsqu’il est considéré comme une surface mesurable. Capturez un enregistrement idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre. Préférez des unités petites et testables aux scripts complexes. Lorsqu’une étape échoue, l’échec doit pointer vers une seule responsabilité plutôt que vers un processus embrouillé.

import asyncio
from claude_agent_sdk import (
    query, ClaudeAgentOptions, tool,
    create_sdk_mcp_server, AssistantMessage, ResultMessage,
)

@tool("search_flights", "Search flights between two cities for a date.",
      {"origin": str, "destination": str, "date": str})
async def search_flights(args):
                                              # ① no check that date exists
    hits = flights_api.search(**args)
    return {"content": [{"type": "text", "text": str(hits)}]}
@tool("book_flight", "Book a specific flight.",
      {"flight_id": str, "passenger_name": str})
async def book_flight(args):
                                               # ② destructive, ungated
    confirmation = flights_api.book(**args)
    return {"content": [{"type": "text", "text": confirmation}]}
server = create_sdk_mcp_server("travel", tools=[search_flights, book_flight])
async def main():
    options = ClaudeAgentOptions(
        mcp_servers={"travel": server},
        allowed_tools=["mcp__travel__search_flights",
                       "mcp__travel__book_flight"],
    )
    async for msg in query(prompt="Rebook this customer for March 32nd.",
                           options=options):
        if isinstance(msg, AssistantMessage):
            for b in msg.content:
                if hasattr(b, "text"):
                    print(b.text)
        elif isinstance(msg, ResultMessage):
            print("done:", msg.subtype)
                                              # ③ no state survives this run

L’agent nu dans LangChain Deep Agents

Pour l’agent nu en phase d’exécution, définissez les entrées, le responsable de l’étape et les critères de fin avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Considérez cette phase comme un contrat entre les entrées et les sorties validées. Nommez les artefacts, définissez des vérifications de succès et refusez toute exécution partielle silencieuse. Authentifiez-vous au niveau du gateway et réautorisez-vous au niveau du plan de données. Un token porteur seul ne constitue pas une frontière entre les tenants.

from langchain.tools import tool
from deepagents import create_deep_agent

@tool
def search_flights(origin: str, destination: str, date: str) -> str:
    """Search flights between two cities for a date (YYYY-MM-DD)."""
    return str(flights_api.search(origin, destination, date))
                                                # ① no date check
@tool
def book_flight(flight_id: str, passenger_name: str) -> str:
    """Book a specific flight."""
    return flights_api.book(flight_id, passenger_name)
                                                 # ② ungated side effect
agent = create_deep_agent(
                                                 # ③ the loop, no controls
    model="anthropic:claude-sonnet-4-6",
    tools=[search_flights, book_flight],
)
result = agent.invoke({"messages": [{"role": "user",
    "content": "Rebook this customer for March 32nd."}]})
print(result["messages"][-1].content)
# Ask a follow-up in a second invoke, and it starts from zero: no thread,
# no memory.

Voyez comment cela peut échouer de trois manières

Pour surveiller le processus, divisez-le en trois étapes : définissez les entrées, le responsable de chaque étape ainsi que les critères d’arrêt avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu, sans avoir à deviner l’état caché. Enregistrez les temps d’exécution ainsi que le coût des jetons ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe d’un environnement de démonstration à des environnements partagés. Authentifiez-vous au niveau du gateway et réautorisez-vous au niveau du plan de données. Un simple jeton porteur ne constitue pas une frontière entre les tenants.

Faute 1 : un argument mal formaté parvient à une fonction destructrice

Pour le cas de défaillance 1 lié à une étape mal formatée, il convient de définir les entrées, le responsable de l’étape ainsi que les critères d’arrêt avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Conservez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les indicateurs fonctionnels doivent être regroupés en un seul endroit que les opérateurs peuvent auditer sans avoir à lire l’ensemble du système. Authentifiez-vous au niveau du gateway et réautorisez-vous au niveau du plan de données. Un simple token porteur ne constitue pas une frontière entre les tenants. Pour le cas de défaillance 1 lié à une étape mal formatée, il convient de définir les entrées, le responsable de l’étape ainsi que les critères d’arrêt avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Préférez des unités petites et testables plutôt que des scripts complexes. Lorsqu’une étape échoue, la défaillance doit pointer vers une seule responsabilité et non vers un pipeline embrouillé.

book_flight(flight_id=”AC-PHANTOM”, passenger_name=”J. Moffatt”)
# -> “Booked.” The action fired. Nothing in the loop asked whether it should.

Échec 2 : le contexte explose et la qualité se dégrade silencieusement

Lorsque vous travaillez sur l’étape où le contexte explose en cas d’échec 2, notez d’abord les conditions prévues : entrées requises, signal de succès, et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Considérez cette étape comme un contrat entre les entrées et les sorties validées. Donnez des noms aux artefacts, définez des vérifications de succès, et refusez toute exécution partielle silencieuse. Enregistrez le nom de l’outil, son hash des arguments, la latence et le résultat de chaque appel. Sans ce suivi, les boucles d’analyse des erreurs perdent des heures précieuses.

Échec 3 : un outil commet une erreur, mais l’agent signale un succès

Lorsque vous travaillez sur l’étape d’outil liée à l’échec 3, notez d’abord le contrat : les entrées requises, le signal de succès, ainsi que ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Enregistrez les temps d’exécution ainsi que le coût des jetons ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite des factures inattendues lorsque le parcours passe de l’environnement de démonstration à des environnements partagés. Journalisez le nom de l’outil, son hash d’arguments, la latence et le résultat de chaque appel. Sans cette trace, les boucles d’agent de débogage gaspillent des heures.

La structure que chaque composant suivra

Lors de la phase « La forme de chaque composant », notez d’abord le contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de garantir l’intégrité des modifications ultérieures du code. Conservez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les indicateurs fonctionnels doivent être regroupés en un seul endroit que les administrateurs peuvent auditer sans devoir lire l’ensemble du système. Enregistrez le nom outil, le hash des arguments, la latence et le résultat de chaque appel. Sans ces traces, le débogage devient une perte de temps considérable. Lors de la phase « La forme de chaque composant », notez d’abord le contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de garantir l’intégrité des modifications ultérieures du code. Préférez des unités petites et testables plutôt que des scripts complexes. Lorsqu’une étape échoue, l’erreur doit indiquer une seule responsabilité et non un processus embrouillé.

Faites cela aujourd’hui

La phase « Faire ceci aujourd’hui » fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Recueillez un exemplaire idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre. Considérez cette phase comme un contrat entre les entrées et les sorties validées. Donnez des noms aux artefacts, définez des vérifications de succès et refusez toute mise en œuvre partielle silencieuse. Exposez des outils dotés de schémas restreints et de labels explicites indiquant les effets secondaires. Les hôtes doivent savoir quels appels modifient l’état avant d’approuver automatiquement.

Le modèle est la partie facile

Le modèle fonctionne le mieux lorsqu’il est considéré comme une surface mesurable. Capturez un cas réussi exemplaire, un cas d’échec et la note de réversion avant d’élargir le périmètre. Enregistrez les temps d’exécution ainsi que le coût en tokens ou en requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe de la démonstration aux environnements partagés. Fixez un budget en tokens par tour et par session : les outils agents élargissent de manière importante le contexte ; des plafonds stricts empêchent que les démonstrations ne se transforment en factures inattendues.

Liste de contrôle opérationnelle

Lorsque vous travaillez sur l’étape de la liste de contrôle opérationnelle, notez d’abord les exigences : entrées requises, signal de succès et comportement en cas d’échec partiel. Cette liste garantit que les modifications ultérieures du code restent transparentes.

Dokumentez ensemble le parcours optimal et les procédures de récupération. Les tentatives de réessai, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’améliorations ultérieures.

Enregistrez le nom de l’outil, le hash des arguments, la latence et le résultat de chaque appel. Déboguer un agent en boucle sans cette trace fait perdre des heures.

Gardez l’état du graphe simple et typé. Les blocs imbriqués cachent lequel nœud a écrit quel champ et empêchent la reprise après interruption.

Ajoutez un test de fumée qui met à l’épreuve le chemin critique dans les CI avec des fixtures, et non des API payantes en temps réel, chaque fois que le budget le permet.

Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le chemin passe de la version démo aux environnements partagés.

Au préalable de promouvoir l’ensemble, figez les versions, capturez une transcription idéale pour le chemin critique et confirmez les étapes de rollback. Les environnements partagés nécessitent des limites de débit, des vérifications de location et un responsable clair pour la rotation des secrets. Préférez une fiabilité banale à des démos originales mais temporaires.

Note de lot pour 765280e2df21 : ne pas inclure les clés du fournisseur dans le répertoire, fixer une limite pour les tokens par session, et stocker les transcriptions à côté des fichiers d’évaluation afin que les remplacements ultérieurs de modèles restent comparables.