Serviços de Agente no Unity Catalog

info

Beta

Este recurso está em Beta. Os administradores da account podem controlar o acesso a este recurso na página Pré-visualizações do console da account. Consulte Gerenciar prévias do Databricks.

Serviços de Agente oferecem um lar para todos os seus agentes de AI no Unity Catalog. É possível realizar o registro de agentes de qualquer equipe em um só lugar, navegar e descobri-los juntamente com suas tabelas, modelos e funções, e definir permissões com as mesmas concessões que protegem seus outros ativos do Unity Catalog.

Descobrir agentes no Catalog Explorer

Depois de registrado, um serviço de agente aparece no Explorador de Catálogos sob o esquema onde foi criado. Qualquer pessoa com READ_METADATA no serviço de agente pode navegar por ele juntamente com as tabelas, modelos e funções no mesmo esquema. Selecione um serviço de agente para view seu nome, descrição, conexão e permissões atuais.

Use o campo comment para adicionar uma descrição ao criar ou atualizar um serviço de agente. Esta descrição aparece no Catalog Explorer e ajuda os colegas a entender o que o agente faz quando o consultam.

Isso oferece à sua organização um lugar único para ver quais agentes existem, quem os possui e quem tem acesso, sem precisar rastreá-los em sistemas ou documentações separados.

Requisitos

• Para criar um serviço de agente, você deve ter USE CATALOG e USE SCHEMA no catálogo e esquema pai, CREATE SERVICE no esquema e USE CONNECTION na conexão referenciada pelo serviço de agente.
• Para gerenciar permissões em um serviço de agente, você deve ter MANAGE_ACCESS_CONTROL no serviço de agente.

Crie um serviço de agente

Um serviço de agente referencia uma conexão existente do Unity Catalog que contém o host e as credenciais para o agente. Crie a conexão antes de criar o serviço de agente.

O exemplo a seguir cria um serviço de agente nomeado support_agent no esquema main.default:

Bash

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."
    }
  }'

A resposta inclui o nome do recurso do serviço de agente:

JSON

{
  "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."
  }
}

Obter e listar serviços de agente

Recupere um único serviço de agente pelo seu nome completo:

Bash

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

Liste todos os serviços de agente em um esquema:

Bash

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

Para listar serviços de agente em todo o metastore, omita o filtro de esquema:

Bash

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

Atualizar um serviço de agente

Para atualizar campos específicos sem sobrescrever outros, use uma solicitação PATCH e especifique quais campos alterar. O exemplo a seguir atualiza o prompt do sistema enquanto deixa todos os outros campos inalterados:

Bash

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." } }'

Campos que você pode atualizar: comment, config.system_prompt, config.base_path.

Conceder acesso

Defina permissões em um serviço de agente com o mesmo modelo de concessão que protege seus outros objetos protegíveis do Unity Catalog. Conceda EXECUTE a usuários e entidades de serviço:

Bash

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

Inspecionar concessões atuais:

Bash

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

Revogar acesso:

Bash

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

Privilégios atribuíveis: EXECUTE, READ_METADATA, MANAGE, MANAGE_ACCESS_CONTROL, ALL_PRIVILEGES.

Excluir um serviço de agente

Bash

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

Limitações

Durante a beta, aplicam-se as seguintes limitações:

• A invocação de Runtime não está disponível. Agentes não podem ser chamados através de um serviço de agente registrado. O registro e o gerenciamento de permissões já estão disponíveis.
• Políticas de serviço e limites de taxa não são compatíveis com a API. A tentativa de definir esses campos retorna um erro.
• SQL DDL para serviços de agente não está disponível. Crie e gerencie serviços de agente com a API REST.
• full_name e os campos owner retornam null nas respostas GET nesta versão.
• A Pesquisa Global do Unity Catalog não exibe serviços de agente.

Próximos os passos

• Unity AI Gateway para governar o tráfego de IA a partir de um local central.
• Governança de AI no Unity Catalog para uma visão geral de como governar ativos de AI no Unity Catalog.