Back to Templates

Quickstart

Fan-out workflow that summarizes the top Hacker News stories

Get Code

The quickstart template is a Hacker News digest: fetch the top story IDs, fan out to fetch and summarize each story in parallel, then assemble a digest. It’s a small but real example of the fan-out/fan-in shape, with every step checkpointed so a crash mid-run only re-executes what didn’t finish. No LLM provider is required to see the durability machinery - only the summarization step calls a model.

What you’ll build

  • A fetch_top_ids step that pulls the current top Hacker News story IDs
  • A parallel fan-out that fetches every story with fetch_story
  • A parallel fan-out that summarizes every story with summarize
  • An assemble_digest step that combines the summaries into one digest

Requirements

  • Python 3.12+ or Node.js 22+
  • uv (Python)
  • OPENAI_API_KEY or ANTHROPIC_API_KEY (only the summarize step calls a model)
  • The AGNT5 CLI

Install

curl -LsSf https://agnt5.com/cli.sh | bash

Setup

Scaffold the project

agnt5 create —template python/quickstart my-digest
cd my-digest
agnt5 create —template typescript/quickstart my-digest
cd my-digest

Set environment variables

cp .env.example .env
# uncomment and fill in exactly one of ANTHROPIC_API_KEY or OPENAI_API_KEY

In the TypeScript variant, switching providers also means updating modelName in src/functions.ts.

Install dependencies

uv sync
pip install -e .
npm install

Start the dev server

agnt5 dev

Run the digest workflow

agnt5 run digest --input '{"limit": 5}'

Or open the Studio URL printed in the terminal, pick the digest workflow, set the input to {"limit": 5}, and click Run.

How it works

The digest workflow runs a four-step pipeline. First, a step pulls the current top story IDs from the Hacker News API - one checkpoint. Second, the workflow fans out a fetch call for every id and awaits them together, so all the fetches run concurrently as independent checkpoints. Third, the same pattern fans out a summarize call over every fetched story. Fourth, a final step combines the summaries into the result.

Because every step is its own checkpoint, the fan-out is crash-safe: if the worker dies after 3 of 5 stories have been summarized, replay only re-runs the missing 2 - completed steps return their journaled results instead of re-executing.

Note:

There’s no model call in the fetch steps - only the summarize step calls an LLM, and it does so through the same checkpointed step mechanism, so retries and replay work the same way for model calls as for any other step.

Key files

app.py                          - Worker entry point
src/agnt5_quickstart/workflows.py - digest workflow: fetch IDs, fan out fetch, fan out summarize, assemble
src/agnt5_quickstart/functions.py - fetch_top_ids, fetch_story, summarize, assemble_digest
src/workflows.ts  - digest workflow: fetch IDs, fan out fetch, fan out summarize, assemble
src/functions.ts  - fetchTopIds, fetchStory, summarize, assembleDigest

Customize

Change the source. Swap fetch_top_ids/fetch_story for another API (Reddit, RSS, an internal feed) - the fan-out/fan-in shape in workflows.py doesn’t need to change.

Add a second fan-out stage. Chain another asyncio.gather over ctx.task(...) calls after summarize, e.g. to categorize or score each story before assembly.

Tune concurrency. limit controls how many stories are fetched. Raise or lower it to change the fan-out width per run.

Next steps