Registrar agentes (serviços de agente)

info

Beta

Os serviços de agente estão em Beta. O Unity AI Gateway está disponível de forma geral, mas seus recursos beta são habilitados separadamente. Um administrador da conta deve ativar os recursos beta do Unity AI Gateway na página Prévias do console da conta. Consulte Gerenciar prévias do Databricks.

Faça o registro de agentes no Unity Catalog para que os agentes de todas as equipes fiquem em um só lugar. Quando você registra um agente como um serviço de agente, você 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.

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

• Os recursos beta do Unity AI Gateway habilitados para sua account. Consulte Gerenciar prévias do 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 referenciada pelo serviço de agente.
• Para gerenciar permissões em um serviço de agente, é necessário ser o proprietário do serviço de agente ou ter o privilégio MANAGE.

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": {
      "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:

JSON

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

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, 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

• Governança de AI com o Unity AI Gateway para governar o tráfego de AI a partir de um local central.