Agentes de registro (servicios de agentes)

Registra agentes en el Catálogo de Unity para que los agentes de cada equipo vivan en un mismo lugar. Cuando registras un agente como servicio de agente, puedes navegar y descubrirlo junto con tus tablas, modelos y funciones, y establecer permisos con las mismas concesiones que protegen tus otros activos del Catálogo de Unity.

Detección de agentes en el Explorador de catálogos

Después de registrar un servicio de agente, aparece en el Explorador de Catálogos bajo el esquema donde fue creado. Para ver un servicio agente, un usuario necesita un privilegio explícito sobre él, como EXECUTE. Seleccione un servicio de agente para ver su nombre, descripción, conexión y permisos actuales.

Use el comment campo para agregar una descripción al crear o actualizar un servicio de agente. Esta descripción aparece en el Explorador de catálogos y ayuda a los compañeros de equipo a comprender lo que hace el agente al examinarla.

Esto proporciona a su organización un único lugar para ver qué agentes existen, quién los posee y quién tiene acceso, sin tener que realizar un seguimiento de ellos en sistemas o documentación independientes.

Requirements

• Las funciones beta de Unity AI Gateway habilitadas para tu cuenta. Consulte Administrar versiones preliminares de Azure Databricks.
• Para crear un servicio de agente, debe disponer de USE CATALOG y USE SCHEMA en el catálogo principal y el esquema, CREATE SERVICE en el esquema y USE CONNECTION en la conexión a la que hace referencia el servicio de agente.
• Para administrar permisos en un servicio de agente, debe ser el propietario del servicio del agente o tener el MANAGE privilegio .

Creación de un servicio de agente

Un servicio de agente hace referencia a una conexión de catálogo de Unity existente que contiene el host y las credenciales del agente. Cree la conexión antes de crear el servicio del agente.

En el ejemplo siguiente se crea un servicio de agente denominado support_agent en el 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."
    }
  }'

La respuesta incluye el nombre del recurso del servicio 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."
  }
}

Obtener y listar los servicios del agente

Recupere un único servicio de agente por su nombre completo:

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

Enumerar todos los servicios del agente en un esquema:

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

Para enumerar los servicios de agente en todo el metastore, omita el filtro de esquema:

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

Actualización de un servicio de agente

Para actualizar campos específicos sin sobrescribir otros, use una PATCH solicitud y especifique qué campos se van a cambiar. En el ejemplo siguiente se actualiza el prompt del sistema mientras se dejan todos los demás campos sin modificar:

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 puede actualizar: comment, config.system_prompt, config.base_path.

Conceder acceso

Establezca permisos en un servicio de agente con el mismo modelo de concesión que protege los demás objetos protegibles del catálogo de Unity. Conceda EXECUTE a los usuarios y entidades de servicio:

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

Inspeccione las concesiones actuales:

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

Revocar acceso:

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

Privilegios asignables: EXECUTE, READ METADATA, MANAGE, ALL PRIVILEGES.

Eliminación de un servicio de agente

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

Limitations

Durante la versión beta, se aplican las siguientes limitaciones:

• La invocación en tiempo de ejecución no está disponible. No se puede invocar a los agentes a través de un servicio de agentes registrados. La administración de registros y permisos ya está disponible.
• La API no admite las directivas de servicio ni los límites de velocidad. Al intentar establecer estos campos, se devuelve un error.
• SQL DDL para los servicios del agente no está disponible. Cree y administre servicios de agente con la API REST.
• Los campos full_name y owner devuelven null en las respuestas GET de esta versión.
• La búsqueda global de Unity Catalog no muestra los servicios de agente.
• El BROWSE privilegio no está respaldado. Para ver un servicio agente, un usuario necesita un privilegio explícito sobre él, como EXECUTE.

Pasos siguientes

• Gobernanza de inteligencia artificial con Unity AI Gateway para controlar el tráfico de IA desde una ubicación central.