Agent Server

Un serveur d’agent est la bibliothèque qui transforme votre code agent en service. Il enveloppe la boucle d’agent dans un serveur HTTP, définit l’API que les clients appellent pour exécuter l’agent, gère les connexions clients et détermine ce qui se passe lorsqu’une exécution est interrompue. Le serveur de l’agent fonctionne sur l’environnement d’exécution de l’agent. Pour comprendre comment les couches s’assemblent, voir Déployer des agents sur Azure Databricks.

Pour les nouveaux agents, Databricks recommande le serveur d’agents fourni par AgentKit , que cette page décrit. Pour le comparer avec les serveurs agents hérités, voir Comparer serveurs agents sur Azure Databricks.

Spécifications

Python 3.10 et plus.
Le databricks-agentbricks package, qui inclut AgentKit. Les projets que vous créez avec agentbricks init le déclarent comme une dépendance.

AgentKit

AgentKit est la bibliothèque Agent Bricks pour construire des agents qui s’exécutent sur Agent Runtime. Il fournit le serveur d’agents qui sert votre agent, ainsi que des clients et des utilitaires pour la mémoire de l’agent, les sessions d’agents, la traçabilité et l’authentification. Les projets que vous créez avec Agent Bricks CLI utilisent par défaut AgentKit.

Serveur d’agent

AgentKit fournit son serveur agent via la DurableAgentServer classe. Le serveur d’agent encapsule votre boucle d’agent dans un serveur HTTP qui sert l’API d’invocation, suit chaque exécution et récupère les exécutions qu’un plantage ou un redémarrage interrompt. Il offre :

Une API pour chaque mode de requête : Synchrone, streaming, et appels en arrière-plan, plus la reconnexion du flux, le tout pris en charge par le même gestionnaire.
Invocations idempotentes : Un ID d’invocation généré par le client garantit qu’une requête réessayée ne déclenche pas une exécution dupliquée.
Sessions ordonnées : Les invocations dans la même session s’exécutent une à une, dans l’ordre.
État d’exécution persistant : Une fois déployé, l’état de l’exécution, les événements et les résultats survivent aux redémarrages des travailleurs.
Récupération après plantage : le serveur détecte les exécutions interrompues et lance une tentative de remplacement.
Demande d’autorisation utilisateur : Les outils peuvent agir avec les permissions de l’utilisateur qui a envoyé la requête.
Points de terminaison personnalisés : Le serveur agent est une application FastAPI, vous pouvez donc ajouter vos propres routes.

Ce qu’inclut AgentKit

AgentKit est une bibliothèque Python databricks_agentkit. Elle exporte les éléments suivants :

Export	Description
`DurableAgentServer`, `InvocationContext`	Le serveur agent et le contexte qu’il transmet à vos gestionnaires d’invocation et de récupération.
`AgentKitClient`	Un client pour la mémoire des agents et les magasins de sessions d’agents. Il crée et obtient des stores, et expose les mémoires et sessions des stores sous forme de `Memory`, `MemoryStore`, `MemorySearchResult`, `Session`, `SessionStore` et `SessionItem` objets.
`configure_tracing`, `start_trace`	Configurez le traçage MLflow pour l’agent, et lancez une trace autour d’une unité de travail.
`workspace_client`, `workspace_headers`	Créez un SDK `WorkspaceClient`Databricks authentifié, ou obtenez des en-têtes d’authentification pour les appels HTTP directs, depuis l’environnement de l’agent.
`list_ai_gateway_model_services`	Listez les services modèles que l’agent peut appeler via Unity Gateway.

La bibliothèque inclut également des assistants de framework dans databricks_agentkit.langgraph et databricks_agentkit.openai, que les modèles générés utilisent pour connecter chaque framework au magasin de session. Pour les API mémoire et session, voir Mémoire de l’agent et Sessions de l’agent.

Enregistrez votre agent

Lorsque vous créez un projet avec agentbricks init, la CLI fait cela pour vous. Le runtime/main.py généré crée le serveur et enregistre les gestionnaires d’appel et de récupération du modèle, donc vous n’éditez que le code de l’agent dans agent/. Suivez les étapes de cette section pour intégrer un agent existant ou pour écrire votre propre gestionnaire.

