Research & Summarize Runbook

Owner: platform-runners Template: Research & Summarize Agent (certified, gallery-visible) Expected duration: ~20 minutes Expected cost range: $0.50–$5.00 Tool profile: web_automation External dependencies: Tavily Web Search API, optional YouTube transcript service

This template’s cost is dominated by Tavily search credits, not LLM tokens. The depth input is the primary cost lever:

quick — 5 sources, ~$0.50
standard — 15 sources, ~$2.00
deep — 30 sources, ~$5.00

Known failure reasons

Reason	What happened	First action
`tavily_api_key_missing_or_invalid`	The org’s Tavily credential is missing or rejected.	Add a Tavily key under Integrations → Tavily.
`tavily_quota_exhausted`	Tavily monthly quota hit.	Customer must top up Tavily; agent cannot work around.
`source_url_unreachable`	One of the explicit `source_urls` returned 4xx/5xx.	Other sources still summarised; check if the failing URL is private/auth-required.
`pdf_extraction_failed`	A PDF source’s text extraction failed.	Often an image-only PDF — out of scope.
`youtube_transcript_unavailable`	YouTube source had no captions.	Skip the video or request a manual transcript.

Diagnostic steps

Did Tavily respond? The first timeline event after session_healthy should be tavily_search_completed with a count ≥ 1. Zero or missing means a Tavily-side issue.
Did each source produce a summary? Look for one source_summarised event per source. A missing event isn’t necessarily a failure (some sources are intentionally skipped), but a count significantly below depth is.
Check sources_cited in outputs. If the customer received a brief with zero citations, that’s a serious failure — escalate.

Rollback / cleanup behavior

From the template’s rollback_or_cleanup_behavior:

Cancelling the run discards in-flight summaries.
Downstream channels (Slack, email) are not notified.
Tavily search credits already spent are not refunded.

Escalation

If sources_cited is 0 OR the brief content does not match the research_topic, ping platform-runners with the diagnostics bundle. That class of failure usually means a corrupt prompt template or a Tavily result-set mismatch.