Agent Bricks CLI

Important

Deze functie bevindt zich in de bètaversie. Er is geen werkruimte-instelling nodig om het in te schakelen. Installeer de Agent Bricks CLI om te beginnen.

De Agent Bricks CLI (databricks-agentbricks) is een Azure Databricks-commandoregeltool voor ontwikkelaars die aangepaste agents in code bouwen en uitrollen.

De Agent Bricks CLI is een codegerichte manier om aangepaste agenten via de terminal te bouwen. De Agent Bricks CLI ondersteunt een project met een ingebouwd framework gebaseerd op de best practices van Databricks. Daarna kan het het project lokaal uitvoeren voor testen en het uitrollen naar de runtime van de Azure Databricks agent. De CLI stelt je in staat om van een lege map naar een gedeployeerde agent te gaan zonder runtime, tools, geheugen en beheerde resources handmatig te hoeven aanleggen. Voor andere manieren om aangepaste agents te bouwen, waaronder de app-gebaseerde workflow, zie Agents uitvoeren op Databricks Apps met de legacy agent server.

Prerequisites

  • De Databricks CLI, geïnstalleerd en beschikbaar in je PATH.

  • Python 3.10 of hoger, met pip.

  • Installeer de Agent Bricks CLI:

    pip install databricks-agentbricks

De levenscyclus van de Agent Bricks CLI

De Agent Bricks CLI genereert op basis van een frameworksjabloon een lokale directory met implementeerbare agentcode, waarbij de runtime, tests en een optionele chat-UI al zijn geïntegreerd. Je schrijft de applicatielogica (model, tools en prompts), en de CLI verzorgt het lokaal uitvoeren en uitrollen naar de infrastructuur van Azure Databricks.

agent.tomlis de declaratieve bron van waarheid voor alle door Azure Databricks beheerde resources waarop uw agent vertrouwt: tool bindings (data sandbox, managed Model Context Protocol (MCP) services, Unity Catalog functions), en geheugen-, sessie- en traceerbronnen. agentbricks deploy leest het om alles te provisioneren en aan elkaar te koppelen, zodat het bestand, en niet handmatig geschreven configuratiecode, voor de uitrol zorgt.

De drie commando's die een agent van een lege directory naar productie brengen:

  • agentbricks init zet het project op basis van een meegeleverde sjabloon op, waarbij optioneel een .env-bestand wordt gevuld met een Databricks-profiel zodat het project meteen kan worden uitgevoerd.
  • agentbricks devDraait de agent lokaal tegen Azure Databricks model serving zodat je hem kunt testen voordat je hem uitrolt.
  • agentbricks deploy richt de resources in die in agent.toml zijn gedeclareerd en rolt de agent uit naar de Azure Databricks agent runtime.

Agent Bricks CLI-levenscyclus: init, dev en deploy fasen met hun belangrijkste acties

Note

Je kunt ook tools toevoegen en geheugen- en sessieopslag op elk moment binden, niet alleen bij init. Gebruik agentbricks tools add, agentbricks memory bind, en agentbricks sessions bind om je agentconfiguratie bij te werken tussen een van deze stappen.

Agent Bricks CLI-mogelijkheden

Capability Description
Toegang tot modellen De Agent Bricks CLI zorgt automatisch voor modeltoegang zodat je agent een Azure Databricks-bediend model kan aanroepen zonder inloggegevens of endpoints te beheren. Zie Databricks Foundation-model-API's.
Beheerd geheugen Langetermijngeheugens die een agent kan schrijven en doorzoeken, gepartitioneerd per actor en ondersteund door beheerde opslagplaatsen. Gebruik het geheugen om feiten en voorkeuren over sessies heen te behouden. Zie het geheugen van de beheerde agent.
Beheerde sessies Gesprektranscripties worden bewaard in beheerde sessieopslagen en gepartitioneerd per actor, met ondersteuning voor het forken van sessies in onafhankelijke kopieën. Zie sessies met beheerde agenten.
Tools Azure Databricks-beheerde capabilities gedeclareerd inagent.toml: een verkleinde Unity Catalog sandbox, een door Azure Databricks beheerde MCP-service, of een Unity Catalog-functie. Aangepaste Python-tools worden direct in de projectcode geschreven. Zie MCPs.
Tracing MLflow-tracering die standaard aan staat, waarbij de traces van elke run worden doorgestuurd naar een MLflow-experiment per project voor debugging en monitoring. Zie Overzicht van tracering.
Implementatie Deployt een agent naar de runtime van de Azure Databricks agent, verleent de agent service principal toegang tot bound stores en beheert de implementatielevenscyclus.

Maak een nieuwe agent aan

Stap 1: Authenticatie met OAuth en sla een profiel op

De Agent Bricks CLI gebruikt Databricks CLI-authenticatie. Authenticeer je bij je werkruimte met OAuth (user-to-machine) en sla de inloggegevens op als een benoemd profiel.

Om de OAuth-flow te starten, voer je het volgende uit en vervang je de host door je workspace-URL. Het commando opent een browser om het aanmelden te voltooien, en schrijft vervolgens het profiel naar ~/.databrickscfg:

