Skapa en AI-agent och distribuera den i Databricks-appar

Skapa en AI-agent och distribuera den med databricks-appar. Med Databricks Apps får du fullständig kontroll över agentkoden, serverkonfigurationen och distributionsarbetsflödet. Den här metoden är perfekt när du behöver anpassat serverbeteende, git-baserad versionshantering eller lokal IDE-utveckling.

Varje mall för konversationsagent innehåller ett inbyggt chattgränssnitt (visas ovan) utan ytterligare konfiguration. Chattgränssnittet stöder strömningssvar, markdown-rendering, Databricks-autentisering och valfri beständig chatthistorik.

Krav

Aktivera Databricks-appar på din arbetsyta. Se Konfigurera din Databricks Apps-arbetsyta och utvecklingsmiljö.

Steg 1. Klona agentapp-mallen

Kom igång med en fördefinierad agentmall från lagringsplatsen för Databricks-appmallar.

I den här självstudien används mallen agent-openai-agents-sdk, som innehåller:

• En agent som skapats med OpenAI Agent SDK
• Startkod för ett agentprogram med ett konversations-REST API och ett interaktivt chattgränssnitt
• Kod för att utvärdera agenten med MLflow

Välj någon av följande sökvägar för att konfigurera mallen:

Användargränssnitt för arbetsutrymme

Installera appmallen med hjälp av arbetsytans användargränssnitt. Detta installerar appen och distribuerar den till en beräkningsresurs på din arbetsyta. Du kan sedan synkronisera programfilerna till din lokala miljö för vidare utveckling.

1. Klicka på + Ny>App på Databricks-arbetsytan.

2. Klicka på Anpassad agent>Agent (OpenAI SDK).

3. Skapa ett nytt MLflow-experiment med namnet openai-agents-template och slutför resten av konfigurationen för att installera mallen.

4. När du har skapat appen klickar du på appens URL för att öppna chattgränssnittet.

När du har skapat appen laddar du ned källkoden till den lokala datorn för att anpassa den:

1. Kopiera det första kommandot under Synkronisera filerna

   

2. Kör det kopierade kommandot i en lokal terminal.

Klona från GitHub

Om du vill börja från en lokal miljö klonar du lagringsplatsen för agentmallen agent-openai-agents-sdk och öppnar katalogen:

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

Steg 2. Förstå agentprogrammet

Agentmallen visar en produktionsklar arkitektur med dessa nyckelkomponenter. Öppna följande avsnitt för mer information om varje komponent:

Öppna följande avsnitt för mer information om varje komponent:

Inbyggt chattgränssnitt

Agentmall hämtar och kör chattappmallen automatiskt som frontend. Det här chattgränssnittet paketeras i samma Databricks Apps-distribution och hanteras tillsammans med din agent, så det krävs ingen ytterligare konfiguration.

Du kan anpassa chattgränssnittet direkt i projektet. Mer information om chattappens funktioner, inklusive hur du aktiverar beständig chatthistorik och insamling av användarfeedback finns i Skapa och dela ett chattgränssnitt med Databricks Apps.

MLflow AgentServer

En asynkron FastAPI-server som hanterar agentbegäranden med inbyggd spårning och observerbarhet. AgentServer tillhandahåller /responses slutpunkten för att fråga din agent och hanterar automatiskt routning, loggning och felhantering av begäranden.

ResponsesAgent Gränssnitt

Databricks rekommenderar MLflow ResponsesAgent för att skapa agenter. ResponsesAgent låter dig skapa agenter med alla ramverk från tredje part och sedan integrera dem med Databricks AI-funktioner för robust loggning, spårning, utvärdering, distribution och övervakning.

Information om hur du skapar en ResponsesAgentfinns i exemplen i MLflow-dokumentationen – ResponsesAgent för modellservering.

ResponsesAgent ger följande fördelar:

• Avancerade agentfunktioner

  • Stöd för flera agenter
  • Strömmande utdata: Strömma utdata i mindre segment.
  • Omfattande meddelandehistorik för verktygssamtal: Returnera flera meddelanden, inklusive mellanliggande verktygssamtalsmeddelanden, för bättre kvalitet och konversationshantering.
  • Stöd för bekräftelse av verktygsanrop
  • Stöd för långvariga verktyg

