Een aangepaste agent bouwen met behulp van de Supervisor-API (bèta)

Important

Deze functie bevindt zich in de bètaversie. Accountbeheerders kunnen de toegang tot deze functie beheren vanaf de pagina Previews . Zie Azure Databricks previews beheren.

U kunt een Azure Databricks Apps-agent bouwen die gebruikmaakt van de Supervisor-API (bèta) voor indeling in plaats van de agentlus in uw eigen code te beheren. Het resultaat is hetzelfde als het ontwerpen van een aangepaste agent: een geïmplementeerde app met een chatgebruikersinterface, een /invocations eindpunt en verificatie. Het verschil is dat Azure Databricks de agentlus voor u uitvoert. Uw agent.py maakt één API-aanroep en Azure Databricks verwerkt de selectie, uitvoering en antwoordsynthese van hulpprogramma's.

De Supervisor-API werkt met een van de ondersteunde basismodellen. Wijzig het model veld om van provider te wisselen zonder uw hulpprogrammadefinities of handlerlogica aan te raken.

Wanneer gebruikt u de Supervisor-API?

De Supervisor-API werkt goed wanneer uw agent alleen Azure Databricks gehoste hulpprogramma's gebruikt en geen aangepaste logica nodig heeft tussen hulpprogramma-aanroepen. Gebruik in plaats daarvan een aangepaste agentlus als uw agent een van de volgende zaken vereist:

  • Hulpprogramma's voor functies aan de clientzijde (de Supervisor-API kan niet worden gemengd met gehoste en clienthulpprogramma's in één aanvraag)
  • Eindpunten van agenten behalve Agent Bricks Knowledge Assistant-eindpunten
  • Aangepaste retrievers, aangepaste invoer/uitvoer of fijnmazige streamingbesturing
  • Aangepaste Python logica tussen hulpprogramma-aanroepen, zoals voorwaardelijke vertakking of statusbeheer
  • Controle over inferentieparameters, zoals temperature

Zie Supervisor-API (bèta) voor de volledige API-verwijzing en ondersteunde parameters.

Requirements

Een aangepaste agent bouwen met behulp van de Supervisor-API

Het aanbevolen startpunt is om een nieuwe app te maken op basis van de nieuwste Databricks-app-sjabloon. De nieuwste sjablonen bevatten een ingebouwde use-supervisor-api vaardigheid voor AI-coderingsassistenten, evenals een add-tools vaardigheid voor het toevoegen van gehoste hulpprogramma's.

Zie Een AI-agent ontwerpen en implementeren in Databricks-apps om een nieuwe app te maken op basis van een sjabloon.

Zodra uw app is ingesteld vanaf de nieuwste sjabloon, opent u het project in uw AI-coderingsassistent en voert u het volgende uit:

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

De vaardigheid werkt uw agent_server/agent.py bij om DatabricksOpenAI().responses.create() aan te roepen met gehoste hulpprogramma's, waarmee de handmatige agentlus wordt vervangen. Ook voegt het de databricks-openai afhankelijkheid toe en worden de bètabeperkingen genoteerd.

Het resultaat is dezelfde geïmplementeerde app, met een chatgebruikersinterface, verificatie en een /invocations eindpunt, maar met eenvoudigere agentcode. Zie Een AI-agent ontwerpen en implementeren in Databricks-apps voor de volledige implementatiewerkstroom (implementeren in apps, hulpprogramma's toevoegen, evalueren).

Ondersteunde hulpprogramma's en parameters

Zie Supervisor-API (bèta) voor de volledige lijst met ondersteunde hulpprogrammatypen, aanvraagparameters en codevoorbeelden.

Voor elk hulpprogramma dat u toevoegt, verleent u ook de bijbehorende resourcemachtiging in databricks.yml. Bekijk de add-tools vaardigheid in .claude/skills/ voor voorbeelden.

Autorisatie voor gehoste hulpprogramma's

Wanneer de Supervisor-API de agentlus uitvoert, worden gehoste hulpprogramma's uitgevoerd met behulp van de identiteit van de app of de identiteit van de aanvragende gebruiker. Kies op basis van of alle gebruikers van de app dezelfde toegang tot uw hulpprogramma's moeten delen, of elke gebruiker mag alleen toegang krijgen tot wat hun eigen machtigingen toestaan.

  • App-autorisatie (standaard): Hulpprogramma's worden uitgevoerd als de service-principal van de app. Verleen de service-principal toestemming voor elk hulpprogramma dat de agent gebruikt. Zie App-autorisatie.
  • Gebruikersautorisatie: Hulpprogramma's worden uitgevoerd als de gebruiker die de aanvraag heeft verzonden, zodat Unity Catalog-machtigingen, rijfilters en kolommaskers per gebruiker van toepassing zijn. Zie de volgende sectie.

Hulpprogramma's uitvoeren als de aanvragende gebruiker

Important

Gebruikersautorisatie bevindt zich in openbare preview. Uw werkruimtebeheerder moet de scopes inschakelen voordat u ze aan uw app kunt toevoegen. Zie Bereiken toevoegen aan een app.

Als u gehoste hulpprogramma's wilt uitvoeren namens de aanvragende gebruiker, stuurt u het token van de gebruiker door naar de DatabricksOpenAI client en voegt u de gebruikersautorisatiebereiken toe die uw hulpprogramma's nodig hebben.

  1. Voeg de gebruikersautorisatiebereiken toe die uw app nodig heeft. ai-gateway is vereist voor alle toegang tot de Supervisor-API. Voeg het bereik per hulpprogramma toe voor elk hulpprogrammatype dat door de agent wordt gebruikt:

    Type gereedschap Vereiste reikwijdte
    Alle hulpmiddelen ai-gateway
    genie_space genie
    uc_function mcp.functions
    knowledge_assistant model-serving
    uc_connection catalog.connections

    Het app hulpprogrammatype wordt niet ondersteund met gebruikersautorisatie. Als u een app-eindpunt als hulpprogramma wilt aanroepen, gebruikt u in plaats daarvan app-autorisatie. Zie Gebruikersautorisatie voor informatie over hoe u scopes toevoegt via de workspace-UI of Declarative Automation Bundles.

  2. Geef in uw agent.py handler een gebruikerswerkruimteclient door aan DatabricksOpenAI. Dit is de enige supervisorspecifieke bedrading: in plaats van een resource rechtstreeks aan te roepen met de gebruikersclient, brengt u deze naar de client die de agentlus uitvoert.

    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() leest het doorgestuurde gebruikerstoken uit de requestheaders, die alleen tijdens het uitvoeren van de query worden gevuld. Roep deze aan binnen de handlers invoke en stream, nooit in __init__ of bij het opstarten van de app. Als het doorgestuurde token ontbreekt, wordt de resulterende client niet geverifieerd als de aanvragende gebruiker. Zie Gebruikersautorisatie voor informatie over het verifiëren of de agent wordt uitgevoerd onder de identiteit van de aanroeper in plaats van die van de service-principal van de app.

  3. Verleen iedere gebruiker die de agent uitvoert de vereiste machtiging voor elk hulpmiddel, zoals CAN_RUN op een Genie Space of CAN_QUERY op een endpoint van een kennisassistent.

Aanvullende informatiebronnen

  • Last updated on