Créer un DurableAgentServer et enregistrer un gestionnaire d’invocation asynchrone avec @app.invoke. Le gestionnaire reçoit le input de la requête et un contexte d’invocation, et retourne un résultat sérialisable en JSON. Publiez l’avancement sous forme d’événements avec context.emit.

from databricks_agentkit import DurableAgentServer, InvocationContext

app = DurableAgentServer()


@app.invoke
async def invoke(input, context: InvocationContext) -> dict:
    await context.emit({"type": "status", "message": "Looking that up"})
    answer = await run_my_agent(input, session_id=context.session_id)
    return {"answer": answer}

Vous pouvez enregistrer un gestionnaire d’appel, et le serveur ne démarre pas sans gestionnaire. Le gestionnaire prend en charge tous les modes de requête : le client choisit d’attendre le résultat, de recevoir les événements de flux ou d’exécuter la tâche en arrière-plan.

Pour faire tourner le serveur localement, démarrez-le avec agentbricks dev. Les projets que vous créez avec agentbricks init incluent un point d’entrée qui fait tourner le serveur avec Uvicorn, et un fichier app.yaml qui lance le même point d’entrée après le déploiement.

Contexte d’appel

Le second argument du manipulateur est un InvocationContext:

Attribut	Description
`invocation_id`	L’ID que le client a envoyé pour cette invocation.
`session_id`	La session à laquelle appartient l’appel, ou `None` si le client n’en a pas fourni.
`attempt`	Numéro de la tentative. La première tentative est `1`.
`is_recovery`	`True` lorsque le gestionnaire de récupération effectue une tentative de remplacement.
`emit(event)`	Stocke un événement JSON, le livre aux clients de streaming, puis restitue la position de l’événement dans le stream.
`request_auth`	L’outil de résolution d’informations d’identification de l’utilisateur de la requête, lorsque l’agent nécessite l’autorisation request-user. Sinon, `None`.

API d’invocation

DurableAgentServer fournit l’API d’appel à /api/invocations :

POST /api/invocations démarre un appel. Par défaut, la requête attend le résultat. Configurez stream pour recevoir les événements en tant qu’événements envoyés par le serveur, ou background pour renvoyer immédiatement une URL d’état.
GET /api/invocations/<id> renvoie le statut d’un appel et, après son achèvement, sa sortie.
GET /api/invocations/<id>/events?after=<event-id> diffuse les événements stockés, afin qu’un client puisse se reconnecter après une coupure de connexion.

Pour les champs de requête, les exemples et les formats de réponse, voir Interroger les agents déployés sur Azure Databricks.

Idempotence

Les clients envoient un UUID id à chaque invocation. Le serveur traite l’ID comme une clé d’idempotence tout en conservant l’enregistrement d’invocation : renvoyer la même requête renvoie l’invocation existante au lieu de relancer l’agent. Réutiliser un ID pour une requête différente renvoie une erreur 409.

Sessions

Les clients peuvent envoyer un session_id pour regrouper les invocations dans une seule conversation. Le serveur stocke l’ID de session séparément de input, le transmet à votre gestionnaire sous la forme de context.session_id, et exécute des invocations qui partagent un identifiant de session une par une, dans l’ordre. Le serveur ne déduit pas une session à partir de l’ID d’invocation ni de l’entrée. Sans identifiant de session, un appel n’est associé à aucune session.

État d’exécution

DurableAgentServer stocke la demande, le statut, les pulsations, les événements et le résultat de chaque appel dans un magasin de runtime.

Développement local : agentbricks dev utilise un magasin de runtime in-process. L’API d’invocation se comporte de la même manière, mais l’état d’exécution est perdu lorsque le processus s’arrête, et le serveur ne redémarre pas le travail interrompu.
Agents déployés : agentbricks deploy provisionne une base de données dédiée pour le magasin de runtime de chaque déploiement dans un projet Lakebase géré par Azure Databricks, et la réutilise lors du redéploiement. Vous ne pouvez pas utiliser votre propre projet Lakebase pour le Runtime Store, et vous ne le créez ni ne le liez vous-même. Les résultats et événements survivent aux redémarrages des travailleurs, et toute instance de l’agent peut servir les demandes de statut et de reconnexion. agentbricks deployments delete supprime le Runtime Store avec le déploiement.

