Envie um relatório semanal

Toda segunda-feira às 09:00 em Tóquio, leia os números da semana passada na sua API de análises, escreva um relatório curto e envie-o ao Slack ou por e-mail. O agente lê por meio de uma conexão que permite apenas GET, então ele pode olhar os seus números, mas não consegue alterá-los.

A execução leva cerca de 10 segundos. A maior parte do custo é a computação, cobrada a $0.0002 por segundo, então quatro execuções por mês custam cerca de um centavo. A parte do modelo depende do modelo que você escolher; leia cost_micros nas primeiras execuções para ver quanto é.

1. Reúna o que você precisa

   • Uma chave de API com a função de administrador, porque só proprietários e administradores criam conexões e agendamentos. Veja funções e chaves.
   • A sua API de análises via HTTPS e uma chave somente leitura para ela. Esta receita presume que ela tem GET /metrics?period=…, em que period é last_week ou uma semana ISO como 2026-W40. Ajuste os caminhos à sua API.
   • Uma URL de webhook de entrada do Slack, ou um endpoint seu que envie e-mails.

2. Crie a conexão somente leitura

   A conexão mantém a chave da API dentro do Ephemeral e permite apenas GET. As instructions dizem ao agente o que a API oferece.

   cURLCLIResposta

   curl -X PUT $EPHEMERAL_URL/v1/connections/analytics-api \
     -H "Authorization: Bearer $EPHEMERAL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "type": "http",
       "url": "https://analytics.example.com/v2",
       "auth": { "type": "header", "header": "X-API-Key", "token": "an_live_…" },
       "allowed_methods": ["GET"],
       "instructions": "GET /metrics?period=last_week or period=2026-W40 returns signups, active_users, revenue_cents and churned_accounts for that ISO week, with the same figures for the week before. Amounts are in cents."
     }'

3. Salve o fluxo de trabalho

   O prompt lê o período a partir da entrada da execução. O agente não tem um calendário confiável, então passe um período que a sua API consiga resolver, como last_week, em vez de pedir ao agente que calcule as datas.

   cURLCLIResposta

   curl -X PUT $EPHEMERAL_URL/v1/workflows/weekly-report \
     -H "Authorization: Bearer $EPHEMERAL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "prompt": "Write the weekly business report for input.period. Call GET /metrics?period=<input.period> on the analytics connection and use only what it returns. Reply in Markdown, at most 150 words: a one-line headline, then signups, active users, revenue in dollars and churned accounts, each with the change from the week before. If the call fails, say so instead of estimating.",
       "connections": { "analytics": { "ref": "analytics-api", "allowed_methods": ["GET"] } },
       "shell": false,
       "timeout_seconds": 120
     }'

   Não há configuração de web, então a execução não tem nenhum acesso à internet; o único alcance dela é a conexão de análises. Um fluxo de trabalho não pode guardar input, um orçamento nem um callback; eles vêm com cada execução.

4. Agende para a manhã de segunda-feira

   0 9 * * 1 é 09:00 nas segundas-feiras, lido no timezone do agendamento. O input do agendamento é o que toda execução iniciada por ele recebe, então é aqui que você define o período. Pré-visualize primeiro.

   cURLCLIResposta

   curl -X POST $EPHEMERAL_URL/v1/schedules/preview \
     -H "Authorization: Bearer $EPHEMERAL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "cron": "0 9 * * 1", "timezone": "Asia/Tokyo" }'

   Os horários estão em UTC: 00:00 UTC é 09:00 em Tóquio. Crie o agendamento:

   cURLCLIResposta

   curl -X POST $EPHEMERAL_URL/v1/schedules \
     -H "Authorization: Bearer $EPHEMERAL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "workflow": "weekly-report",
       "name": "Monday report",
       "cron": "0 9 * * 1",
       "timezone": "Asia/Tokyo",
       "input": { "period": "last_week" },
       "max_cost_micros": 300000
     }'

   O orçamento de $0.30 é reservado a cada início e liberado quando a execução é liquidada. Como o agendamento é dono da entrada, você pode adicionar outro agendamento ao mesmo fluxo de trabalho com uma entrada diferente, ou alterar este depois com PATCH /v1/schedules/{id} e um novo input. Para vê-lo funcionar antes de segunda-feira, inicie uma agora com POST /v1/schedules/{id}/run ou ephemeral schedules run ID.

5. Entregue o relatório

   As execuções agendadas não enviam callbacks, então a entrega é feita coletando o resultado. Este script, executado a cada dez minutos pelo cron ou pelo CI, pede a execução bem-sucedida mais recente do agendamento, envia a saída dela uma única vez e memoriza o ID da execução. Troque a chamada ao Slack por uma chamada ao seu serviço de e-mail se preferir e-mail.

   report.mjs (Node.js 18 ou posterior)

   import { readFile, writeFile } from "node:fs/promises";
   
   const { EPHEMERAL_URL, EPHEMERAL_API_KEY, SCHEDULE_ID, SLACK_WEBHOOK_URL } = process.env;
   const stateFile = "report-state.json";
   const { sent } = JSON.parse(await readFile(stateFile, "utf8").catch(() => "{}"));
   
   const response = await fetch(`${EPHEMERAL_URL}/v1/runs?schedule=${SCHEDULE_ID}&status=succeeded&limit=1`, {
     headers: { Authorization: `Bearer ${EPHEMERAL_API_KEY}` },
   });
   if (!response.ok) throw new Error(`Ephemeral returned ${response.status}`);
   const [run] = (await response.json()).items;
   if (!run || run.id === sent) process.exit(0); // nothing new since the last report
   
   await fetch(SLACK_WEBHOOK_URL, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({ text: run.output }),
   });
   await writeFile(stateFile, JSON.stringify({ sent: run.id }));

   Uma execução que falhou não envia nada, então olhe também GET /v1/runs?schedule={id}&status=failed&limit=1, ou acompanhe o last_error do agendamento, para que um relatório ausente não passe despercebido.

6. Execute de novo um relatório de uma semana passada

   "Iniciar agora" reutiliza a entrada do agendamento, então, para outra semana, inicie o fluxo de trabalho diretamente com o período que você quiser. Desta vez você pode pedir um callback assinado, que entrega o resultado ao seu endpoint assim que estiver pronto. Use uma chave de idempotência que nomeie a semana, para que uma requisição repetida nunca envie um segundo relatório.

   cURLCLI

   curl $EPHEMERAL_URL/v1/runs \
     -H "Authorization: Bearer $EPHEMERAL_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: weekly-report-2026-W38" \
     -d '{
       "workflow": "weekly-report",
       "input": { "period": "2026-W38" },
       "max_cost_micros": 300000,
       "callback": {
         "url": "https://example.com/hooks/ephemeral",
         "secret": "'"$EPHEMERAL_CALLBACK_SECRET"'"
       }
     }'

   O seu endpoint de callback verifica a assinatura e encaminha run.output; o receptor está em a receita de investigação de pagamento. Uma execução iniciada dessa forma não carrega o ID do agendamento, então não aparece em ?schedule=.

Bom saber