Een AI-agent ontwerpen en implementeren in Databricks-apps

Bouw een AI-agent en implementeer deze met databricks-apps. Databricks Apps biedt u volledige controle over de agentcode, serverconfiguratie en implementatiewerkstroom. Deze benadering is ideaal wanneer u aangepast servergedrag, git-versiebeheer of lokale IDE-ontwikkeling nodig hebt.

Elke sjabloon voor een gespreksagent bevat een ingebouwde chatgebruikersinterface (hierboven weergegeven) zonder dat er extra instellingen vereist zijn. De chatinterface ondersteunt streamingreacties, markdown-rendering, Databricks-verificatie en optionele permanente chatgeschiedenis.

Eisen

Databricks-apps inschakelen in uw werkruimte. Zie Uw Databricks Apps-werkruimte en -ontwikkelomgeving instellen.

Stap 1. De sjabloon voor de agent-app klonen

Ga aan de slag met behulp van een vooraf samengestelde agentsjabloon vanuit de databricks-app-sjablonenopslagplaats.

In deze zelfstudie wordt gebruikgemaakt van de agent-openai-agents-sdk sjabloon, waaronder:

• Een agent die is gemaakt met de OpenAI Agent SDK
• Starterscode voor een agenttoepassing met een conversationele REST API en een interactieve chatinterface
• Code voor het evalueren van de agent met behulp van MLflow

Kies een van de volgende paden om de sjabloon in te stellen:

Gebruikersinterface van werkruimte

Installeer de app-sjabloon met behulp van de gebruikersinterface van de werkruimte. Hiermee wordt de app geïnstalleerd en geïmplementeerd in een rekenresource in uw werkruimte. Vervolgens kunt u de toepassingsbestanden synchroniseren met uw lokale omgeving voor verdere ontwikkeling.

1. Klik in uw Databricks-werkruimte op + Nieuwe>app.

2. Klik op Agents>Custom Agent (OpenAI SDK).

3. Maak een nieuw MLflow-experiment met de naam openai-agents-template en voltooi de rest van de set om de sjabloon te installeren.

4. Nadat u de app hebt gemaakt, klikt u op de APP-URL om de chatgebruikersinterface te openen.

Nadat u de app hebt gemaakt, downloadt u de broncode naar uw lokale computer om deze aan te passen:

1. Kopieer de eerste opdracht onder De bestanden synchroniseren

   

2. Voer in een lokale terminal de gekopieerde opdracht uit.

Klonen vanuit GitHub

Als u vanuit een lokale omgeving wilt beginnen, kloont u de opslagplaats van de agentsjabloon en opent u de agent-openai-agents-sdk map:

git clone https://github.com/databricks/app-templates.git
cd app-templates/agent-openai-agents-sdk

Stap 2. Inzicht in de agenttoepassing

De agentsjabloon demonstreert een architectuur die gereed is voor productie met deze belangrijke onderdelen. Open de volgende secties voor meer informatie over elk onderdeel:

Open de volgende secties voor meer informatie over elk onderdeel:

Ingebouwde chatinterface

De agentsjabloon haalt de sjabloon voor de chat-app automatisch op en voert deze uit als front-end. Deze chatgebruikersinterface is gebundeld in dezelfde Databricks Apps-implementatie en wordt geleverd naast uw agent, dus er is geen extra installatie vereist.

U kunt de chatgebruikersinterface rechtstreeks in uw project aanpassen. Zie Een chatinterface bouwen en delen met Databricks Apps voor meer informatie over de functies van de chat-app, waaronder het inschakelen van permanente chatgeschiedenis en het verzamelen van feedback van gebruikers.

MLflow AgentServer

Een asynchrone FastAPI-server die agentaanvragen verwerkt met ingebouwde tracering en waarneembaarheid. De AgentServer biedt het eindpunt voor het /responses uitvoeren van query's op uw agent en beheert automatisch aanvraagroutering, logboekregistratie en foutafhandeling.

ResponsesAgent interface

Databricks raadt MLflow ResponsesAgent aan om agents te bouwen. ResponsesAgent hiermee kunt u agents bouwen met elk framework van derden en deze vervolgens integreren met Ai-functies van Databricks voor robuuste logboekregistratie, tracering, evaluatie, implementatie en bewakingsmogelijkheden.

Zie de voorbeelden in de ResponsesAgent voor meer informatie over hoe u een kunt maken.

