Conexões

Uma conexão permite que um agente chame uma API HTTP ou um servidor MCP durante uma execução. O Ephemeral guarda as credenciais e faz a chamada. O worker nunca vê um token, uma senha ou um segredo de URL.

Como funciona uma chamada

Cada conexão concedida a uma execução dá ao agente ferramentas para chamar. Quando ele chama uma, o worker envia a requisição ao Ephemeral com um token de curta duração que só funciona para aquela execução. O Ephemeral verifica se a execução recebeu a conexão e se o método ou a ferramenta é permitido, adiciona as credenciais, envia a requisição, remove os valores de credenciais da resposta e a devolve. Cada chamada é registrada como um evento connection.

Em uma conexão HTTP, o agente informa um método, um caminho relativo à URL da conexão e, opcionalmente, um corpo. Os corpos são enviados como JSON, a menos que o agente indique outro tipo de conteúdo, como um formulário ou XML, e envie o corpo como texto. Em uma conexão MCP, o agente vê as ferramentas do servidor e as chama diretamente.

Ensinando o agente a usá-la

Uma conexão HTTP dá ao agente uma URL base e nada mais, então descreva a API em instructions: os endpoints de que a tarefa precisa, o formato das requisições, como são os IDs e as regras a seguir. O agente as vê junto com a ferramenta da conexão e nas suas instruções permanentes. Uma execução pode substituir as instruções de uma conexão salva pelas suas próprias.

"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."

Conexões salvas e em linha

Uma conexão salva é armazenada uma vez para a organização e referenciada pelo nome. Proprietários e administradores as criam no painel, em Conexões, ou com PUT /v1/connections/{name}. As execuções e os fluxos de trabalho se referem a elas com ref:

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

A chave, como payments, é o nome que o agente vê nesta execução. Você também pode definir uma conexão em linha na requisição da execução, com sua URL e credenciais. As credenciais em linha são armazenadas criptografadas com essa execução e removidas da definição quando você a lê de volta, então uma nova execução exige que sejam informadas de novo. As conexões salvas evitam isso.

Restringindo o acesso

allowed_methods limita quais métodos HTTP uma conexão HTTP aceita. allowed_tools limita quais ferramentas de um servidor MCP podem ser chamadas. Uma lista vazia ou ausente permite tudo.

Uma execução pode restringir ainda mais uma conexão salva. A execução recebe apenas os métodos ou ferramentas que aparecem nas duas listas. Se as duas listas não tiverem nada em comum, a requisição da execução é rejeitada, de modo que uma execução nunca acaba com mais acesso do que a conexão salva concede.

Autenticação

No OAuth, um proprietário ou administrador salva a conexão com o ID do cliente, a URL de autorização e a URL do token do provedor e depois a autoriza uma vez no navegador. O Ephemeral armazena os tokens e renova o token de acesso antes de ele expirar, desde que o provedor tenha emitido um refresh token. Registre https://app.ephemer.al/oauth/callback como URI de redirecionamento no seu provedor; em uma instalação auto-hospedada, use o seu próprio domínio.

Regras de rede

• As URLs das conexões devem usar HTTPS e resolver para endereços públicos da internet.
• Os redirecionamentos não são seguidos.
• Uma conexão HTTP aceita GET, POST, PUT, PATCH, DELETE e HEAD e retorna no máximo 1 MiB por resposta. O agente recebe a resposta inteira; o registro da execução guarda até 256 KiB dela e marca onde foi encurtada.
• Os servidores MCP são acessados por Streamable HTTP. Os agentes podem listar e chamar ferramentas; os demais recursos do MCP são recusados.
• No serviço hospedado, a rede de um worker alcança apenas o Ephemeral. Toda requisição externa passa por uma conexão ou, quando a execução o tem, pelo acesso à web.