Le Runtime Store contient l’état d’exécution du serveur. C’est séparé des stockages de session et de mémoire que votre agent utilise pour l’historique des conversations et la mémoire à long terme.

Récupération après un crash

Pour récupérer des exécutions qu’un crash ou un redémarrage d’un worker interrompt, enregistrez un gestionnaire de récupération avec @app.recover. Lorsqu’un serveur déployé détecte que les signaux de vie d’une exécution se sont arrêtés, il lance une tentative de remplacement sur un worker disponible et appelle le gestionnaire de récupération avec l’entrée initiale.

@app.recover
async def recover(input, context: InvocationContext) -> dict:
    # Resume from the agent's last checkpoint in the session store,
    # or replay the input if that's safe for your agent.
    return await resume_my_agent(input, session_id=context.session_id)

Si vous n’enregistrez pas de gestionnaire de récupération, la récupération automatique est désactivée, et le serveur affiche un avertissement au démarrage.

La récupération se déroule comme suit :

Quand la récupération commence : Chaque tentative en cours d'exécution envoie un heartbeat toutes les quelques secondes. Si les battements de cœur s’arrêtent, par exemple parce que le worker plante, redémarre ou est remplacé lors d’un redéploiement, le serveur détecte l’exécution obsolète en quelques secondes et lance une tentative de remplacement.
Quand la récupération ne démarre pas : Si votre gestionnaire lève une exception, l’invocation échoue et le serveur ne la réessaie pas. La récupération couvre les workers interrompus, pas les erreurs dans votre code d’agent.
Nombre de tentatives : Le serveur ne limite pas le nombre de tentatives de récupération. Chaque tentative de remplacement augmente context.attempt d’un point. Pour arrêter après un certain nombre de tentatives, vérifiez context.attempt dans votre gestionnaire de récupération et signalez une erreur.
Récupération manuelle : Vous ne pouvez pas lancer la récupération manuellement. Réenvoyer une requête avec le même ID d’invocation renvoie l’invocation existante au lieu de commencer une nouvelle tentative.

Recovery peut exécuter votre code d’agent plusieurs fois pour la même invocation. Une tentative interrompue a peut-être déjà appelé des systèmes externes avant le début de la tentative de remplacement, donc rendez ces appels idempotents.

Autorisation request-user

Par défaut, les outils de votre agent fonctionnent avec les permissions du principal de service de l’application. Pour exécuter un outil avec les permissions de l’utilisateur qui a envoyé la requête, déclarez l’autorisation utilisateur dans agent.toml:

Pour un outil géré, définissez auth = "user" dans l’entrée de l’outil. Les commandes agentbricks tools add pour les serveurs MCP, les bacs à sable et les agents Genie écrivent dans auth = "user" par défaut. Indiquez --auth app pour utiliser l’identité de l’application à la place.
Pour un outil que vous écrivez en code, déclarez l’exigence et toutes les étendues de l’API que Agent Bricks ne peut pas déduire :
```
[auth.user]
required = true
additional_api_scopes = ["sql"]
```

Lorsqu’un agent nécessite une autorisation utilisateur, DurableAgentServer lit les informations d’identification de l’utilisateur depuis les en-têtes de requête Databricks Apps de confiance et les conserve en mémoire uniquement pour la tentative active. Le magasin de runtime ne stocke pas les informations d’identification. Dans votre gestionnaire, obtenez un client d’espace de travail pour l’utilisateur à partir de context.request_auth:

@app.invoke
async def invoke(input, context: InvocationContext) -> dict:
    user_client = context.request_auth.client_for("user")
    me = user_client.current_user.me()
    return {"answer": f"Hello, {me.user_name}"}

client_for("app") renvoie un client qui utilise le principal de service de l’application. L’outil de résolution se ferme à la fin de la tentative, donc appelez-le à l’intérieur du gestionnaire au lieu de stocker le client. Lorsque vous exécutez l’agent localement avec agentbricks dev, client_for("user") utilise vos identifiants locaux.