ResponsesAgent biedt de volgende voordelen:

• Geavanceerde agentmogelijkheden

  • Ondersteuning voor meerdere agents
  • Streaming-uitvoer: Stream de uitvoer in kleinere brokken.
  • Uitgebreide berichtgeschiedenis voor het aanroepen van hulpprogramma's: Meerdere berichten retourneren, inclusief tussenliggende berichten voor bellen via hulpprogramma's, voor verbeterde kwaliteit en gespreksbeheer.
  • Bevestigingsondersteuning bij oproep van tools
  • Ondersteuning voor langdurig werkende tools

• Gestroomlijnde ontwikkeling, implementatie en bewaking

  • Agents creëren met elk framework: Omwikkel een bestaande agent met de ResponsesAgent interface voor directe compatibiliteit met AI Playground, Agent Evaluation en Agent Monitoring.
  • Typed authoring interfaces: Schrijf agentcode met behulp van getypte Python-klassen en profiteer van IDE en notebook autovoltooiing.
  • Automatische tracering: Met MLflow worden gestreamde antwoorden automatisch samengevoegd in traceringen voor een eenvoudigere evaluatie en weergave.
  • Compatibel met het OpenAI-schema: Zie OpenAIResponses: Antwoorden versus ChatCompletion.

OpenAI Agents SDK

De sjabloon maakt gebruik van de OpenAI Agents SDK als agentframework voor gespreksbeheer en indeling van hulpprogramma's. U kunt agents ontwerpen met elk framework. De sleutel is het verpakken van uw agent met de MLflow-interface ResponsesAgent .

MCP-servers (Model Context Protocol)

De sjabloon maakt verbinding met Databricks MCP-servers om agents toegang te geven tot hulpprogramma's en gegevensbronnen. Zie McP (Model Context Protocol) op Databricks.

Agents ontwikkelen met AI-coderingsassistenten

Databricks raadt aan ai-coderingsassistenten zoals Claude, Cursor en Copilot te gebruiken om agents te ontwerpen. Gebruik de opgegeven agentvaardigheden in /.claude/skillsen het AGENTS.md bestand om AI-assistenten inzicht te geven in de projectstructuur, beschikbare hulpprogramma's en best practices. Agents kunnen deze bestanden automatisch lezen om de Databricks-apps te ontwikkelen en te implementeren.

Stap 3. Tools bij uw agent toevoegen

Geef uw agent mogelijkheden, zoals het opvragen van databases, het doorzoeken van documenten of het aanroepen van externe API's door deze te verbinden met MCP-servers. De agentsjabloon bevat een standaard MCP-serververbinding. Als u meer hulpprogramma's wilt toevoegen, configureert u extra MCP-servers in uw agentcode en verleent u de vereiste machtigingen in databricks.yml.

Zie ai-agenthulpprogramma's voor ondersteunde hulpprogrammatypen en codevoorbeelden.

Definieer lokale Python-functiehulpmiddelen

Voor bewerkingen waarvoor geen externe gegevensbronnen of API's nodig zijn, definieert u hulpprogramma's rechtstreeks in uw agentcode. Deze hulpprogramma's worden uitgevoerd in hetzelfde proces als uw agent en zijn handig voor gegevenstransformaties, berekeningen of hulpprogrammabewerkingen.

OpenAI Agents SDK

Gebruik de @function_tool decorator van de OpenAI Agents SDK:

from agents import Agent, function_tool

@function_tool
def get_current_time() -> str:
    """Get the current date and time."""
    from datetime import datetime
    return datetime.now().isoformat()

agent = Agent(
    name="My agent",
    instructions="You are a helpful assistant.",
    model="databricks-claude-sonnet-4-5",
    tools=[get_current_time],
)

LangGraph

Gebruik de @tool decorator van LangChain:

from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent
from databricks_langchain import ChatDatabricks

@tool
def get_current_time() -> str:
    """Get the current date and time."""
    from datetime import datetime
    return datetime.now().isoformat()

agent = create_react_agent(
    ChatDatabricks(endpoint="databricks-claude-sonnet-4-5"),
    tools=[get_current_time],
)

Voor lokale functiehulpprogramma's zijn geen resourcetoelagen databricks.yml vereist omdat ze worden uitgevoerd binnen het agentproces.

Stap 4. LLM-gebruik beheren van uw agents in Databricks-apps met Unity AI Gateway

