> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: "Quickstart: Run your first workflow in AGNT5 Cloud"
description: Create a workflow locally, connect it to an AGNT5 Cloud dev environment, invoke it, and inspect the execution trace.
page_type: tutorial
audience: both
last_verified: 2026-05-13
---

import CopyPromptButton from "../../../components/CopyPromptButton.tsx";



In this quickstart you'll create a workflow locally, connect it to an AGNT5 Cloud dev environment, invoke it, and inspect the execution trace. The workflow itself summarizes the top Hacker News stories — the API is public so there's no Hacker News token to chase; you just bring your own OpenAI key.

**You'll need:** Python 3.12+ Node.js 20+ (with pnpm, npm, or yarn) , an [OpenAI API key](https://platform.openai.com/api-keys), and ~3 minutes. We install the `agnt5` CLI below.

<div class="agnt5-agent-callout">
  <div class="agnt5-agent-callout-head">
    <span class="agnt5-agent-callout-icon" aria-hidden="true">⚡</span>
    <div>
      <strong>Using a coding agent?</strong>
      <p>Paste the prompt below into Claude Code, Cursor, Windsurf, Cline, or Copilot. The agent walks every step on this page for you. If the <a href="/docs/integrations/mcp">AGNT5 MCP server</a> is connected, it'll also inspect the run and trace once the workflow finishes — no clicking through Studio.</p>
    </div>
  </div>

<div class="agnt5-agent-callout-action">
  <p class="agnt5-agent-callout-action-desc">Installs the CLI, scaffolds the project, starts <code>agnt5 dev</code>, and walks you through the first run.</p>


**Python:**

<CopyPromptButton client:load prompt={`Help me run the AGNT5 Hacker News digest quickstart.

1. Install the AGNT5 CLI if not present:
     curl -LsSf https://agnt5.com/cli.sh | bash
   Open a new shell (or 'source' the rc file) so 'agnt5' resolves.

2. Authenticate:
     agnt5 auth login
   This opens a browser to sign in.

3. Scaffold the project:
     agnt5 create my-agnt5-quickstart --template python/quickstart
     cd my-agnt5-quickstart

4. Ask me for my OpenAI API key. Write OPENAI_API_KEY="sk-..." to .env at the project root. Do not commit .env.

5. Start the dev server:
     agnt5 dev
   Wait for it to print a Studio URL and to register these components:
   digest, fetch_top_ids, fetch_story, summarize, assemble_digest.

6. Tell me to open the Studio URL, pick the 'digest' workflow, set the input to {"limit": 5}, and click Run.

7. When the run completes, describe the trace structure: one fetch_top_ids step, five parallel fetch_story steps, five parallel summarize steps, and one assemble_digest step. Point me at where the assembled digest text appears.

If the AGNT5 MCP server is available in your tool list, call list_runs after step 6 and get_trace on the latest run to verify completion and show me the trace tree.

Rules:
- Don't modify workflows.py or functions.py on this first run.
- Keep the summarizer model as openai/gpt-5-mini.
- The HN API is public — no Hacker News token needed.`} />




**TypeScript:**

<CopyPromptButton client:load prompt={`Help me run the AGNT5 Hacker News digest quickstart.

1. Install the AGNT5 CLI if not present:
     curl -LsSf https://agnt5.com/cli.sh | bash
   Open a new shell (or 'source' the rc file) so 'agnt5' resolves.

2. Authenticate:
     agnt5 auth login
   This opens a browser to sign in.

3. Scaffold the project:
     agnt5 create my-agnt5-quickstart --template typescript/quickstart
     cd my-agnt5-quickstart

4. Ask me for my OpenAI API key. Write OPENAI_API_KEY="sk-..." to .env at the project root. Do not commit .env.

5. Start the dev server:
     agnt5 dev
   Wait for it to print a Studio URL and to register these components:
   digest, fetchTopIds, fetchStory, summarize, assembleDigest.

6. Tell me to open the Studio URL, pick the 'digest' workflow, set the input to {"limit": 5}, and click Run.

7. When the run completes, describe the trace structure: one fetchTopIds step, five parallel fetchStory steps, five parallel summarize steps, and one assembleDigest step. Point me at where the assembled digest text appears.

If the AGNT5 MCP server is available in your tool list, call list_runs after step 6 and get_trace on the latest run to verify completion and show me the trace tree.

Rules:
- Don't modify workflows.ts or functions.ts on this first run.
- Keep the summarizer model as openai/gpt-5-mini.
- The HN API is public — no Hacker News token needed.`} />


</div>

  <p class="agnt5-agent-callout-foot">Running the manual commands yourself? Skip this — the same five steps are below.</p>
</div>

## Install the CLI

