Agent Runtime

Agent Runtime runs your agent on Azure Databricks-hosted serverless compute. It runs your agent server, such as DurableAgentServer, on Databricks Apps, so you deploy code instead of provisioning servers. To learn how Agent Runtime fits with your framework and agent server, see Deploy agents on Azure Databricks.

What Agent Runtime provides

  • A stable, authenticated endpoint: Each deployment is an app named agent-bricks-<name> with its own URL. Clients authenticate with a Azure Databricks OAuth token. See Query agents deployed on Azure Databricks.
  • Agent identity: The agent runs as the app's service principal. See Agent identity.
  • Durable execution: For agents that use DurableAgentServer, deployment provisions a Runtime Store so that run state survives worker restarts and interrupted runs can recover.
  • Tracing: Deployment configures MLflow tracing to the experiment that the project binds. See Tracing overview.
  • Scaling: Run an agent at scale across multiple instances. See Horizontal scaling for Databricks apps.

Agent identity

An agent's identity is the service principal of the app that it's deployed to. The agent uses this identity to call Azure Databricks APIs and to run tools that you add with --auth app.

  • When you deploy, agentbricks deploy grants the service principal access to the memory, session, and run state stores that the agent uses.
  • To give the agent access to other data and resources, grant the app's service principal the permissions it needs, as you would for any app. See Configure authorization in a Databricks app.
  • Tools that use auth = "user" run with the permissions of the user who sent the request instead of the service principal. See Request-user authorization.

Prerequisites

  • Install the Databricks CLI, Python 3.11 or above, and uv.

  • Install the Agent Bricks CLI:

    uv tool install databricks-agentbricks
    
  • Sign in to your workspace. agentbricks login saves the profile as the default, so later commands can omit --profile:

    databricks auth login --host <workspace-url> --profile <profile>
    agentbricks login --profile <profile>
    
  • Create an agent project and change to its directory:

    agentbricks init my-agent
    cd my-agent
    

Deploy an agent

Deploy an agent project with the Agent Bricks CLI.

Deploy from the project directory

To deploy the agent, run the following command from the project directory:

agentbricks deploy my-agent

To deploy to a workspace other than the default, pass --profile <profile>.

The project directory holds agent.toml and app.yaml. If you run agentbricks deploy from any other directory, it uploads that directory instead. To deploy a project from another directory, pass --source <dir>.

The argument to agentbricks deploy is the deployment name, up to 17 characters. The app is named agent-bricks-<name>, so this example creates agent-bricks-my-agent. The first deploy records the name in agent.toml, so later deploys from the project can omit it.

A first deploy takes a few minutes. The command finishes when the agent answers requests.

agentbricks deploy does the following:

  1. Creates or reuses the memory and session stores declared in agent.toml, and grants the app's service principal access to them.
  2. For agents that use DurableAgentServer, creates or reuses the deployment's Runtime Store.
  3. Configures tracing.
  4. Deploys the app.

To run the agent on more than one instance, pass --instances:

agentbricks deploy my-agent --instances 2

When an agent runs on more than one instance, clients can send the session ID in an X-Routing-Key header to route all requests in a session to the same instance.

Deploy without waiting

If a script or coding agent has a short command timeout, deploy without waiting, and then wait for the deployment in a separate command:

agentbricks deploy my-agent --no-wait
agentbricks deployments wait agent-bricks-my-agent

--no-wait runs the quick checks, and then finishes the deploy in a background process. agentbricks deployments wait waits up to 100 seconds by default. To change the limit, pass --timeout. The command exits with one of the following codes:

  • 0: The agent is deployed and answers requests.
  • 1: The deploy failed.
  • 75: The agent is still deploying. Run the command again.

Run agentbricks deployments wait from the project directory, or pass --source <dir>.

Manage deployments

Command Description
agentbricks deployments list List your agent deployments.
agentbricks deployments get <app-name> Show a deployment's URL, status, and description.
agentbricks deployments wait [<app-name>] Wait for a deployment to finish. Defaults to the deployment recorded in agent.toml.
agentbricks deployments logs <app-name> Show a deployment's logs.
agentbricks deployments start <app-name> Start a deployment.
agentbricks deployments stop <app-name> Stop a deployment. Asks for confirmation unless you pass --yes.
agentbricks deployments delete <app-name> Delete a deployment. Asks for confirmation unless you pass --yes.

Because each deployment is an app, you can also view and monitor it in Databricks Apps. See Logging and Monitoring for Databricks Apps.

Limitations

You can't change the agent server of an existing deployment. To switch servers, create a new project with the agentbricks init --server option that you want, and deploy it under a new name.

Additional resources