Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
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 deploygrants 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-agentbricksSign in to your workspace.
agentbricks loginsaves 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:
- Creates or reuses the memory and session stores declared in
agent.toml, and grants the app's service principal access to them. - For agents that use
DurableAgentServer, creates or reuses the deployment's Runtime Store. - Configures tracing.
- 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.