Servizi degli agenti in Unity Catalog

Agent Services offrono a tutti i tuoi agenti AI uno spazio dedicato in Unity Catalog. Registrare gli agenti di qualsiasi team in un'unica posizione, esplorarli e individuarli insieme a tabelle, modelli e funzioni e impostare le autorizzazioni con le stesse concessioni che proteggono gli altri asset del catalogo Unity.

Scopri gli agenti in Catalog Explorer

Dopo la registrazione, un servizio di agente compare in Catalog Explorer all’interno dello schema in cui è stato creato. Chiunque disponga READ_METADATA del servizio agente può esplorarlo insieme alle tabelle, ai modelli e alle funzioni nello stesso schema. Selezionare un servizio agente per visualizzarne il nome, la descrizione, la connessione e le autorizzazioni correnti.

Usare il comment campo per aggiungere una descrizione quando si crea o si aggiorna un servizio agente. Questa descrizione viene visualizzata in Esplora cataloghi e aiuta i compagni di squadra a capire cosa fa l'agente quando lo esplorano.

In questo modo, l'organizzazione dispone di un unico punto da cui vedere quali agenti esistono, chi ne è proprietario e chi vi ha accesso, senza doverne tenere traccia tra sistemi o documentazione separati.

Requirements

• Per creare un servizio agente, è necessario avere USE CATALOG e USE SCHEMA nel catalogo padre e nello schema, CREATE SERVICE nello schema e USE CONNECTION nella connessione a cui fa riferimento il servizio agente.
• Per gestire le autorizzazioni per un servizio agente, è necessario disporre di MANAGE_ACCESS_CONTROL per il servizio agente.

Crea un servizio agente

Un servizio agent si riferisce a una connessione Unity Catalog esistente che contiene l'host e le credenziali dell'agent. Creare la connessione prima di creare il servizio dell'agente.

L'esempio seguente crea un servizio agente denominato support_agent nello 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."
    }
  }'

La risposta include il nome della risorsa del servizio agente:

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

Ottenere ed elencare i servizi dell'agente

Recupera un singolo servizio dell'agente tramite il nome completo:

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

Elencare tutti i servizi agente in uno schema:

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

Per elencare i servizi agente nell'intero metastore, omettere il filtro dello schema:

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

Aggiornare il servizio dell'agente

Per aggiornare campi specifici senza sovrascrivere altri, usare una PATCH richiesta e specificare i campi da modificare. L'esempio seguente aggiorna la richiesta di sistema lasciando invariati tutti gli altri campi:

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

Campi che è possibile aggiornare: comment, config.system_prompt, config.base_path.

Concedi accesso

Imposta le autorizzazioni per un servizio dell'agente con lo stesso modello di autorizzazione che protegge gli altri oggetti proteggibili di Unity Catalog. Concedi EXECUTE agli utenti e alle entità servizio:

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

Visualizzare le autorizzazioni attuali:

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

Revocare l'accesso:

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

Privilegi assegnabili: EXECUTE, READ_METADATA, MANAGE, MANAGE_ACCESS_CONTROL, ALL_PRIVILEGES.

Eliminare il servizio dell'agente

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

Limitations

Durante la versione beta, si applicano le limitazioni seguenti:

• La chiamata di runtime non è disponibile. Gli agenti non possono essere chiamati tramite un servizio agente registrato. La gestione delle registrazioni e delle autorizzazioni è ora disponibile.
• I criteri di servizio e i limiti di frequenza non sono supportati dall'API. Il tentativo di impostare questi campi restituisce un errore.
• DDL SQL per i servizi agent non è disponibile. Creare e gestire i servizi agente con l'API REST.
• I campi full_name e owner restituiscono null nelle risposte GET in questa versione.
• La ricerca globale di Unity Catalog non mostra i servizi degli agenti.

Passaggi successivi

• Governance IA con Unity AI Gateway per gestire il traffico IA da un punto centralizzato.