<Steps>
  <Step title="Install agnt5">
    <CodeGroup>
    <CodeBlock title="curl (macOS, Linux, WSL2)" lang="bash" code={`curl -LsSf https://agnt5.com/cli.sh | bash`} />
    <CodeBlock title="Homebrew (macOS only)" lang="bash" code={`brew install agnt5/tap/agnt5`} />
    </CodeGroup>

    The installer writes `agnt5` to `~/.agnt5/bin` and adds it to your `PATH`. Open a new terminal (or `source` your shell's rc file) so `agnt5` resolves.
  </Step>

  <Step title="Authenticate">
    ```bash
    agnt5 auth login
    ```

    Opens a browser window to sign you into AGNT5. Once it returns, future `agnt5` commands run against your account. For verification, troubleshooting, and API-key auth, see the [full Install guide](/docs/get-started/install.md).
  </Step>
</Steps>

## Run it

<Steps>
  <Step title="Create the project">
    

**Python:**

    ```bash
    agnt5 create --template python/quickstart my-agnt5-quickstart
    cd my-agnt5-quickstart
    ```
    



    

**TypeScript:**

    ```bash
    agnt5 create --template typescript/quickstart my-agnt5-quickstart
    cd my-agnt5-quickstart
    ```
    



    `agnt5 create` downloads the template, registers the project with the Control Plane, and writes the scaffolded files into `my-agnt5-quickstart/`.
  </Step>

  <Step title="Start the dev server">
    ```bash
    agnt5 dev
    ```

    `agnt5 dev` starts a local worker, registers your components with the runtime, and prints a Studio URL:

    

**Python:**

    ```
    Registered components: digest, fetch_top_ids, fetch_story, summarize, assemble_digest
    Worker connected
    Studio: https://app.agnt5.com/anon/<session-id>
    Watching project files
    ```
    



    

**TypeScript:**

    ```
    Registered components: digest, fetchTopIds, fetchStory, summarize, assembleDigest
    Worker connected
    Studio: https://app.agnt5.com/anon/<session-id>
    Watching project files
    ```
    


  </Step>

  <Step title="Open Studio">
    Open the Studio URL from the terminal in your browser. The components your worker just registered show up live — the `digest` workflow is at the top of the list.
  </Step>

  <Step title="Run the digest workflow">
    In Studio:

    1. Pick the `digest` workflow.
    2. Set the input to `{"limit": 5}`.
    3. Click **Run**.

    The trace renders live as each step lands. Click any step to inspect its input, output, and (for model calls) the prompt, response, and cost.
  </Step>
</Steps>

## Notes

- Default model is `openai/gpt-5-mini`. Change it on the `model="..."` line in `functions.py` `functions.ts` .
- Side effects go through `ctx.task(...)`. A bare `await fetch_story(id)` `await fetchStory(id)`  would run every replay and break resume.
- You can also invoke the workflow from the CLI instead of Studio: `agnt5 run digest --input '{"limit": 5}'`.

## What's next

This gets you through the first part of the AGNT5 loop: **Build → Ship → Run → Observe**. For production-ready behavior — promoting to managed environments, invoking from your app, capturing failures into evals — work through [The Loop](/docs/get-started/loop.md).

## Next steps

<CardGroup cols={3}>
  <Card
    title="The AGNT5 loop"
    href="/docs/get-started/loop"
    iconPath="M16.023 9.348h4.992v-.001M2.985 19.644v-4.992m0 0h4.992m-4.993 0l3.181 3.183a8.25 8.25 0 0 0 13.803-3.7M4.031 9.865a8.25 8.25 0 0 1 13.803-3.7l3.181 3.182m0-4.991v4.99"
  >
    Build → Ship → Run → Observe → Improve. The production-ready version of what you just did.
  </Card>
  <Card
    title="Core concepts"
    href="/docs/concepts/workflows-steps-and-agents"
    iconPath="M12 6.042A8.967 8.967 0 0 0 6 3.75c-1.052 0-2.062.18-3 .512v14.25A8.987 8.987 0 0 1 6 18c2.305 0 4.408.867 6 2.292m0-14.25a8.966 8.966 0 0 1 6-2.292c1.052 0 2.062.18 3 .512v14.25A8.987 8.987 0 0 0 18 18a8.967 8.967 0 0 0-6 2.292m0-14.25v14.25"
  >
    Workflows, steps, and agents — how durable execution actually works under the hood.
  </Card>
  <Card
    title="Browse templates"
    href="/templates"
    iconPath="M3.75 3v11.25A2.25 2.25 0 0 0 6 16.5h2.25M3.75 3h-1.5m1.5 0h16.5m0 0h1.5m-1.5 0v11.25A2.25 2.25 0 0 1 18 16.5h-2.25m-7.5 0h7.5m-7.5 0-1 3m8.5-3 1 3m0 0 .5 1.5m-.5-1.5h-9.5m0 0-.5 1.5"
  >
    HITL, deep research, customer support, document processing — production-shaped starting points.
  </Card>
</CardGroup>