L'API Managed Agents su Agent Platform ti consente di creare agenti autonomi gestiti con una sola chiamata API. Grazie all'imbracatura Antigravity, ogni agente viene eseguito in un ambiente sandbox in cui ragiona, pianifica, utilizza le competenze dell'agente, esegue codice, esegue ricerche sul web e legge e scrive file.
Architettura di sistema
L'API Managed Agents su Agent Platform sfrutta due interfacce chiave:
| API | Descrizione |
|---|---|
| API Agents | Il control plane per la gestione degli agenti. Utilizzalo per creare agenti dalle configurazioni e configurare i loro ambienti di esecuzione, incluso il montaggio di origini dati esterne e la definizione di liste consentite di rete. Il sistema applica queste configurazioni all'ambiente di esecuzione sandbox dell'agente. La connessione di origini dati e strumenti esterni richiede l'autenticazione, con le limitazioni descritte in Sicurezza e best practice. |
| API Interactions | Si tratta del data plane, che funge da interfaccia principale per comunicare e interagire con gli agenti di cui è stato eseguito il deployment in runtime. Si connette all'agente creato utilizzando l'API Agents. |
Per una maggiore sicurezza, ogni agente opera con un ambiente sandbox isolato. Quando personalizzi l'ambiente con fonti esterne, come Cloud Storage, il sistema carica questi file direttamente nel file system del container su richiesta e l'agente può scrivere i risultati in Cloud Storage. Per saperne di più, consulta il riferimento all'API Managed Agents nell'ambiente sandbox di Agent Platform.
Sicurezza e best practice
Per impostazione predefinita, ogni agente esegue azioni in un ambiente sandbox senza accesso a sistemi, reti o credenziali esterni. L'agente può interagire solo con i file, i pacchetti e i dati all'interno della propria sandbox.
Ciò significa che l'agente non può effettuare chiamate di rete, accedere a database o raggiungere l'infrastruttura di produzione.
Qualsiasi connettività oltre la sandbox deve essere configurata esplicitamente da te, lo sviluppatore. Per ulteriori informazioni, consulta la pagina Configura l'accesso alla rete.
Accesso alla rete
Attiva questa opzione solo quando il tuo caso d'uso lo richiede e limita l'accesso il più possibile.
Quando abiliti l'accesso alla rete per un ambiente, l'agente può raggiungere API esterne, clonare repository pubblici e scaricare pacchetti. Prima di abilitare l'accesso alla rete, tieni presente quanto segue:
- Evita di esporre endpoint sensibili. Non indirizzare l'agente a servizi interni, pannelli di amministrazione o database, a meno che tu non abbia esaminato i rischi e non sia pronto a monitorare l'attività dell'agente.
- Rivedi le azioni dell'agente. Quando l'accesso alla rete è abilitato, monitora le interazioni dell'agente, soprattutto durante lo sviluppo iniziale, per verificare che acceda solo alle risorse che intendi.
Best practice per le credenziali
Se il tuo flusso di lavoro richiede l'autenticazione dell'agente con servizi esterni, come i server MCP, sei responsabile del provisioning e dell'ambito di queste credenziali. Segui queste linee guida per ridurre il rischio:
- Utilizza credenziali con privilegi minimi. Crea service account o chiavi API con solo le autorizzazioni necessarie al tuo agente. Evita di trasmettere credenziali con accesso amministrativo o ampio.
- Preferisci i token di breve durata. Se possibile, utilizza credenziali o token a tempo limitato che scadono anziché chiavi API di lunga durata.
- Non fornire mai credenziali che non vuoi che l'agente utilizzi. L'agente può utilizzare qualsiasi credenziale a cui ha accesso per completare l'attività che gli hai assegnato. Fornisci solo credenziali di cui vuoi concedere l'ambito di accesso completo.
- Ruota regolarmente le credenziali. Tratta le credenziali condivise con l'agente allo stesso modo di qualsiasi credenziale programmatica: ruotale regolarmente.
Connessione di strumenti e API esterni
L'API Agents supporta la connessione di strumenti e API esterni (come i server MCP) per estendere le funzionalità dell'agente. Quando lo fai:
- Valuta attentamente le fonti degli strumenti. Connetti solo strumenti provenienti da fonti attendibili. Uno strumento dannoso o scritto male potrebbe esporre i dati o eseguire azioni non intenzionali.
- Definisci l'ambito delle autorizzazioni dello strumento. Configura gli strumenti con le autorizzazioni minime richieste per il tuo caso d'uso. Se uno strumento supporta la modalità di sola lettura, utilizzala a meno che non sia necessario l'accesso in scrittura.
- Esegui prima il test in isolamento. Prima di connettere uno strumento a un'origine dati di produzione, testalo con dati di esempio o sintetici per verificare che l'agente lo utilizzi come previsto.
Supervisione umana
Gli agenti possono ragionare, pianificare ed eseguire workflow in più passaggi con un alto grado di autonomia. Sebbene sia potente, ciò significa anche che devi applicare una supervisione adeguata, in particolare per le attività che modificano i dati o interagiscono con sistemi esterni.
Verifica sempre gli output critici, come il codice generato, le trasformazioni dei dati o le modifiche alla configurazione, prima di eseguirne il deployment.
Passaggi successivi
Creare e gestire gli agenti
Scopri come creare, aggiornare, elencare, ottenere ed eliminare agenti utilizzando l'API REST.
API Managed Agents nell'ambiente sandbox di Agent Platform
Scopri di più sul contenitore sandbox isolato, sulle autorizzazioni e sui pacchetti/strumenti preinstallati.