• Effektiviserad utveckling, distribution och övervakning

  • Skapa agenter med valfritt ramverk: Omslut alla befintliga agenter med ResponsesAgent-gränssnittet för att få standardkompatibilitet med AI Playground, agentutvärdering och agentövervakning.
  • Typed authoring interfaces: Skriv agentkod med använda typade Python-klasser och dra nytta av autokomplettering i IDE och notebook.
  • Automatisk spårning: MLflow aggregerar automatiskt strömmade svar i spårningar för enklare utvärdering och visning.
  • Kompatibel med OpenAI-schematResponses: Se OpenAI: Responses vs. ChatCompletion.

OpenAI Agents SDK

Mallen använder OpenAI Agents SDK som agentramverk för konversationshantering och verktygsorkestrering. Du kan skapa agenter med valfritt ramverk. Det viktiga är att omsluta din agent med MLflow-gränssnittet ResponsesAgent.

MCP-servrar (Model Context Protocol)

Mallen ansluter till Databricks MCP-servrar för att ge agenter åtkomst till verktyg och datakällor. Se McP (Model Context Protocol) på Databricks.

Skapa agenter med hjälp av AI-kodningsassistenter

Databricks rekommenderar att du använder AI-kodningsassistenter som Claude, Cursor och Copilot för att skapa agenter. Använd de tillhandahållna agentkunskaperna i /.claude/skillsoch AGENTS.md filen för att hjälpa AI-assistenter att förstå projektstrukturen, tillgängliga verktyg och metodtips. Agenter kan automatiskt läsa dessa filer för att utveckla och distribuera Databricks-apparna.

Steg 3. Lägga till verktyg i din agent

Ge din agent funktioner som att fråga databaser, söka i dokument eller anropa externa API:er genom att ansluta den till MCP-servrar. Agentmallen innehåller en STANDARD-MCP-serveranslutning. Om du vill lägga till fler verktyg konfigurerar du ytterligare MCP-servrar i agentkoden och beviljar nödvändiga behörigheter i databricks.yml.

Se AI-agentverktyg för verktygstyper och kodexempel som stöds.

Define lokala Python funktionsverktyg

För åtgärder som inte kräver externa datakällor eller API:er definierar du verktyg direkt i agentkoden. Dessa verktyg körs i samma process som din agent och är användbara för datatransformeringar, beräkningar eller verktygsåtgärder.

OpenAI Agents SDK

Använd dekoratören @function_tool från 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

Använd dekoratören @tool från 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],
)

Lokala funktionsverktyg kräver inte resursbidrag eftersom databricks.yml de körs i agentprocessen.

Steg 4. Styra LLM-användning från dina agenter i Databricks-appar med Unity AI Gateway

Dirigera agentens LLM-anrop via AI Gateway (Beta) så att varje begäran styrs av samma kontroller oavsett vilken leverantör som svarar på den. Med gatewayen i begärandesökvägen kan du centralisera behörigheter, attributkostnad per app, växla modeller och inspektera eller spela upp trafik utan att ändra agentkoden eller rotera providerautentiseringsuppgifterna.

1. Aktivera AI Gateway på din arbetsyta. AI Gateway är valfri under betaversionen. En kontoadministratör måste aktivera det från sidan förhandsvyer i kontokonsolen innan du kan skapa eller utföra frågor mot gatewayslutpunkter. Se Hantera förhandsversioner av Azure Databricks.

2. Rikta din agent mot en AI Gateway-slutpunkt. I agentkoden skickar du namnet på AI Gateway-slutpunkten som argumentet model och anger use_ai_gateway=True på Azure Databricks LLM-klienten. Klienten dirigerar trafik via gatewayen och hanterar autentisering automatiskt.

   OpenAI (på engelska)

   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,
   )
   

   Ytterligare API-ytor (OpenAI Responses API, Anthropic Messages API, Google Gemini) och REST-exempel finns i Query Unity AI Gateway-slutpunkter.

Avancerade redigeringsämnen

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

Steg 5. Köra agentappen lokalt

Konfigurera din lokala miljö:

1. Installera uv (Python package manager), nvm (Node Version Manager) och Databricks CLI:

   • uv Installation
   • nvm Installation
   • Kör följande för att använda Node 20 LTS:

     nvm use 20
     

   • databricks CLI Installation

