Endpoints d'agents personnalisés

Lorsque votre application AppKit a besoin de plus qu'une réponse de foundation model ou qu'une requête de données de type Genie, vous faites appel à un custom agent : un LLM façonné par des instructions, des outils, un ancrage documentaire ou une orchestration multi-agents. Vous pouvez en exécuter un depuis AppKit de deux façons :

• Exécutez-le directement dans votre application avec le plugin agents. Vous définissez l'agent en code ou en markdown, ou vous exécutez un Supervisor managé via l'adaptateur Supervisor API, sans avoir à déployer d'endpoint distinct. Privilégiez cette approche pour un nouvel agent que vous développez vous-même.
• Appelez un agent déjà exposé sous forme d'endpoint de serving avec le plugin Model Serving. Utilisez cette approche pour un Knowledge Assistant, ou pour tout agent déjà déployé en tant qu'endpoint partagé.

Prérequis

• Databricks CLI v1.0.0+ avec un profil authentifié.
• Une application AppKit en cours d'exécution. Consultez le démarrage rapide Apps.
• Pour l'approche par endpoint décrite ci-dessous, un agent déjà déployé en tant qu'endpoint de serving.

Exécuter un agent au sein de votre App

Le plugin agents héberge l'agent dans votre App. Vous le définissez en markdown ou en code, vous y connectez des outils, et il est exposé sur des routes intégrées, sans aucun endpoint à provisionner. Pour un nouvel agent personnalisé ou un Supervisor Agent, commencez ici.

Pour un Supervisor qui coordonne des spaces Genie, des fonctions Unity Catalog ou d'autres agents, l'adaptateur Supervisor API exécute l'agent comme un service managé sur Databricks :

import { createApp } from "@databricks/appkit";
import {
  agents,
  createAgent,
  DatabricksAdapter,
} from "@databricks/appkit/beta";

await createApp({
  plugins: [
    agents({
      agents: {
        assistant: createAgent({
          instructions: "You are a helpful assistant.",
          model: DatabricksAdapter.fromSupervisorApi({
            model: "databricks-claude-sonnet-4-6",
          }),
        }),
      },
    }),
  ],
});

Consultez la référence du plugin agents pour en savoir plus sur les agents markdown, la limitation de portée des outils, les sous-agents et les outils Supervisor hébergés.

Appeler un endpoint d'agent existant

Certains agents sont accessibles via un endpoint Model Serving plutôt qu'exécutés dans l'application. C'est toujours le cas d'un Knowledge Assistant, et cela peut l'être d'un Supervisor Agent ou d'un custom Python agent. Le plugin Model Serving les appelle tous par leur nom, comme un foundation model. Voici les builders qui produisent un tel endpoint :

Les builders Knowledge Assistant et Supervisor Agent se configurent en quelques clics dans le workspace. Vous pouvez aussi les créer depuis votre agent de code avec la compétence d'agent databricks-agent-bricks. La Supervisor API permet de définir un Supervisor Agent en Python, pour les équipes qui préfèrent le code à l'interface du workspace.

Déployer un custom agent sur son propre endpoint Model Serving avec agents.deploy() est une approche héritée. Privilégiez son exécution dans l'application (voir ci-dessus), ou consultez Créer un agent et Migrer vers Databricks Apps.

Mise en place

Le plugin Model Serving appelle les endpoints d'agent exactement comme il appelle les endpoints de foundation model. Faites pointer le plugin vers la variable d'environnement de votre agent :

serving({
  endpoints: {
    assistant: { env: "DATABRICKS_AGENT_ENDPOINT" },
  },
}),

Liez la variable d'environnement à une ressource serving-endpoint dans app.yaml :

env:
  - name: DATABRICKS_AGENT_ENDPOINT
    valueFrom: serving-endpoint

Lorsque vous ajoutez l'endpoint de l'agent comme ressource d'application (interface Databricks Apps ou CLI), Databricks accorde le droit CAN QUERY sur cet endpoint au service principal de votre application.

Pour la mise en œuvre complète, y compris createApp, useServingStream et les gestionnaires de routes personnalisés, consultez Appeler un endpoint gouverné depuis AppKit.

À quoi ressemble la réponse

Les réponses en streaming arrivent sous forme de fragments useServingStream. Les appels sans streaming renvoient l'objet complet via useServingInvoke. Le format de la requête est généralement compatible avec OpenAI Chat Completions (messages, max_tokens, stream en option). Les endpoints reposant sur ResponsesAgent utilisent plutôt l'API OpenAI Responses (input à la place de messages).

Le format de la réponse dépend du builder : vérifiez-le plutôt que de le deviner.

1. Ouvrez votre endpoint d'agent dans le workspace et cliquez sur Open in Playground.
2. Cliquez sur Get code et choisissez Curl API ou Python API.
3. Exécutez l'exemple et inspectez la réponse pour connaître les champs exacts.

Permissions par utilisateur

Par défaut, les routes de serving d'AppKit s'exécutent pour le compte de l'utilisateur authentifié. Si l'agent accède à des données propres à l'utilisateur (par exemple un Supervisor Agent qui redirige vers un Genie Agent que l'utilisateur est autorisé à interroger), celui-ci ne voit que les données auxquelles il a droit. Aucun code d'authentification supplémentaire n'est nécessaire.

Pour la logique serveur en dehors des routes de plugin intégrées (par exemple des routes Express personnalisées), appelez AppKit.serving("assistant").asUser(req).invoke(...) afin de conserver ce comportement par utilisateur. Pour les traitements en arrière-plan sans requête (tâches planifiées, workers), omettez asUser : l'appel s'exécute alors avec le service principal de l'application.

Et ensuite ?

Essayez l'AI Chat App pour une configuration complète d'AppKit et d'agent, ou parcourez le catalogue de modèles pour découvrir d'autres approches.