Register agents (agent services)

Important

Agent services are in Beta. Unity AI Gateway is generally available, but its beta capabilities are enabled separately. An account admin must turn on the Unity AI Gateway beta features from the account console Previews page. See Manage Azure Databricks previews.

Register agents in Unity Catalog so every team's agents live in one place. When you register an agent as an agent service, you can browse and discover it alongside your tables, models, and functions, and set permissions with the same grants that protect your other Unity Catalog assets.

Discover agents in Catalog Explorer

After an agent service is registered, it appears in Catalog Explorer under the schema where it was created. To see an agent service, a user needs an explicit privilege on it, such as EXECUTE. Select an agent service to view its name, description, connection, and current permissions.

Note

Granting EXECUTE also lets the user invoke the agent service, not just discover it. Grant it only to users who should be able to use the agent.

Use the comment field to add a description when you create or update an agent service. This description appears in Catalog Explorer and helps teammates understand what the agent does when they browse it.

This gives your organization a single place to see what agents exist, who owns them, and who has access, without having to track them across separate systems or documentation.

Requirements

  • The Unity AI Gateway beta features enabled for your account. See Manage Azure Databricks previews.
  • To create an agent service, you must have USE CATALOG and USE SCHEMA on the parent catalog and schema, CREATE SERVICE on the schema, and USE CONNECTION on the connection the agent service references.
  • To manage permissions on an agent service, you must be the owner of the agent service or have the MANAGE privilege.

Create an agent service

An agent service references an existing Unity Catalog connection that holds the host and credentials for the agent. Create the connection before you create the agent service.

The following example creates an agent service named support_agent in the main.default schema:

databricks api post \
  "/api/2.1/unity-catalog/agent-services?parent=schemas/main.default&agent_service_id=support_agent" \
  --json '{
    "agent_service_type": "AGENT_SERVICE_TYPE_EXTERNAL",
    "comment": "Support agent for the customer team",
    "config": {
      "source_connection": {
        "name": "connections/main.default.my_agent_connection"
      },
      "base_path": "/v1/chat",
      "system_prompt": "You are a helpful support assistant."
    }
  }'

The response includes the agent service's resource name:

{
  "name": "agent-services/main.default.support_agent",
  "agent_service_type": "AGENT_SERVICE_TYPE_EXTERNAL",
  "created_by": "you@company.com",
  "config": {
    "source_connection": { "name": "connections/main.default.my_agent_connection" },
    "base_path": "/v1/chat",
    "system_prompt": "You are a helpful support assistant."
  }
}

Get and list agent services

Retrieve a single agent service by its full name:

databricks api get "/api/2.1/unity-catalog/agent-services/main.default.support_agent"

List all agent services in a schema:

databricks api get "/api/2.1/unity-catalog/agent-services?parent=schemas/main.default"

To list agent services across the entire metastore, omit the schema filter:

databricks api get "/api/2.1/unity-catalog/agent-services"

Update an agent service

To update specific fields without overwriting others, use a PATCH request and specify which fields to change. The following example updates the system prompt while leaving all other fields unchanged:

databricks api patch \
  "/api/2.1/unity-catalog/agent-services/main.default.support_agent?update_mask=config.system_prompt" \
  --json '{ "config": { "system_prompt": "You are a concise support assistant." } }'

Fields you can update: comment, config.system_prompt, config.base_path.

Grant access

Set permissions on an agent service with the same grant model that protects your other Unity Catalog securable objects. Grant EXECUTE to users and service principals:

databricks api patch \
  "/api/2.1/unity-catalog/permissions/AGENT_SERVICE/main.default.support_agent" \
  --json '{
    "changes": [
      { "principal": "teammate@company.com", "add": ["EXECUTE"] }
    ]
  }'

Inspect current grants:

databricks api get "/api/2.1/unity-catalog/permissions/AGENT_SERVICE/main.default.support_agent"

Revoke access:

databricks api patch \
  "/api/2.1/unity-catalog/permissions/AGENT_SERVICE/main.default.support_agent" \
  --json '{
    "changes": [
      { "principal": "teammate@company.com", "remove": ["EXECUTE"] }
    ]
  }'

Assignable privileges: EXECUTE, READ METADATA, MANAGE, ALL PRIVILEGES.

Delete an agent service

databricks api delete "/api/2.1/unity-catalog/agent-services/main.default.support_agent"

Limitations

During the beta, the following limitations apply:

  • Runtime invocation is not available. Agents cannot be called through a registered agent service. Registration and permissions management are available now.
  • Service policies and rate limits are not supported by the API. Attempting to set these fields returns an error.
  • SQL DDL for agent services is not available. Create and manage agent services with the REST API.
  • full_name and owner fields return null in GET responses in this release.
  • Unity Catalog Global Search does not surface agent services.
  • The BROWSE privilege is not supported. To see an agent service, a user needs an explicit privilege on it, such as EXECUTE.

Next steps

  • Last updated on