databricks auth login --host https://<your-workspace-url> --profile <profile>

Om dat profiel als standaard voor de CLI in te stellen, zodat --profile in latere opdrachten kan worden weggelaten, voer je het volgende uit:

agentbricks login --profile <profile>

agentbricks login verifieert de referenties van het profiel. Als ze ontbreken of worden afgewezen, voert de CLI databricks auth login opnieuw uit en probeert het opnieuw.

Stap 2: Zet het agentproject op

Maak een nieuw agentproject aan en geef --framework op om de sjabloon te kiezen. Dit voorbeeld gebruikt de LangGraph-sjabloon, die een browserchat-app bevat:

agentbricks init --framework langgraph my-agent
cd my-agent

De CLI wordt per framework met één gebundelde template geleverd, en --framework bepaalt op basis van welke template wordt gescaffold: langgraph voor LangGraph of openai voor de OpenAI Agents SDK. De CLI schrijft de beheerde bronnen en toolbindings van het project naar agent.toml en sjabloonherkomst naar .agentbricks/project.toml. Om de backend met alleen API zonder de chat-app op te zetten, voeg --disable-chat-app toe.

Stap 3: Voeg beheerde sessie- en geheugenopslagen toe

Koppel beheerde opslagplaatsen zodat je agent de gespreksgeschiedenis en het langetermijngeheugen kan opslaan. Elk commando registreert de winkelnaam in agent.toml en maakt de store aan als die niet bestaat.

Om een sessieopslag en een geheugenopslag te binden, voer je het volgende uit:

agentbricks sessions bind my-agent-sessions
agentbricks memory bind my-agent-memory

Stap 4: Bekijk tracering

Tracing staat standaard aan. agentbricks init bindt een standaard /Shared/agentbricks_traces/<project> MLflow-experiment en agentbricks devagentbricks deploy stuurt de traces van elke run ernaartoe.

Om traces weer te geven nadat je agent er een paar heeft gegenereerd, voer je het volgende uit:

agentbricks tracing list

Om een specifiek MLflow-experiment te koppelen, voer agentbricks tracing bind --experiment-id <experiment-id> uit. Om het traceren uit te schakelen, ren agentbricks tracing unbind.

Stap 5: Voer de agent lokaal uit

Voer de agent op je machine uit om hem te testen voordat je hem uitrolt.

agentbricks dev

Dit start een lokale server op poort 8000 met dezelfde commando en omgeving als de runtime van de Azure Databricks agent. De Agent Bricks CLI verbindt de agent met Azure Databricks model serving zodat het model lokaal kan aanroepen. De template stelt een standaardmodel in als de MODEL waarde in agent/agent.py. Om een ander model te gebruiken, bewerk die waarde. Stuur verzoeken naar http://localhost:8000 om met de agent te communiceren.

Stap 6: Zet de agent in

Deploy de agent naar de Azure Databricks agent runtime. De CLI richt de gekoppelde opslagservices in, geeft de service-principal van de agent toegang tot deze services en rolt de implementatie uit. De ingezette agent heet agent-bricks-<name>.

agentbricks deploy my-agent

Wanneer de implementatie is voltooid, retourneert de CLI de URL van de deployment. Open die URL om te communiceren met je live agent, die automatisch verbonden is met de Azure Databricks modelservice. Om de uitrol daarna te beheren, gebruik je de agentbricks deployments commando's zoals agentbricks deployments logs en agentbricks deployments stop.

Breng een bestaande agent mee

Als je al een agent hebt gebouwd met LangGraph of de OpenAI Agents SDK, gebruik dan de --existing vlag om deze naar de Agent Bricks CLI te verplaatsen en DurableAgentServer. De CLI herschrijft je code niet. In plaats daarvan bereidt het migratie-instructies voor die een codeeragent, zoals Claude Code of Codex, volgen om het project om te zetten.

Stap 1: Bereid de migratie voor

Bereid vanuit de projectmap van de agent de migratie voor. Geef het framework dat de agent gebruikt: langgraph voor LangGraph of openai voor de OpenAI Agents SDK.

agentbricks init --framework langgraph --existing .

De CLI schrijft een agent-bricks-migrate/ map die de migratie-instructies bevat, een prompt voor je codeeragent en een referentieproject dat is gegenereerd uit de templates van de CLI. Het voegt ook vaardigheden in .claude/skills/ en .agent/skills/ toe die codeeragenten naar de instructies verwijzen. Het commando verandert je applicatiecode, afhankelijkheden of het .env-bestand niet, en creëert geen resources in je werkruimte.

Stap 2: Converteer het project met je codeeragent

Plak de prompt uit agent-bricks-migrate/ in je codeeragent. De coding agent zet het project om om agent.toml en een DurableAgentServer-entrypoint te gebruiken, en verifieert de conversie.

Stap 3: Controleer de conversie

Voer agentbricks doctor uit in de projectmap:

agentbricks doctor .

agentbricks doctorinspecteert de bestanden van het project zonder de code uit te voeren of contact op te nemen met Azure Databricks. Dit werkt wanneer het project een geldige agent.tomlheeft, DurableAgentServer start met een invoke handler en de adapter voor zijn framework aanroept. Een mislukte rapportage betekent dat de conversie niet voltooid is.