2. Ändra katalogen till agent-openai-agents-sdk mappen.

3. Kör de angivna snabbstartsskripten för att installera beroenden, konfigurera din miljö och starta appen.

   uv run quickstart
   uv run start-app
   

I en webbläsare, gå till http://localhost:8000 för att öppna det inbyggda chattgränssnittet och börja chatta med agenten.

Steg 6. Konfigurera autentisering

Din agent behöver autentisering för att få åtkomst till Azure Databricks resurser. Databricks Apps innehåller två autentiseringsmetoder: appauktorisering (tjänstens huvudnamn) och användarauktorisering (å användarens vägnar). Du kan konfigurera dem antingen via arbetsytans användargränssnitt eller deklarativt i databricks.yml med deklarativa Automatiseringspaket. Agentmallarna levereras med en databricks.yml, så att sökvägen är standard när du börjar från en mall.

Fullständig referens, inklusive alla resurstyper som stöds, behörighetsvärden och en genomgång från slutpunkt till slutpunkt databricks.yml , finns i Autentisering för AI-agenter.

Appauktorisering (standard)

Appauktorisering använder ett huvudnamn för tjänsten som Azure Databricks skapar automatiskt för din app. Alla användare har samma behörigheter.

Deklarera varje resurs som agenten använder under resources.apps.<app>.resources i databricks.yml. Distribuera paketet för att ge tjänstens huvudnamn de deklarerade behörigheterna:

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

En fullständig lista över resurstyper finns i Appauktorisering.

Användarauktorisering

Med användarauktorisering kan din agent agera med varje användares individuella behörigheter. Använd detta när du behöver åtkomstkontroll per användare eller spårningsloggar.

Lägg till den här koden i din 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)

Konfigurera vilka Azure Databricks API:er som agenten kan anropa åt användaren genom att lägga till omfång under user_api_scopes i appen i 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

En lista över tillgängliga omfång och fullständiga installationsinstruktioner finns i Användarauktorisering.

Steg 7. Utvärdera agenten

Mallen innehåller agentutvärderingskod. Mer information finns i agent_server/evaluate_agent.py. Utvärdera relevansen och säkerheten för agentens svar genom att köra följande i en terminal:

uv run agent-evaluate

Steg 8. Distribuera agenten till Databricks-applikationer

När du har konfigurerat autentisering distribuerar du din agent till Azure Databricks. Agentmallarna använder Databricks Asset Bundles (DAB) för distribution. Filen databricks.yml i mallen definierar appkonfigurationen och resursbehörigheterna. Kontrollera att Databricks CLI är installerat och konfigurerat.

1. Verifiera paketkonfigurationen för att fånga upp fel innan du distribuerar:

   databricks bundle validate
   

2. Distribuera paketet. Detta laddar upp koden och konfigurerar resurser (MLflow-experiment, serveringsslutpunkter och så vidare) som definierats i databricks.yml:

   databricks bundle deploy
   

3. Starta eller starta om appen:

   databricks bundle run agent_openai_agents_sdk
   

   Anteckning

   bundle deploy laddar bara upp filer och konfigurerar resurser. bundle run krävs för att starta eller starta om appen med den nya koden.

För framtida uppdateringar, kör databricks bundle deploy och följ sedan med databricks bundle run agent_openai_agents_sdk för att distribuera om.

Steg 9. Fråga den distribuerade agenten

I följande exempel används en snabbbegäran curl med en OAuth-token. Personliga åtkomsttoken (PAT) stöds inte för Databricks-appar.

Den fullständiga listan över frågemetoder, inklusive Databricks OpenAI-klienten och REST-API:et, finns i Query an agent deployed on Azure Databricks.

Generera en OAuth-token med databricks CLI:

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

Använd token för att fråga agenten:

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 }'

Begränsningar

• Endast medelstora och stora beräkningsstorlekar stöds. Se Konfigurera beräkningsresurser för en Databricks-app.
• Användargränssnittet för MLflow Review App Chat stöder för närvarande inte agenter som distribueras i Databricks-appar. Om du vill utvärdera befintliga spårningar använder du etiketteringssessioner som fungerar oavsett distributionsmetod. Databricks skapar stöd för granskning och feedback direkt i chattrobotmallen.

Nästa steg

• Belastningstesta din Databricks Apps-agent