Agentes de registro (serviços de agentes)

Registre os agentes no Unity Catalog para que todos os agentes de cada equipe fiquem em um só lugar. Quando você registra um agente como serviço de agente, pode navegar e descobri-lo junto com suas tabelas, modelos e funções, e definir permissões com as mesmas concessões que protegem seus outros ativos do Unity Catalog.

Descubra agentes no Catalog Explorer

Após o registro de um serviço de agente, ele aparece no Explorador de Catálogos no esquema onde foi criado. Para ver um serviço agente, o usuário precisa de um privilégio explícito sobre ele, como EXECUTE. Selecione um serviço de agente para exibir seu nome, descrição, conexão e permissões atuais.

Use o comment campo para adicionar uma descrição ao criar ou atualizar um serviço de agente. Essa descrição aparece no Gerenciador de Catálogos e ajuda os colegas a entender o que o agente faz quando eles navegam nele.

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

Requirements

• Os recursos beta do Unity AI Gateway ativados para sua conta. Consulte Gerenciar visualizações do Azure Databricks.
• 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 que o serviço de agente referencia.
• Para gerenciar permissões em um serviço de agente, você deve ser o proprietário do serviço do agente ou ter o MANAGE privilégio.

Criar um serviço de agente

Um serviço de agente faz referência a uma conexão existente no Unity Catalog que contém o host e as credenciais do 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 main.default esquema:

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

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

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

Obter e listar serviços de agente

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

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

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

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

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

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

Atualizar um serviço de agente

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

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_promptconfig.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 Catálogo do Unity. Conceder EXECUTE a usuários e entidades de serviço:

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

Inspecione as concessões atuais:

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

Revogar o acesso:

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. ALL PRIVILEGES

Excluir um serviço de agente

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

Limitations

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

• A invocação de runtime não está disponível. Os agentes não podem ser chamados por meio de um serviço de agente registrado. O gerenciamento de registro e permissões já está disponível.
• As políticas de serviço e os limites de taxa não são compatíveis com a API. Tentar definir esses campos retorna um erro.
• A DDL do SQL para serviços de agente não está disponível. Crie e gerencie serviços de agente com a API REST.
• Os campos full_name e owner retornam null em respostas GET nesta versão.
• A Pesquisa Global do Catálogo do Unity não exibe serviços de agente.
• O BROWSE privilégio não é apoiado. Para ver um serviço agente, o usuário precisa de um privilégio explícito sobre ele, como EXECUTE.

Próximas Etapas 

• Governança de IA com o Gateway de IA do Unity para controlar o tráfego de IA de um local central.