Routeer de LLM-aanroepen van uw agent via AI Gateway (bèta), zodat elke aanvraag wordt beheerd door dezelfde besturingselementen, ongeacht welke provider het beantwoordt. Met de gateway in het aanvraagpad kunt u machtigingen, kenmerkkosten per app centraliseren, modellen wisselen en verkeer inspecteren of opnieuw afspelen zonder agentcode te wijzigen of providerreferenties te roteren.

1. Schakel AI Gateway in uw werkruimte in. AI Gateway wordt aangemeld tijdens de bètaversie. Een accountbeheerder moet deze inschakelen vanaf de pagina Previews van de accountconsole voordat u gateway-eindpunten kunt maken of er query's op kunt uitvoeren. Zie Azure Databricks previews beheren.

2. Wijs uw agent aan op een AI Gateway-eindpunt. Geef in de agentcode de naam van het AI Gateway-eindpunt door als het argument model en stel use_ai_gateway=True in op de Azure Databricks LLM-client. De client stuurt verkeer via de gateway en verwerkt verificatie automatisch.

   OpenAI

   from agents import Agent, set_default_openai_api, set_default_openai_client
   from databricks_openai import AsyncDatabricksOpenAI
   
   set_default_openai_client(AsyncDatabricksOpenAI(use_ai_gateway=True))
   set_default_openai_api("chat_completions")
   
   agent = Agent(
       name="Agent",
       instructions="You are a helpful assistant.",
       model="<ai-gateway-endpoint>",
   )
   

   LangGraph

   from databricks_langchain import ChatDatabricks
   
   llm = ChatDatabricks(
       model="<ai-gateway-endpoint>",
       use_ai_gateway=True,
   )
   

   Zie Query Unity AI Gateway-eindpunten voor aanvullende API-functionaliteiten (OpenAI-antwoorden-API, Anthropic Berichten-API, Google Gemini) en REST-voorbeelden.

Geavanceerde auteurschapsonderwerpen

{
  "delta": …,
  "databricks_output": {
    "trace": {...},
    "error": {
      "error_code": BAD_REQUEST,
      "message": "TimeoutException: Tool XYZ failed to execute."
    }
  }
}

Stap 5. De agent-app lokaal uitvoeren

Uw lokale omgeving instellen:

1. Installeer uv (Python package manager), nvm (Node Version Manager) en de Databricks CLI:

   • uv Installatie
   • nvm Installatie
   • Voer het volgende uit om Node 20 LTS te gebruiken:

     nvm use 20
     

   • databricks CLI Installatie

2. Wijzig de map in de agent-openai-agents-sdk map.

3. Voer de opgegeven quickstartscripts uit om afhankelijkheden te installeren, uw omgeving in te stellen en de app te starten.

   uv run quickstart
   uv run start-app
   

Open in een browser http://localhost:8000 om de ingebouwde chatinterface te openen en te beginnen met chatten met de agent.

Stap 6. Verificatie configureren

Uw agent heeft verificatie nodig voor toegang tot Azure Databricks resources. Databricks Apps biedt twee verificatiemethoden: app-autorisatie (service-principal) en gebruikersautorisatie (namens de gebruiker). U kunt er een configureren via de gebruikersinterface van de werkruimte of declaratief in databricks.yml met Declarative Automation-bundles. De agentsjablonen worden meegeleverd met een databricks.yml, zodat dat pad de standaard is wanneer u begint met een sjabloon.

Zie databricks.yml voor een volledig overzicht, inclusief alle ondersteunde resourcetypen, machtigingswaarden en een end-to-end-overzicht.

App-autorisatie (standaard)

App-autorisatie maakt gebruik van een service-principal die Azure Databricks automatisch aanmaakt voor uw app. Alle gebruikers delen dezelfde machtigingen.

Declareer alle bronnen die de agent onder resources.apps.<app>.resources in databricks.yml gebruikt. Implementeer de bundel om de service-principal de gedeclareerde machtigingen te verlenen:

resources:
  apps:
    agent_openai_agents_sdk:
      name: 'agent-openai-agents-sdk'
      source_code_path: ./
      config:
        command: ['uv', 'run', 'start-app']
        env:
          - name: MLFLOW_TRACKING_URI
            value: 'databricks'
          - name: MLFLOW_REGISTRY_URI
            value: 'databricks-uc'
          - name: MLFLOW_EXPERIMENT_ID
            value_from: 'experiment'
      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'
        - name: 'llm'
          serving_endpoint:
            name: 'databricks-claude-sonnet-4-5'
            permission: 'CAN_QUERY'

