Agenti di registro (servizi agenti)

Registra gli agenti nel Catalogo Unity così che gli agenti di ogni squadra vivano in un unico posto. Quando registri un agente come servizio agente, puoi consultarlo e scoprirlo insieme alle tue tabelle, modelli e funzioni, e impostare permessi con le stesse concessioni che proteggono gli altri asset del Catalogo Unity.

Scopri gli agenti in Catalog Explorer

Dopo che un servizio agente è stato registrato, appare in Catalog Explorer sotto lo schema in cui è stato creato. Per vedere un servizio agente, un utente deve avere un privilegio esplicito su di esso, come EXECUTE. 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

• Le funzionalità beta di Unity AI Gateway attivate per il tuo account. Vedere Gestire le anteprime di Azure Databricks.
• 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 essere il proprietario del servizio agente o avere il MANAGE privilegio .

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": {
      "source_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": {
    "source_connection": { "name": "connections/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, 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.
• Il BROWSE privilegio non è supportato. Per vedere un servizio agente, un utente deve avere un privilegio esplicito su di esso, come EXECUTE.

Passaggi successivi

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