Due strade per un servizio che parla HTTP

Quando l’API che vuoi far chiamare all’agente non ha un connettore prebuilt, Copilot Studio ti mette davanti a due strade. La prima parte da un custom connector già costruito in Power Platform e ne aggiunge le operazioni come strumenti. La seconda carica una specifica OpenAPI direttamente nella procedura guidata REST API dello studio. In conversazione il risultato sembra lo stesso — l’agente chiama il servizio — ma cambia dove vive la definizione, chi la governa e come si sposta fra ambienti.

Aggiungere uno strumento da un custom connector esistente

Se il connettore esiste già, il percorso è identico a quello dei connettori prebuilt: apri l’agente, vai alla pagina Tools, scegli Add a tool, poi Connector. Cerchi il servizio, selezioni l’operazione che ti serve (ogni operazione diventa uno strumento distinto) e, se la connection non c’è ancora, scegli Create new connection; chiudi con Add and configure e ti ritrovi sulla pagina di configurazione dello strumento. Il connettore va anche condiviso: la documentazione avverte che «The connector needs view and share permissions for the organization for the agent to use the connector».

Se invece il connettore non esiste, Add a tool → New tool → Custom connector non lo costruisce nello studio: ti porta nel portale Power Apps, sezione Custom connectors. Host, operazioni, schema e scheda Security si scrivono là.

Sulla pagina dello strumento, la sezione Details contiene Name e Description — è la descrizione che la generative orchestration legge per decidere quando invocarlo — e sotto Additional details trovi Allow agent to decide dynamically when to use the tool, Ask the end user before running e la scelta fra credenziali End user e Maker-provided (la pagina dedicata ai connettori chiama la stessa impostazione Credentials to use). Per impostazione predefinita la connessione usa le credenziali dell’utente.

On-behalf-of: chi chiama davvero il servizio

Un custom connector con autenticazione Microsoft Entra ID può supportare l’autenticazione On-Behalf-Of (OBO): l’agente chiede all’utente il permesso di ottenere un token e agire a suo nome, e l’utente può concedere o negare. Da quel momento l’accesso al servizio è trasparente.

La configurazione tocca due mondi. In Microsoft Entra ID servono, nell’ordine: (facoltativa) un’app registration che rappresenta la tua API o il tuo server MCP, con uno scope pubblicato sotto Expose an API; un’app registration per il connettore, con API permissions di tipo Delegated permissions — non Application permissions — e admin consent; un client secret; e, sempre sull’app del connettore, uno scope esposto più l’autorizzazione del service principal Azure API Connections (client ID fe053c5f-3692-4f14-aef2-ee34fc081cae) fra le Authorized client applications. Senza quest’ultimo passaggio gli utenti dovrebbero accedere esplicitamente ogni volta che usano il connettore.

Nel connettore, scheda Security, la parte che conta è questa:

Authentication type:        OAuth 2.0
Identity Provider:         Microsoft Entra ID
Resource URL:              api://00001111-aaaa-2222-bbbb-3333cccc4444
Enable on-behalf-of login: true
Scope:                     api://00001111-aaaa-2222-bbbb-3333cccc4444/employee.read

Update connector genera un Redirect URL da incollare nell’app registration del connettore sotto Authentication → Add a platform → Web. Infine si condivide il connettore: Can edit ai maker che lo gestiscono, Can view agli utenti che dialogano con l’agente. Attenzione a non confondere OBO con le credenziali maker-provided: OBO agisce con l’identità dell’utente e ne rispetta i permessi, le credenziali del maker fanno agire tutti con l’identità dell’autore.

Caricare una REST API direttamente come strumento

La seconda strada salta il portale connettori. Da Tools → Add a tool → New tool → REST API carichi la specifica dell’API: deve essere un file JSON in formato OpenAPI v2, e se ne fornisci una v3 il processo di creazione la traduce automaticamente in v2. Nella pagina API plugin details curi la Description — quella precompilata dalla specifica è quasi sempre troppo povera per l’orchestratore — e scegli la Solution in cui salvare l’artefatto; se la lasci vuota, una solution viene creata per te con il nome dell’azione e il publisher predefinito, e non è quello che vuoi se poi devi spostare l’agente fra ambienti.

Poi arriva l’autenticazione, con tre opzioni: None, API key (con Parameter label, Parameter name e Parameter location su Header o Query) e OAuth 2.0, etichettata Auth 2.0 nell’interfaccia, con Client ID, Client secret, Authorization URL, Token URL, Refresh URL e Scope. Nella pagina Select and configure your tool scegli quali endpoint attivare: un’API che espone anche delete non obbliga a regalare il delete all’agente. Per ciascuno definisci Tool name e Tool description, poi in Review your tool’s parameters puoi correggere le descrizioni di input e output ma non i valori, e le descrizioni vuote vanno riempite per procedere. Alla fine lo strumento viene pubblicato e devi ancora creare la connessione e fare Add and configure.

In pratica: parti dal custom connector quando esiste già, è condiviso, è coperto dalle policy DLP e serve a più agenti o flow; usa la procedura REST API quando hai la specifica in mano e vuoi ricavarne più strumenti in una sola passata (funzionalità documentata come preview).

Il nodo Send HTTP request non è uno strumento

Dentro un topic puoi aggiungere Add node → Advanced → Send HTTP request: imposti URL, Method (sono supportati GET, POST, PATCH, PUT e DELETE), header e body (No Content, JSON Content o Raw content), il Response data type con Get schema from sample JSON, e la variabile in cui salvare la risposta. Ha error handling proprio (Raise an error oppure Continue on error, con variabili per status code e corpo dell’errore) e un Request timeout in millisecondi.

Qui sta la confusione che l’esame ti chiede di sciogliere: il nodo HTTP è un’azione in un punto preciso del flusso conversazionale, non uno strumento che l’orchestratore può scegliere autonomamente in base a nome e descrizione. Non ha connection, non ha connection reference, non compare fra i tool dell’agente, e l’autenticazione la costruisci a mano passando un header tipo Authorization: Bearer .... Uno strumento da connettore o da REST API, al contrario, è selezionabile dalla generative orchestration; in orchestrazione classica, invece, «Tools can only be called explicitly from within a topic». Un altro dettaglio da ricordare: la risposta di un connettore che supera i 500 KB fa fallire la richiesta con HTTP 400, sia che il connettore sia configurato a livello di agente sia dentro un topic, e la soluzione è filtrare i dati sugli input dell’operazione.