databricks bundle deploy
databricks bundle run agent_openai_agents_sdk

Zie App-autorisatie voor de volledige lijst met resourcetypen.

Gebruikersautorisatie

Met gebruikersautorisatie kan uw agent handelen met de afzonderlijke machtigingen van elke gebruiker. Gebruik deze optie wanneer u toegangsbeheer per gebruiker of audittrails nodig hebt.

Voeg deze code toe aan uw agent:

from agent_server.utils import get_user_workspace_client

# In your agent code (inside @invoke or @stream)
user_workspace = get_user_workspace_client()

# Access resources with the user's permissions
response = user_workspace.serving_endpoints.query(name="my-endpoint", inputs=inputs)

Configureer welke Azure Databricks API's de agent kan aanroepen namens de gebruiker door autorisatieniveaus toe te voegen onder user_api_scopes op de app in databricks.yml.

resources:
  apps:
    agent_openai_agents_sdk:
      name: 'agent-openai-agents-sdk'
      source_code_path: ./
      user_api_scopes:
        - sql
        - dashboards.genie
        - serving.serving-endpoints

databricks bundle deploy
databricks bundle run agent_openai_agents_sdk

Zie Gebruikersautorisatie voor de lijst met beschikbare rechten en volledige instructies voor setup.

Stap 7. De agent evalueren

De sjabloon bevat agentevaluatiecode. Zie agent_server/evaluate_agent.py voor meer informatie. Evalueer de relevantie en veiligheid van de reacties van uw agent door het volgende uit te voeren in een terminal:

uv run agent-evaluate

Stap 8. De agent implementeren in Databricks-apps

Nadat u verificatie hebt geconfigureerd, implementeert u uw agent in Azure Databricks. De agentsjablonen gebruiken Databricks Asset Bundles (DABs) voor implementatie. Het databricks.yml bestand in de sjabloon definieert de app-configuratie en resourcemachtigingen. Zorg ervoor dat de Databricks CLI is geïnstalleerd en geconfigureerd.

1. Valideer de bundelconfiguratie om fouten te ondervangen voordat u implementeert:

   databricks bundle validate
   

2. Implementeer de bundel. Hiermee uploadt u uw code en configureert u resources (MLflow-experiment, het leveren van eindpunten enzovoort) die zijn gedefinieerd in databricks.yml:

   databricks bundle deploy
   

3. Start de app of start deze opnieuw:

   databricks bundle run agent_openai_agents_sdk
   

   Notitie

   bundle deploy uploadt alleen bestanden en configureert resources. bundle run is vereist om de app te starten of opnieuw te starten met de nieuwe code.

Voor toekomstige updates voert u databricks bundle deploy uit en zet u vervolgens opnieuw databricks bundle run agent_openai_agents_sdk in.

Stap 9. Een query uitvoeren op de ingezette agent

In het volgende voorbeeld wordt een snelle curl aanvraag met een OAuth-token gebruikt. Persoonlijke toegangstokens (PAT's) worden niet ondersteund voor Databricks-apps.

Zie Query van een agent die is geïmplementeerd op Azure Databricks voor de volledige lijst met querymethoden, waaronder de Databricks OpenAI-client en REST API.

Genereer een OAuth-token met behulp van de Databricks CLI:

databricks auth login --host <https://host.databricks.com>
databricks auth token

Gebruik het token om een query uit te voeren op de agent:

curl -X POST <app-url.databricksapps.com>/responses \
   -H "Authorization: Bearer <oauth token>" \
   -H "Content-Type: application/json" \
   -d '{ "input": [{ "role": "user", "content": "hi" }], "stream": true }'

Beperkingen

• Alleen middelgrote en grote computergrootten worden ondersteund. Zie Rekenresources configureren voor een Databricks-app.
• De MLflow Review App Chat-gebruikersinterface biedt momenteel geen ondersteuning voor agents die zijn geïmplementeerd in Databricks-apps. Als u bestaande traceringen wilt evalueren, gebruikt u labelsessies, die werken ongeacht de implementatiemethode. Databricks bouwt ondersteuning voor beoordeling en feedback rechtstreeks in de chatbotsjabloon.

Volgende stappen 

• Uw Databricks Apps-agent load testen