Lorsque vous déployez, agentbricks deploy demande les étendues utilisateur des applications Databricks dont vos outils ont besoin. Pour ajouter des scopes manquants à une application existante, passez --allow-user-scope-update. Consultez Configurer l’autorisation dans une application Databricks.

Les invocations Request-user utilisent les mêmes API synchrones, de streaming, en arrière-plan et de reconnexion. Comme le serveur ne stocke pas les identifiants de l’utilisateur, il ne peut pas récupérer un appel request-user interrompu. La tentative de remplacement échoue avec l’erreur MCP_USER_AUTH_RECOVERY_UNSUPPORTED avant que vos gestionnaires ne s’exécutent.

Ajouter des points de terminaison personnalisés

DurableAgentServer est une application FastAPI. Ajoutez des routes aux côtés de l’API d’invocation de la même manière que vous les ajoutez à n’importe quelle application FastAPI :

@app.get("/status")
async def status() -> dict:
    return {"ready": True}

Modèles de framework

agentbricks init Génère deux répertoires :

agent/ contient votre code du framework : le modèle, les prompts et les outils.
runtime/ contient l’adaptateur qui relie le framework à DurableAgentServer, et le point d’entrée qui enregistre les gestionnaires d’invocation et de récupération de l’adaptateur.

L’adaptateur traduit chaque invocation en un appel à la boucle agent du framework, et traduit la sortie du framework en événements et en résultat. Les deux modèles définissent un gestionnaire de récupération. Le modèle LangGraph reprend depuis son dernier point de contrôle dans le magasin de session, et le modèle SDK des agents OpenAI relance la requête dans la même session. Pour intégrer un agent existant, ajoutez un adaptateur et un point d’entrée DurableAgentServer, et réglez server = "agentbricks" dans la section [agent] de agent.toml.

Comparer les serveurs agents sur Azure Databricks

Azure Databricks propose trois serveurs agents : le serveur d’agents AgentKit et deux serveurs d’agents hérités utilisés par les anciens modèles d’applications.

Serveur Agent	Package	API de client	Exécution durable	Utilisé par
AgentKit (`DurableAgentServer`recommandé)	`databricks_agentkit`, dans le package `databricks-agentbricks`.	API d’invocation à `/api/invocations`: exécutions synchrones, en streaming et en arrière-plan, avec reconnexion du flux	Un magasin de runtime qui assure le provisionnement `agentbricks deploy`, ainsi que la récupération en cas de plantage via un gestionnaire de récupération	Projets que vous créez avec le CLI Agent Bricks
`LongRunningAgentServer` (hérité)	`databricks_ai_bridge.long_running`, dans le package `databricks-ai-bridge[agent-server]`.	OpenAI Responses API à `/responses`, avec des exécutions en arrière-plan et la reprise du flux	État d’exécution dans une base de données Lakebase que vous configurez. Après un crash, une nouvelle tentative poursuit l’exécution depuis le journal d’événements de la tentative interrompue.	Les et `agent-openai-advancedagent-langgraph-advanced`
MLflow `AgentServer` (hérité)	`mlflow.genai.agent_server`, dans le package `mlflow`.	API OpenAI Responses à `/responses`: exécutions synchrones et en streaming	None	Les modèles d’applications de base, tels que `agent-openai-agents-sdk`

LongRunningAgentServer étend le MLflow AgentServer, et les deux servent les agents qui implémentent l’interface MLflow ResponsesAgent . Pour déployer et maintenir un agent utilisant l’un d’eux, voir Exécuter des agents sur Databricks Apps utilisant le serveur d’agents hérité. Pour interroger un agent sur l’un de ces serveurs, voir Interroger les agents déployés sur Azure Databricks.

Limitations

Vous ne pouvez pas changer le serveur agent d’un déploiement existant. Pour passer entre DurableAgentServer et votre propre serveur, créez un nouveau projet avec l’option agentbricks init --server que vous souhaitez, puis déployez-le sous un nouveau nom.
Changer le champ server dans agent.toml ne convertit pas le code serveur existant en DurableAgentServer.
L’autorisation request-user nécessite server = "agentbricks".

Ressources additionnelles

Commentaires

Cette page a-t-elle été utile ?

Dernière mise à jour : 2026-10-15