O acesso à web permite que um agente leia páginas, pesquise na web e chame APIs públicas durante uma execução. A própria microVM não tem internet: toda requisição passa pelo Ephemeral, que a verifica, a envia como EphemeralBot e a registra.
Ativando
O acesso à web fica desativado, a menos que uma execução ou um fluxo de trabalho defina web. O playground do painel o ativa para você.
"web": truePara restringir uma execução a certos sites, liste-os em allow. api.github.com corresponde apenas a esse host; *.github.com corresponde a todos os subdomínios e ao próprio github.com. Os redirecionamentos são verificados na mesma lista. Defina search como false para excluir a pesquisa na web.
"web": { "allow": ["api.github.com", "*.stripe.com"], "search": false }Em um arquivo de fluxo de trabalho, a mesma configuração é escrita como web: true ou como web: com allow e search logo abaixo. O web de uma requisição de execução substitui o do fluxo de trabalho naquela execução.
O que o agente pode fazer
| Ferramenta | Faz |
|---|---|
web_ | Envia uma requisição com qualquer método, cabeçalhos e corpo e retorna o status e a resposta como texto. As páginas HTML são convertidas em texto legível, com seus links. As respostas longas vêm em partes de 40.000 caracteres; ler a parte seguinte de uma página que a execução já buscou é gratuito. |
web_ | Pesquisa na web e retorna até 10 resultados, cada um com título, URL e um breve trecho. O agente lê um resultado por completo com web_fetch. |
O agente de cada execução é informado de como a sua máquina funciona: o shell não tem rede, então curl ou pip install vão falhar, e ele deve acessar a web com essas ferramentas.
O que o Ephemeral verifica
- O destino é um endereço público na porta 80, 443, 8080 ou 8443, por HTTP ou HTTPS, e consta na lista de permissões da execução. Cada redirecionamento é verificado de novo, até cinco.
- Um classificador de segurança lê cada requisição junto com a tarefa da execução e recusa as que parecem um ataque a um sistema, spam ou fraude, ou dados sendo enviados a um lugar que a tarefa não exige. Se o classificador não conseguir responder, as leituras prosseguem e as requisições que poderiam alterar dados são recusadas até que ele consiga.
- Uma execução pode fazer 50 requisições e pesquisas na web. Uma organização pode fazer 120 por minuto, e todos os clientes juntos enviam a um único site no máximo 60 por minuto. Quando um limite é atingido, o agente é avisado e a requisição não é enviada.
- Os corpos das requisições têm até 1 MiB, e até 10 MiB de cada resposta são lidos.
- As requisições seguem as regras que o robots.txt de um site define para o EphemeralBot pelo nome. A página do EphemeralBot explica como os proprietários de sites o reconhecem e o bloqueiam.
Uma requisição recusada é registrada com o motivo, e o agente recebe o mesmo motivo para poder mudar de rumo. A execução continua.
Custo
No serviço hospedado, cada requisição custa $0.001 e cada pesquisa, $0.01. Ambos saem do orçamento da execução como as chamadas ao modelo; uma requisição que o ultrapassaria é recusada. As requisições recusadas não são cobradas. Veja os preços.
Eventos
| Tipo | Registrado quando |
|---|---|
web_ | Uma requisição foi enviada. Inclui o método, a URL final, o status, o tamanho, a duração, o custo, as pontuações de segurança e o ID da requisição que ela levava. |
web_ | Uma pesquisa foi executada. Inclui a consulta, quantos resultados retornou e o custo. |
web_ | Uma requisição ou pesquisa foi recusada antes de ser enviada. Inclui o motivo. |
Credenciais
O web_fetch envia os cabeçalhos que o agente definir, então uma chave de API usada pelo agente precisa estar no prompt ou na entrada, onde é armazenada com a execução. Para uma API que você chama com um segredo, uma conexão é melhor: o Ephemeral guarda o segredo e o agente nunca o vê.
Instalações auto-hospedadas
O mecanismo envia as requisições web a partir do seu próprio host. Defina EPHEMERAL_WEB_SOURCE_IP com um endereço separado nesse host para mantê-las isoladas do seu outro tráfego. A pesquisa na web usa a chave do OpenRouter em INFERENCE_API_KEY; com outro provedor, a pesquisa fica indisponível.
O classificador de segurança vem desativado nas instalações auto-hospedadas, porque roda na sua conta de inferência. Para ativá-lo, defina EPHEMERAL_WEB_CLASSIFIER_MODEL=typesafe/jev-1.13 com uma chave do OpenRouter. Sem ele, as suas listas de permissões, os limites de taxa e as regras de rede continuam valendo.