Skapa en anpassad agent med hjälp av Api för övervakare (Beta)

Important

Den här funktionen finns i Beta. Kontoadministratörer kan styra åtkomsten till den här funktionen från sidan Förhandsversioner . Se Hantera förhandsversioner av Azure Databricks.

Du kan skapa en Azure Databricks Apps-agent som använder Supervisor API (Beta) för orkestrering i stället för att hantera agentloopen i din egen kod. Resultatet är detsamma som att skapa en anpassad agent: en distribuerad app med ett chattgränssnitt, en /invocations slutpunkt och autentisering. Skillnaden är att Azure Databricks kör agentloopen åt dig. Din agent.py gör ett enda API-anrop och Azure Databricks hanterar verktygsval, körning och svarssyntes.

Supervisor-API:et fungerar med någon av de grundläggande modeller som stöds. Ändra fältet model för att växla providers utan att röra vid verktygsdefinitioner eller hanteringslogik.

När du ska använda api:et för övervakare

Api för övervakare fungerar bra när din agent endast använder Azure Databricks värdbaserade verktyg och inte behöver anpassad logik mellan verktygsanrop. Använd en anpassad agentloop i stället om din agent kräver något av följande:

  • Funktionsverktyg på klientsidan (övervakar-API:et kan inte blanda värdbaserade verktyg och verktyg på klientsidan i en begäran)
  • Andra agentslutpunkter än Agent Bricks Knowledge Assistant-slutpunkter
  • Anpassade hämtningar, anpassade indata/utdata eller detaljerad strömningskontroll
  • Anpassad Python logik mellan verktygsanrop, till exempel villkorlig förgrening eller tillståndshantering
  • Kontroll över slutsatsdragningsparametrar som temperature

Fullständig API-referens och parametrar som stöds finns i Supervisor API (Beta).

Kravspecifikation

Skapa en anpassad agent med hjälp av övervakar-API:et

Den rekommenderade utgångspunkten är att skapa en ny app från den senaste Databricks-appmallen. De senaste mallarna innehåller en inbyggd färdighet för AI-kodningsassistenter use-supervisor-api samt en add-tools färdighet för att lägga till värdbaserade verktyg.

Information om hur du skapar en ny app från en mall finns i Skapa en AI-agent och distribuera den i Databricks-appar.

När appen har konfigurerats från den senaste mallen öppnar du projektet i AI-kodningsassistenten och kör:

Use the Supervisor API skill to update this agent to use the Databricks Supervisor API.

Färdigheten uppdaterar ditt agent_server/agent.py för att ringa DatabricksOpenAI().responses.create() med hjälp av värdbaserade verktyg och ersätter den manuella agentloopen. Det lägger också till databricks-openai beroendet och noterar betabegränsningarna.

Resultatet är samma distribuerade app, med ett chattgränssnitt, autentisering och en /invocations slutpunkt, men med enklare agentkod. Det fullständiga distributionsarbetsflödet (distribuera till appar, lägg till verktyg, utvärdera) finns i Skapa en AI-agent och distribuera den i Databricks-appar.

Verktyg och parametrar som stöds

En fullständig lista över verktygstyper som stöds, begäransparametrar och kodexempel finns i Supervisor API (Beta).

För varje verktyg som du lägger till beviljar du även motsvarande resursbehörighet i databricks.yml. Se färdigheten add-tools i .claude/skills/ för exempel.

Auktorisering för värdbaserade verktyg

När övervakar-API:et kör agentloopen körs värdbaserade verktyg med antingen appens identitet eller den begärande användarens identitet. Välj baserat på om alla användare av appen ska dela samma åtkomst till dina verktyg, eller om varje användare bara ska få åtkomst till vad deras egna behörigheter tillåter.

  • Appauktorisering (standard): Verktyg körs som appens huvudobjekt för tjänsten. Bevilja tjänsthuvudnamnet behörighet till varje verktyg som agenten använder. Se Appauktorisering.
  • Användarauktorisering: Verktyg körs som den användare som skickade begäran, så behörigheter, radfilter och kolumnmasker i Unity-katalogen gäller per användare. Se följande avsnitt.

Kör verktyg som den begärande användaren

Important

Användarauktorisering finns i offentlig förhandsversion. Administratören för din arbetsyta måste aktivt möjliggöra det innan du kan lägga till behörigheter i din app. Se Lägg till omfång i en app.

Om du vill köra värdbaserade verktyg åt den begärande användaren vidarebefordrar du användarens token till DatabricksOpenAI klienten och lägger till de användarauktoriseringsomfång som dina verktyg behöver.

  1. Lägg till de användarauktoriseringsomfång som din app behöver. ai-gateway krävs för all åtkomst till Supervisor API. Lägg till omfånget per verktyg för varje verktygstyp som agenten använder:

    Verktygstyp Obligatoriskt omfång
    Alla verktyg ai-gateway
    genie_space genie
    uc_function mcp.functions
    knowledge_assistant model-serving
    uc_connection catalog.connections

    Verktygstypen app stöds inte med användarauktorisering. Om du vill anropa en appslutpunkt som ett verktyg använder du appauktorisering i stället. Mer information om hur du lägger till omfång via arbetsytans användargränssnitt eller deklarativa automatiseringspaket finns i Användarbehörighet.

  2. I din agent.py-hanterare skickar du en klient för användararbetsyta till DatabricksOpenAI. Det här är den enda övervakarspecifika kabelkopplingen: i stället för att anropa en resurs direkt med användarklienten, lämnar du den till klienten som kör agentloopen.

    from databricks_openai import DatabricksOpenAI
from agent_server.utils import get_user_workspace_client

# Inside your invoke or stream handler, not at app startup
client = DatabricksOpenAI(
  workspace_client=get_user_workspace_client(),
  use_ai_gateway=True,
)

    get_user_workspace_client() läser den vidarebefordrade användartoken från begärandehuvudena, som endast fylls i vid frågetillfället. Anropa den i hanterarna invoke och stream , aldrig i __init__ eller vid appstart. Om den vidarebefordrade token saknas autentiseras inte den resulterande klienten som den begärande användaren. Information om hur du verifierar att agenten körs som anropare i stället för appens tjänsthuvudnamn finns i Användarauktorisering.

  3. Ge varje användare som kör agenten den behörighet som krävs för varje verktyg, till exempel CAN_RUN på ett Genie-utrymme eller CAN_QUERY på en slutpunkt för kunskapsassistenten.

Ytterligare resurser

  • Last updated on