Agent Services in Unity Catalog

Important

This feature is in Beta. Account admins can control access to this feature from the account console Previews page. See Manage Azure Databricks previews.

Agent Services give all your AI agents a home in Unity Catalog. Register agents from any team in one place, browse and discover them 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

Once registered, an agent service appears in Catalog Explorer under the schema where it was created. Anyone with READ_METADATA on the agent service can browse it alongside the tables, models, and functions in the same schema. Select an agent service to view its name, description, connection, and current permissions.

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

  • 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 have MANAGE_ACCESS_CONTROL on the agent service.

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": {
      "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": {
    "connection": { "name": "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, MANAGE_ACCESS_CONTROL, 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.

Next steps

  • Last updated on