Aller au contenu principal

Agent Runtime

Agent Runtime exécute votre agent sur une compute Serverless hébergée par Databricks. Il exécute le serveur de votre agent, tel que DurableAgentServer, sur Databricks Apps, ce qui vous permet de déployer du code au lieu d'effectuer le provisionnement de serveurs. Pour découvrir comment Agent Runtime s'intègre à votre framework et au serveur de votre agent, consultez Déployer des agents sur Databricks.

Ce que Runtime fournit pour l’agent​

  • Un endpoint stable et authentifié : chaque déploiement est une application nommée agent-bricks-<name> dotée de sa propre URL. Les clients s’authentifient à l’aide d’un jeton OAuth Databricks. Consultez Query des agents déployés sur Databricks.
  • Identité de l'agent : l'agent s'exécute en tant que Service Principal de l'application. Voir Identité de l'agent.
  • Exécution durable : pour les agents qui utilisent DurableAgentServer, le déploiement provisionne un Runtime Store afin que l’état de l’exécution soit conservé malgré les redémarrages des Worker et que les exécutions interrompues puissent reprendre.
  • Tracing : le déploiement configure le traçage MLflow sur l'Experimentation à laquelle le projet est lié. Consultez Aperçu du traçage.
  • Monter en charge : exécutez un agent à l'échelle sur plusieurs instances. Consultez Montée en charge horizontale pour les applications Databricks.

Identité de l'agent​

L’identité d’un agent est le Service Principal de l’application sur laquelle il est déployé. L’agent utilise cette identité pour appeler les APIs Databricks et exécuter les outils que vous ajoutez avec --auth app.

  • Lorsque vous déployez, agentbricks deploy accorde au service principal l’accès aux magasins de mémoire, de session et d’état d’exécution utilisés par l’agent.
  • Pour donner à l'agent accès à d'autres données et ressources, accordez au service principal de l'application les autorisations dont il a besoin, comme vous leisseriez pour n'importe quelle application. Consultez Configure authorization in a Databricks app.
  • Les outils qui utilisent auth = "user" s’exécutent avec les autorisations de l’utilisateur ayant envoyé la requête au lieu du Service Principal. Voir Autorisation de l’utilisateur demandeur.

Prérequis​

  • Installez la CLI Databricks, Python 3.11 ou version supérieure et uv.

  • Installez l'Agent Bricks CLI :

    Bash
    uv tool install databricks-agentbricks
  • Connectez-vous à votre Workspace. agentbricks login enregistre le profil comme default, afin que les commandes ultérieures puissent omettre --profile:

    Bash
    databricks auth login --host <workspace-url> --profile <profile>
    agentbricks login --profile <profile>
  • Créez un projet d'agent et accédez à son répertoire :

    Bash
    agentbricks init my-agent
    cd my-agent

Déployer un agent​

Déployez un projet d’agent avec la CLI Agent Bricks.

Déployer à partir du répertoire du projet​

Pour déployer l'agent, exécutez la commande suivante à partir du répertoire du projet :

Bash
agentbricks deploy my-agent

Pour déployer sur un Workspace autre que celui par default, passez --profile <profile>.

Le répertoire du projet contient agent.toml et app.yaml. Si vous exécutez agentbricks deploy à partir d’un autre répertoire, il upload ce répertoire à la place. Pour déployer un projet à partir d’un autre répertoire, passez --source <dir>.

L'argument de agentbricks deploy est le nom du déploiement, jusqu'à 17 caractères. L'application se nomme agent-bricks-<name>, cet exemple crée donc agent-bricks-my-agent. Le premier déploiement enregistre le nom dans agent.toml, les déploiements ultérieurs depuis le projet peuvent donc l'omettre.

Un premier déploiement prend quelques minutes. La commande se termine lorsque l’agent répond aux demandes.

agentbricks deploy fait ce qui suit :

  1. Crée ou réutilise la mémoire et les magasins de sessions déclarés dans agent.toml, et accorde l’accès au service principal de l’application.
  2. Pour les agents qui utilisent DurableAgentServer, créez ou réutilisez le Runtime Store du déploiement.
  3. Configure le traçage.
  4. Déploie l'application.

Pour exécuter l'agent sur plusieurs instances, transmettez --instances:

Bash
agentbricks deploy my-agent --instances 2

Lorsqu’un agent s’exécute sur plusieurs instances, les clients peuvent envoyer l’ID de session dans un en-tête X-Routing-Key pour acheminer toutes les requêtes d’une session vers la même instance.

Déployer sans attendre​

Si un script ou un agent de codage a un délai d’expiration de commande court, déployez sans attendre, puis attendez le déploiement dans une commande distincte :

Bash
agentbricks deploy my-agent --no-wait
agentbricks deployments wait agent-bricks-my-agent

--no-wait exécute les vérifications rapides, puis termine le déploiement dans un processus d'arrière-plan. agentbricks deployments wait attend jusqu'à 100 secondes par default. Pour modifier la limite, transmettez --timeout. La commande se termine avec l'un des codes suivants :

  • 0: L'agent est déployé et répond aux demandes.
  • 1: le déploiement a échoué.
  • 75: L'agent est encore en cours de déploiement. Exécutez à nouveau la commande.

Exécutez agentbricks deployments wait à partir du répertoire du projet ou passez --source <dir>.

Gérer les déploiements​

Commande

Description

agentbricks deployments list

Répertoriez vos déploiements d'agents.

agentbricks deployments get <app-name>

Afficher l’URL, l’état et la description d’un déploiement.

agentbricks deployments wait [<app-name>]

Attendez la fin d'un déploiement. Par default, le déploiement enregistré dans agent.toml.

agentbricks deployments logs <app-name>

Afficher les logs d’un déploiement.

agentbricks deployments start <app-name>

start un déploiement.

agentbricks deployments stop <app-name>

Arrêtez un déploiement. Demande confirmation sauf si --yes est transmis.

agentbricks deployments delete <app-name>

Supprimer un déploiement. Demande une confirmation, sauf si vous transmettez --yes.

Commande

Description

agentbricks deployments list

Répertoriez vos déploiements d'agents.

agentbricks deployments get <app-name>

Afficher l’URL, l’état et la description d’un déploiement.

agentbricks deployments wait [<app-name>]

Attendez la fin d'un déploiement. Par default, le déploiement enregistré dans agent.toml.

agentbricks deployments logs <app-name>

Afficher les logs d’un déploiement.

agentbricks deployments start <app-name>

start un déploiement.

agentbricks deployments stop <app-name>

Arrêtez un déploiement. Demande confirmation sauf si --yes est transmis.

agentbricks deployments delete <app-name>

Supprimer un déploiement. Demande une confirmation, sauf si vous transmettez --yes.

Puisque chaque déploiement est une application, vous pouvez également l’afficher et le monitoring dans Databricks Apps. Consultez Logging and Monitoring for Databricks Apps.

Limitations​

Vous ne pouvez pas modifier le serveur d'agent d'un déploiement existant. Pour changer de serveur, créez un nouveau projet avec l'option agentbricks init --server de votre choix, puis déployez-le sous un nouveau nom.

Ressources supplémentaires​