Einen Wochenbericht senden

Lesen Sie jeden Montag um 09:00 Uhr in Tokio die Zahlen der letzten Woche aus Ihrer Analytics-API, schreiben Sie einen kurzen Bericht und senden Sie ihn an Slack oder per E-Mail. Der Agent liest über eine Verbindung, die nur GET erlaubt, sodass er Ihre Zahlen ansehen, aber nicht ändern kann.

Die Ausführung dauert etwa 10 Sekunden. Den größten Teil der Kosten macht die Rechenzeit aus, die mit $0.0002 pro Sekunde berechnet wird, vier Ausführungen im Monat kosten also etwa einen Cent. Der Anteil des Modells hängt vom gewählten Modell ab; lesen Sie bei den ersten Ausführungen cost_micros aus, um ihn zu sehen.

1. Was Sie brauchen

   • Ein API-Schlüssel mit der Rolle Admin, denn nur Inhaber und Admins erstellen Verbindungen und Zeitpläne. Siehe Rollen und Schlüssel.
   • Ihre Analytics-API über HTTPS und ein Schlüssel nur zum Lesen dafür. Dieses Rezept geht davon aus, dass sie GET /metrics?period=… bietet, wobei period entweder last_week oder eine ISO-Woche wie 2026-W40 ist. Passen Sie die Pfade an Ihre API an.
   • Eine eingehende Slack-Webhook-URL oder ein Endpunkt von Ihnen, der E-Mails sendet.

2. Verbindung nur zum Lesen erstellen

   Die Verbindung hält den API-Schlüssel innerhalb von Ephemeral und erlaubt nur GET. Die instructions sagen dem Agenten, was die API bietet.

   cURLCLIAntwort

   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. Workflow speichern

   Der Prompt liest den Zeitraum aus der Eingabe der Ausführung. Der Agent hat keinen verlässlichen Kalender, übergeben Sie also einen Zeitraum, den Ihre API auflösen kann, etwa last_week, statt den Agenten Datumsangaben ausrechnen zu lassen.

   cURLCLIAntwort

   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
     }'

   Es gibt keine web-Einstellung, die Ausführung hat also gar keinen Internetzugang; ihre einzige Reichweite ist die Analytics-Verbindung. Ein Workflow kann weder input noch ein Budget oder einen Callback enthalten; diese kommen mit jeder Ausführung.

4. Für Montagmorgen einplanen

   0 9 * * 1 ist 09:00 Uhr an Montagen, gelesen in der timezone des Zeitplans. Die input des Zeitplans erhält jede Ausführung, die er startet; hier legen Sie also den Zeitraum fest. Sehen Sie sich ihn zuerst in der Vorschau an.

   cURLCLIAntwort

   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" }'

   Die Zeiten sind in UTC: 00:00 UTC ist 09:00 Uhr in Tokio. Erstellen Sie den Zeitplan:

   cURLCLIAntwort

   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
     }'

   Das Budget von $0.30 wird bei jedem Start reserviert und freigegeben, wenn die Ausführung abgerechnet ist. Da der Zeitplan die Eingabe besitzt, können Sie einen weiteren Zeitplan für denselben Workflow mit anderer Eingabe anlegen oder diesen später mit PATCH /v1/schedules/{id} und einer neuen input ändern. Um ihn vor Montag zu erleben, starten Sie jetzt eine Ausführung mit POST /v1/schedules/{id}/run oder ephemeral schedules run ID.

5. Bericht zustellen

   Geplante Ausführungen senden keine Callbacks, stellen Sie also zu, indem Sie das Ergebnis abholen. Dieses Skript, alle zehn Minuten aus cron oder CI ausgeführt, fragt nach der neuesten erfolgreichen Ausführung des Zeitplans, sendet deren Ausgabe einmal und merkt sich die Ausführungs-ID. Ersetzen Sie den Slack-Aufruf durch einen Aufruf Ihres Mail-Dienstes, wenn Sie E-Mail bevorzugen.

   report.mjs (Node.js 18 oder neuer)

   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 }));

   Eine fehlgeschlagene Ausführung sendet nichts. Sehen Sie sich daher auch GET /v1/runs?schedule={id}&status=failed&limit=1 an oder beobachten Sie das last_error des Zeitplans, damit ein fehlender Bericht nicht unbemerkt bleibt.

6. Einen Bericht für eine vergangene Woche erneut ausführen

   "Jetzt starten" verwendet die Eingabe des Zeitplans erneut. Für eine andere Woche starten Sie daher den Workflow direkt mit dem gewünschten Zeitraum. Diesmal können Sie einen signierten Callback anfordern, der das Ergebnis an Ihren Endpunkt liefert, sobald es fertig ist. Verwenden Sie einen Idempotency-Key, der die Woche nennt, damit eine wiederholte Anfrage nie einen zweiten Bericht sendet.

   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"'"
       }
     }'

   Ihr Callback-Endpunkt prüft die Signatur und leitet run.output weiter; den Empfänger finden Sie im Rezept zur Zahlungsuntersuchung. Eine so gestartete Ausführung trägt nicht die ID des Zeitplans und erscheint daher nicht unter ?schedule=.

Gut zu wissen