Stap 4: Opschonen, uitvoeren en uitrollen

Verwijder agent-bricks-migrate/ en de twee skills die ernaar verwijzen, en neem ze niet op in je commits. Voer dan de agent uit met agentbricks dev en deploy hem met agentbricks deploy.

Considerations

  • --existing ondersteunt LangGraph en de OpenAI Agents SDK met DurableAgentServer. Het ondersteunt geen --server custom.
  • Het overzetten van de agent naar een beheerde sessieopslag verplaatst zijn bestaande gespreksgeschiedenis niet. De migratie-instructies vragen je te beslissen hoe je eerdere gesprekken wilt afhandelen.
  • De --disable-chat-app, --memory-store, en --session-store opties bepalen het referentieproject. Ze creëren geen resources.

Voeg MCP-tools toe

Als je je agent bouwt met de Agent Bricks CLI, voeg dan een ingebouwde system.ai MCP-service toe aan je project met agentbricks tools add mcp. Het commando controleert of de service in je werkruimte bestaat en registreert de tool in agent.toml. De agent maakt tijdens runtime verbinding met de tool, dus je schrijft geen verbindingscode.

Om de MCP-diensten die je kunt toevoegen op te sommen, voer je het volgende commando uit:

agentbricks tools list --kind mcp

De volgende voorbeelden voegen gemeenschappelijke ingebouwde diensten toe:

# Answer analytics questions across your workspace with Genie One.
agentbricks tools add mcp system.ai.genie_one_mcp

# Run SQL on a SQL warehouse.
agentbricks tools add mcp system.ai.dbsql

# Connect to third-party applications.
agentbricks tools add mcp system.ai.slack
agentbricks tools add mcp system.ai.github

Standaard draait een tool met de rechten van de gebruiker die het verzoek naar je agent heeft gestuurd. Om het in plaats daarvan als de service-principal van de app uit te voeren, voeg --auth app toe Voor Google Drive, Gmail, Google Agenda en Microsoft 365 voltooit elke gebruiker een eenmalige OAuth-login vóór de eerste aanroep. Zie Verbonden apps.

Om tools te beoordelen of te verwijderen, start agentbricks tools list of agentbricks tools remove mcp <service>.

Voor andere hulpmiddelen, zie de volgende pagina's:

agent.toml Referentie

agent.tomlis de declaratieve bron van waarheid voor de door Azure Databricks beheerde bronnen die jouw agent gebruikt. agentbricks init maakt het aan, agentbricks tools add, agentbricks memory bind, agentbricks sessions bind, en agentbricks tracing bind werken het bij, en agentbricks deploy leest het om resources te provisioneren en toegang te verlenen. Je kunt het ook direct bewerken.

Sectie of veld Description
schema_version De versie van het agent.toml format. Gegenereerde projecten gebruiken 1.
[agent] framework De raamwerktemplate: langgraph of openai.
[agent] server De agentserver: agentbricks voor DurableAgentServer, of custom voor je eigen server.
[memory_store] name De beheerde geheugenopslag die de agent gebruikt.
[session_store] name De beheerde sessieopslag die de agent gebruikt.
[tracing] experiment_name Het MLflow-experiment voor traces. Verwijder het gedeelte om tracering uit te schakelen.
[[tools]] Een toolbinding. Elk hulpmiddel heeft een id, een auth waarde van user of app, en een source die het gereedschap identificeert, plus een optionele policy.
[auth.user] autorisatie van de gebruiker aanvragen voor tools die je in code schrijft: required en additional_api_scopes. Zie Request-user authorization.

Het volgende voorbeeld is het bestand dat agentbricks init genereert voor een LangGraph-agent met de naam my-agent:

schema_version = 1

[agent]
framework = "langgraph"
server = "agentbricks"

[memory_store]
name = "my-agent-memory"

[session_store]
name = "my-agent-session"

[tracing]
experiment_name = "/Shared/agentbricks_traces/my-agent"

Het volgende voorbeeld toont toolbindings die door agentbricks tools add worden geschreven: een ingebouwde MCP-service, een Genie Agent en een sandbox die in één tabel is gescoped:

[[tools]]
id = "web_search"
auth = "user"
source = { kind = "mcp", service = "system.ai.web_search" }

[[tools]]
id = "genie_agent"
auth = "user"
source = { kind = "genie_agent", space_id = "<space-id>" }

[[tools]]
id = "sandbox"
auth = "user"
source = { kind = "sandbox", service = "system.ai.sandbox" }
policy = { downscope = [{ resource = "table:samples.nyctaxi.trips", permission = "read_only" }] }

Hulpmiddelen die een Unity Catalog-functie aanroepen gebruiken source = { kind = "uc_function", function = "<catalog>.<schema>.<function>" } en ondersteunen alleen auth = "app".

Opdrachtenoverzicht

Voor de volledige, actuele commandoreferentie met alle commando's en vlaggen raadpleegt u de Agent Bricks CLI README op GitHub.

Aanvullende bronnen

  • Laatst bijgewerkt om