Quale esperienza stai usando?
Questa documentazione copre entrambe le esperienze. Se Impostazioni → Personale → My Okou è disponibile, segui i passaggi di My Okou. Se usi una pagina Agents con Nuovo agente, segui i passaggi di Legacy Agents. La disponibilità può variare tra i membri; questa documentazione non modifica la tua esperienza.
In entrambe le esperienze, puoi eseguire più chat o attività contemporaneamente, riutilizzare i flussi di lavoro e condividere con il tuo team il lavoro revisionato. Un sottagente di runtime è uno strumento di esecuzione, non un profilo del prodotto separato che devi creare.
Differenze di configurazione: My Okou usa le istruzioni personali (Instructions) in Impostazioni → Personale → My Okou e i flussi di lavoro dello spazio di lavoro. Qualsiasi passaggio qui sotto che ti chiede di scegliere, creare o autorizzare un agente nominato si applica solo a Legacy Agents. In My Okou, usa la tua chat e segui la richiesta di account e di autorizzazione nominata mostrata. I flussi di lavoro condivisi non condividono le credenziali; le automazioni usano il contesto e l'accesso del loro proprietario.
Un connettore personalizzato consente a un amministratore dell'organizzazione di registrare un'API HTTPS o, dove abilitato, un server MCP Streamable HTTP non presente nel catalogo integrato. Definisce il confine di rete e il metodo di autenticazione. Non genera automaticamente per l'agente una documentazione completa dell'API.
Chi configura cosa
- Gli amministratori dell'organizzazione creano, modificano ed eliminano la definizione del connettore.
- I membri collegano il proprio segreto o completano il flusso OAuth del connettore.
- Autorizzazione e permessi controllano quali azioni nominate Okou può richiedere con la connessione. Anche Legacy Agents usano autorizzazioni specifiche dell'Agent.
La definizione è condivisa nell'organizzazione. Le credenziali del membro restano limitate al membro e all'organizzazione.
Connettore API HTTP
- Apri Connectors → Custom e scegli New connector.
- Seleziona HTTP API e inserisci un nome visualizzato.
- Aggiungi uno o più Prefissi HTTPS, uno per riga. Una richiesta deve corrispondere a un prefisso configurato prima che il connettore possa autorizzarla.
- Aggiungi l'autenticazione se l'API la richiede:
- Autenticazione API: inserisci il nome dell'intestazione e un modello di intestazione che contenga
{{secret}}, ad esempioAuthorizationeBearer {{secret}}. - OAuth 2.0: inserisci l'URL di autorizzazione, l'URL del token, l'ID client, il segreto client, gli scope e il metodo di autenticazione dell'endpoint del token. Registra con il provider l'esatto URL di reindirizzamento mostrato nel modulo.
- Autenticazione API: inserisci il nome dell'intestazione e un modello di intestazione che contenga
- Crea il connettore. Ogni membro che ne ha bisogno seleziona quindi Connect e fornisce il proprio segreto oppure completa OAuth.
- Rivedi e autorizza i permessi nominati richiesti. In Legacy Agents, seleziona anche l'Agent previsto.
La modifica di una definizione OAuth esistente o delle relative credenziali client disconnette le connessioni OAuth attive. I membri devono connettersi di nuovo dopo la modifica.
Connettore MCP
Se MCP appare come tipo di connettore nel tuo spazio di lavoro, inserisci un endpoint MCP Streamable HTTP HTTPS e configura l'autenticazione API o OAuth nello stesso modulo. Se MCP non è disponibile nel selettore, non è abilitato per quello spazio di lavoro.
Insegna all'agente la procedura API
Un connettore personalizzato fornisce accesso di rete sicuro e inserimento delle credenziali. Il modulo di creazione non carica né rileva automaticamente un documento OpenAPI. Fornisci all'agente l'endpoint, il metodo, i parametri e la risposta prevista nella richiesta, oppure registra quella procedura in un flusso di lavoro con un riferimento API allegato come file.
Valida un nuovo connettore con una richiesta limitata, di sola lettura, verso un endpoint noto. Non esiste una richiesta generica Test connection perché molte API non espongono un endpoint radice significativo.
Limiti di sicurezza
- Sono accettati solo prefissi HTTPS ed endpoint MCP.
- Il firewall inserisce le credenziali salvate solo nelle richieste corrispondenti.
- Il segreto salvato è crittografato a riposo e non viene esposto all'agente come variabile d'ambiente.
- Non inserire chiavi, token o segreti client nei messaggi di chat, nelle istruzioni del flusso di lavoro o nei file allegati.
- Usa una credenziale di servizio con il minimo scope upstream necessario per il flusso di lavoro.
Risoluzione dei problemi
| Problema | Controllo |
|---|---|
| New connector non è disponibile | Solo un amministratore dell'organizzazione può creare o modificare le definizioni dei connettori. |
| L'agente non riesce a vedere il connettore | Collegalo per il membro corrente e rivedi i permessi necessari. In Legacy Agents, autorizza anche l'Agent previsto. |
| La richiesta viene bloccata prima di raggiungere l'API | Conferma che l'URL della richiesta inizi con uno dei prefissi HTTPS configurati. |
| L'API restituisce 401 o 403 | Ricollega le credenziali del membro e verifica la chiave upstream o gli scope OAuth. |
| OAuth restituisce un errore di reindirizzamento | Registra l'esatto URL di reindirizzamento mostrato nel modulo del connettore e verifica gli URL di autorizzazione e del token. |
| L'agente indovina l'endpoint o il payload sbagliato | Inserisci la procedura API in un flusso di lavoro e allega il riferimento pertinente invece di fare affidamento solo sul nome del connettore. |
Cosa c'è dopo
- Consulta i flussi di lavoro per acquisire lavoro ripetuto con connettori personalizzati.
- Consulta le Autorizzazioni per sapere come vengono gestite le credenziali dei connettori personalizzati.
- Consulta il Catalog prima di creare un connettore personalizzato: il tuo servizio potrebbe già essere supportato.
