Connexions

Une connexion permet à un agent d'appeler une API HTTP ou un serveur MCP pendant une exécution. Ephemeral conserve les identifiants et effectue l'appel. Le worker ne voit jamais de jeton, de mot de passe ni de secret d'URL.

Comment fonctionne un appel

Chaque connexion accordée à une exécution donne à l'agent des outils à appeler. Lorsqu'il en appelle un, le worker envoie la requête à Ephemeral avec un jeton de courte durée qui ne fonctionne que pour cette exécution. Ephemeral vérifie que l'exécution a bien reçu la connexion et que la méthode ou l'outil est autorisé, ajoute les identifiants, envoie la requête, retire les valeurs d'identifiants de la réponse et la renvoie. Chaque appel est enregistré comme un événement connection.

Pour une connexion HTTP, l'agent fournit une méthode, un chemin relatif à l'URL de la connexion et, en option, un corps. Les corps sont envoyés en JSON, sauf si l'agent indique un autre type de contenu, comme un formulaire ou du XML, et envoie le corps sous forme de texte. Pour une connexion MCP, l'agent voit les outils du serveur et les appelle directement.

Expliquer à l'agent comment l'utiliser

Une connexion HTTP ne donne à l'agent qu'une URL de base, rien de plus : décrivez donc l'API dans instructions, avec les endpoints nécessaires à la tâche, le format des requêtes, l'aspect des ID et les règles à respecter. L'agent les voit avec l'outil de la connexion et dans ses instructions permanentes. Une exécution peut remplacer les instructions d'une connexion enregistrée par les siennes.

"instructions": "Find a customer with GET /v1/customers?email=... Create a refund with POST /v1/refunds as a form body (payment, amount in cents). Never refund more than the payment amount."

Connexions enregistrées et en ligne

Une connexion enregistrée est stockée une seule fois pour l'organisation et référencée par son nom. Les propriétaires et les administrateurs les créent dans le tableau de bord, sous Connexions, ou avec PUT /v1/connections/{name}. Les exécutions et les workflows les désignent avec ref :

"connections": {
  "payments": { "ref": "payments-api", "allowed_methods": ["GET"] },
  "docs": { "ref": "docs-mcp", "allowed_tools": ["search"] }
}

La clé, par exemple payments, est le nom que l'agent voit dans cette exécution. Vous pouvez aussi définir une connexion en ligne dans la requête d'exécution, avec son URL et ses identifiants. Les identifiants en ligne sont stockés chiffrés avec cette exécution et retirés de sa définition quand vous la relisez : une nouvelle exécution exige donc de les fournir de nouveau. Les connexions enregistrées évitent cela.

Restreindre l'accès

allowed_methods limite les méthodes HTTP qu'une connexion HTTP accepte. allowed_tools limite les outils d'un serveur MCP qui peuvent être appelés. Une liste vide ou absente autorise tout.

Une exécution peut restreindre davantage une connexion enregistrée. Elle ne reçoit que les méthodes ou les outils présents dans les deux listes. Si les deux listes n'ont rien en commun, la requête d'exécution est rejetée : une exécution n'obtient donc jamais plus d'accès que ce que la connexion enregistrée accorde.

Authentification

Pour OAuth, un propriétaire ou un administrateur enregistre la connexion avec l'ID client, l'URL d'autorisation et l'URL de jeton du fournisseur, puis l'autorise une fois dans le navigateur. Ephemeral stocke les jetons et renouvelle le jeton d'accès avant son expiration, tant que le fournisseur a émis un jeton de rafraîchissement. Enregistrez https://app.ephemer.al/oauth/callback comme URI de redirection auprès de votre fournisseur ; sur une installation auto-hébergée, utilisez votre propre domaine.

Règles réseau

• Les URL de connexion doivent utiliser HTTPS et pointer vers des adresses publiques d'Internet.
• Les redirections ne sont pas suivies.
• Une connexion HTTP accepte GET, POST, PUT, PATCH, DELETE et HEAD, et renvoie au plus 1 Mio par réponse. L'agent reçoit la réponse entière ; l'historique de l'exécution en conserve jusqu'à 256 Kio et marque l'endroit où elle a été raccourcie.
• Les serveurs MCP sont joints en Streamable HTTP. Les agents peuvent lister et appeler des outils ; les autres fonctionnalités MCP sont refusées.
• Sur le service hébergé, le réseau d'un worker n'atteint qu'Ephemeral. Toute requête vers l'extérieur passe par une connexion ou, lorsque l'exécution en dispose, par l'accès web.