# AGNT5 — full documentation

> One runtime for durable AI agent execution — checkpoint every step, trace every call, replay any run for evals.
> For the structured index, see [llms.txt](/llms.txt). For agent operating guidance, see [skill.md](/skill.md).

Source: https://agnt5.com

This file concatenates every page an AI agent should know about, in one fetch. Pages are separated by `---` rules; each starts with an `## H2` title.


# build-with-ai

---

## Build with AI coding agents

_Source: https://agnt5.com/docs/build-with-ai.md_

> Install AGNT5 skills for your coding agent, then use copyable prompts to create, deploy, evaluate, or integrate workflows.

Modern AGNT5 projects often start in an AI coding agent. This page gives Codex, Claude Code, Cursor, Windsurf, Cline, or Copilot AGNT5 skills for creating a **[workflow](/docs/build/workflows.md)**, running it with the **[CLI](/docs/install-cli.md)**, inspecting the **[trace](/docs/run/overview.md)**, and moving the result toward production. Use this path when you want the agent to do the setup work inside your repo while you review each file it changes.

## 1. Install AGNT5 skills

**AGNT5 skills** are project instructions plus task prompts for AI coding agents. The instruction file tells your coding agent how AGNT5 projects are structured, which commands to run, and how to handle secrets. Add the file that matches your tool, then start a new agent thread so the skills load.


  

  
### Codex

Add this to `AGENTS.md` in the target repo. Codex also reads nested `AGENTS.md` files, so place the file at the narrowest directory that owns the AGNT5 project.

```md
# AGNT5 project instructions

- AGNT5 is a durable runtime and observability platform for agentic workflows.
- Use `agnt5 create --template <template> <project-name>` for new projects.
- Prefer the Python template unless the user asks for TypeScript.
- Run `agnt5 auth login` before cloud-backed CLI work.
- Keep secrets in `.env`; never commit `.env`.
- For model providers, use exactly one of `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`.
- Start local runs with `agnt5 dev`, then use the printed Studio URL to inspect runs and traces.
- After the quickstart works, propose deploy, evaluate, and integrate as the next tasks.
```
  

  
### Claude Code

Add this to `CLAUDE.md` or `.claude/CLAUDE.md` in the target repo.

```md
# AGNT5 project instructions

- AGNT5 is a durable runtime and observability platform for agentic workflows.
- Use `agnt5 create --template <template> <project-name>` for new projects.
- Prefer the Python template unless the user asks for TypeScript.
- Run `agnt5 auth login` before cloud-backed CLI work.
- Keep secrets in `.env`; never commit `.env`.
- For model providers, use exactly one of `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`.
- Start local runs with `agnt5 dev`, then use the printed Studio URL to inspect runs and traces.
- After the quickstart works, propose deploy, evaluate, and integrate as the next tasks.
```
  

  
### Cursor

Create a project rule in `.cursor/rules/agnt5.mdc`, or create it from **Cursor Settings > Rules** and paste the body below.

```md
# AGNT5 project instructions

- AGNT5 is a durable runtime and observability platform for agentic workflows.
- Use `agnt5 create --template <template> <project-name>` for new projects.
- Prefer the Python template unless the user asks for TypeScript.
- Run `agnt5 auth login` before cloud-backed CLI work.
- Keep secrets in `.env`; never commit `.env`.
- For model providers, use exactly one of `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`.
- Start local runs with `agnt5 dev`, then use the printed Studio URL to inspect runs and traces.
- After the quickstart works, propose deploy, evaluate, and integrate as the next tasks.
```
  

  
### Windsurf

Create a workspace rule in `.windsurf/rules/agnt5.md`.

```md
---
trigger: always_on
---

# AGNT5 project instructions

- AGNT5 is a durable runtime and observability platform for agentic workflows.
- Use `agnt5 create --template <template> <project-name>` for new projects.
- Prefer the Python template unless the user asks for TypeScript.
- Run `agnt5 auth login` before cloud-backed CLI work.
- Keep secrets in `.env`; never commit `.env`.
- For model providers, use exactly one of `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`.
- Start local runs with `agnt5 dev`, then use the printed Studio URL to inspect runs and traces.
- After the quickstart works, propose deploy, evaluate, and integrate as the next tasks.
```
  

  
### Cline

Create a workspace rule in `.clinerules/agnt5.md`.

```md
# AGNT5 project instructions

- AGNT5 is a durable runtime and observability platform for agentic workflows.
- Use `agnt5 create --template <template> <project-name>` for new projects.
- Prefer the Python template unless the user asks for TypeScript.
- Run `agnt5 auth login` before cloud-backed CLI work.
- Keep secrets in `.env`; never commit `.env`.
- For model providers, use exactly one of `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`.
- Start local runs with `agnt5 dev`, then use the printed Studio URL to inspect runs and traces.
- After the quickstart works, propose deploy, evaluate, and integrate as the next tasks.
```
  

  
### Copilot

Add this to `.github/copilot-instructions.md` in the target repo.

```md
# AGNT5 project instructions

- AGNT5 is a durable runtime and observability platform for agentic workflows.
- Use `agnt5 create --template <template> <project-name>` for new projects.
- Prefer the Python template unless the user asks for TypeScript.
- Run `agnt5 auth login` before cloud-backed CLI work.
- Keep secrets in `.env`; never commit `.env`.
- For model providers, use exactly one of `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`.
- Start local runs with `agnt5 dev`, then use the printed Studio URL to inspect runs and traces.
- After the quickstart works, propose deploy, evaluate, and integrate as the next tasks.
```
  


## 2. Give the agent a task

Pick the prompt that matches the work you want done. Each prompt tells the agent to use AGNT5 templates when they fit, ask before choosing a model provider, keep secrets out of git, and verify the result with `agnt5 dev` or the relevant docs path.


  

### Run the Hacker News quickstart

Create the digest workflow, configure Anthropic or OpenAI, start the dev server, and inspect the trace.

```text
Help me run the AGNT5 Hacker News digest quickstart in this repo.

Use Python unless I ask for TypeScript. Install the AGNT5 CLI if it is missing, authenticate with agnt5 auth login, scaffold the quickstart template, copy .env.example to .env, and ask whether I want Anthropic or OpenAI before editing the model provider key.

Start agnt5 dev, wait for the Studio URL, tell me how to run the digest workflow with {"limit": 5}, and verify that the trace shows fetch, summarize, and assemble steps. Do not commit .env.
```


  

### Build from a template

Start with the closest AGNT5 template, then adapt it to the app you describe.

```text
Help me choose and adapt an AGNT5 template for this application.

First ask me what event starts the workflow, what external systems it calls, whether a human approval step is required, and which model provider I want to use. Then choose the closest AGNT5 template, scaffold it with agnt5 create, and explain the files you changed.

Run the local worker with agnt5 dev. Keep secrets in .env, avoid committing .env, and leave me with the Studio URL and the exact input payload to test the first run.
```


  

### Add a webhook workflow

Create a workflow that starts from an external event source and records a trace.

```text
Add an AGNT5 workflow that starts from a webhook.

Use the AGNT5 webhook docs to design the handler, validate the incoming request, map the payload into a workflow input, and keep duplicate deliveries safe. Add a local test payload I can run. Start agnt5 dev and show me how to trigger the workflow from Studio or a local HTTP request.
```


  

### Add human approval

Insert a durable approval checkpoint before a side effect runs.

```text
Add human approval to this AGNT5 workflow.

Find the step that performs the side effect. Before that step runs, add an approval checkpoint that shows the proposed action and captures approve or reject. Make the workflow return a clear rejected result when approval is denied.

Run or describe the narrowest verification path, and point me to the trace node where the workflow pauses.
```


  

### Evaluate a workflow

Turn recent runs into a dataset, add scorers, and compare a prompt or model change.

```text
Create an AGNT5 evaluation plan for this workflow.

Inspect the workflow inputs, outputs, and traces. Propose a small dataset from recent or representative runs, define deterministic scorers first, and add an LLM-as-judge scorer only where deterministic checks are not enough.

Then make the smallest code or config changes needed to run the eval loop and compare one prompt or model change against the current behavior.
```


  

### Integrate an existing app

Connect an app event to AGNT5 and return a result the application can consume.

```text
Integrate AGNT5 into this existing application.

Find the application event that should start the workflow. Add the smallest integration layer that sends a structured workflow input to AGNT5, handles success and failure responses, and records the run ID for later trace lookup.

Keep the application boundary clear: app code starts the workflow, AGNT5 owns durable execution, and Studio owns run inspection.
```




## 3. Review the result

Treat the coding agent as the driver, not the reviewer. Before you keep the generated code:

1. Check that `.env` is ignored and no API key appears in git.
2. Run the command the agent used, usually **agnt5 dev** for local verification.
3. Open the Studio URL and confirm the trace has the expected workflow steps.
4. Read the changed files and remove unused scaffolding.
5. Ask the agent to summarize deploy, evaluate, and integrate follow-ups.

## Next steps



Once the agent has created a working workflow, move it through the same path as a manually built project.

- [Run the quickstart](/docs/quickstart): Build the Hacker News digest workflow and inspect its first trace.
- [Deploy the workflow](/docs/run/deploying): Set secrets, create an environment, and run the worker outside local dev.
- [Evaluate the output](/docs/improve/overview): Compare prompt and model changes with datasets and scorers.


# Build

---

## Agents

_Source: https://agnt5.com/docs/build/agents.md_

> Configure LLM agents with instructions, models, tools, handoffs, and loop limits.

An **Agent** is an LLM that runs in a loop: it reads your instructions, calls tools when it needs to, and keeps going until it has a final answer. You give it a model, a purpose, and optionally a set of tools. The SDK handles the loop, tool dispatch, and result collection.

---

## Creating an Agent

Three things are required: a name, a model, and instructions.

```python
from agnt5 import Agent

agent = Agent(
    name="researcher",
    model="openai/gpt-4o-mini",
    instructions="You are a research assistant. Answer questions with cited sources.",
)
```

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | `str` | yes | Identifier for this agent |
| `model` | `str` | yes | Model to use, as `"provider/model-name"` (e.g. `"openai/gpt-4o"`, `"anthropic/claude-3-5-sonnet-20241022"`) |
| `instructions` | `str` | yes | System prompt that tells the agent its role and behavior |
| `tools` | `list` | no | Tools the agent can call (see [Tools](#tools)) |
| `built_in_tools` | `list[BuiltInTool]` | no | Provider-hosted tools like web search (see [Built-in Tools](#built-in-tools)) |
| `handoffs` | `list` | no | Agents to delegate to (see [Handoffs](#handoffs)) |
| `max_iterations` | `int` | no | Max reasoning loops before stopping. Default: `10` |
| `temperature` | `float` | no | Sampling temperature (0–1). Lower = more deterministic. Default: `0.7` |
| `max_tokens` | `int` | no | Maximum tokens in the model response |
| `top_p` | `float` | no | Top-p nucleus sampling (0–1) |
| `model_config` | `ModelConfig` | no | Custom endpoint config: `base_url`, `api_key`, `timeout`, `headers` |

**Example with generation settings:**

```python
agent = Agent(
    name="analyst",
    model="openai/gpt-4o-mini",
    instructions="You are a precise data analyst.",
    temperature=0.2,      # more focused, less creative
    max_tokens=4096,
    max_iterations=5,
)
```

---

## Running an Agent

### `run()`: wait for the final answer

Use `run()` when you want the complete result in one call.

```python
result = await agent.run("What causes northern lights?")
print(result.output)
```

`result.output` is the agent's final text response. `result.tool_calls` lists every tool call made along the way.

### `stream()`: receive events as they happen

Use `stream()` when you want to show output progressively or react to tool calls in real time.

```python
async for event in agent.stream("What causes northern lights?"):
    if event.event_type == "lm.content_block.delta":
        print(event.content, end="", flush=True)
```

Key event types:

| Event type | When it fires |
|---|---|
| `agent.started` | Agent loop begins |
| `lm.content_block.delta` | A chunk of the LLM response arrives |
| `lm.content_block.completed` | LLM response block is complete |
| `tool_call.started` | A tool call begins |
| `tool_call.completed` | A tool call finishes |
| `agent.completed` | Agent loop ends. Final answer is available |

---

## Tools

Tools give your agent the ability to take actions: call an API, run code, or search the web. Pass them via `tools` (custom functions or other agents) or `built_in_tools` (provider-hosted tools like web search).

See [Tools](/docs/build/tools.md) for the full reference. Covers custom tools, sandbox workspaces, built-in tools, and human-in-the-loop tools.

---

## Multi-Agent Patterns

### Agents as tools

The calling agent invokes a specialist, gets the result back, and continues its own reasoning. Good for workflows where the coordinator needs to synthesize results from multiple specialists.

```python
from agnt5 import Agent

research_agent = Agent(
    name="researcher",
    model="openai/gpt-4o-mini",
    instructions="You research topics and return concise summaries.",
)

analyst_agent = Agent(
    name="analyst",
    model="openai/gpt-4o-mini",
    instructions="You analyze data and identify trends.",
)

coordinator = Agent(
    name="coordinator",
    model="openai/gpt-4o-mini",
    instructions="Use the researcher and analyst to answer complex questions.",
    tools=[research_agent, analyst_agent],   # each becomes ask_researcher / ask_analyst
)

result = await coordinator.run("What are the latest trends in renewable energy?")
print(result.output)
```

### Handoffs

The calling agent transfers control entirely to a specialist. The specialist runs and its output is returned as the final result. Good for routing: when the triage agent's job is done once it knows who should handle the request.

```python
from agnt5 import Agent, handoff

billing_agent = Agent(
    name="billing",
    model="openai/gpt-4o-mini",
    instructions="You handle billing questions and subscription changes.",
)

technical_agent = Agent(
    name="technical",
    model="openai/gpt-4o-mini",
    instructions="You handle technical support and bug reports.",
)

triage_agent = Agent(
    name="triage",
    model="openai/gpt-4o-mini",
    instructions="Route the user to the right specialist.",
    handoffs=[
        handoff(billing_agent, "Transfer when the user has a billing or payment question"),
        handoff(technical_agent, "Transfer when the user has a technical or product issue"),
    ],
)

result = await triage_agent.run("My payment failed but I was still charged.")
print(result.output)          # billing_agent's response
print(result.handoff_to)      # "billing"
```

`handoff()` parameters:

| Parameter | Type | Default | Description |
|---|---|---|---|
| `agent` | `Agent` | required | The target agent |
| `description` | `str` | agent's instructions | What the LLM sees when deciding whether to hand off |
| `tool_name` | `str` | `transfer_to_{name}` | Custom name for the transfer tool |
| `pass_full_history` | `bool` | `True` | Whether to pass the full conversation to the target agent |

To hand off without customization, pass the agent directly (no `handoff()` call needed):

```python
triage_agent = Agent(
    name="triage",
    model="openai/gpt-4o-mini",
    instructions="Route the user to the right specialist.",
    handoffs=[billing_agent, technical_agent],   # simple form
)
```

---

## Functions

_Source: https://agnt5.com/docs/build/functions.md_

> Define stateless units of work that AGNT5 can register, retry, time out, and checkpoint inside workflows.

A **function** is a stateless unit of work: it receives inputs, runs your logic, and returns a result. The platform handles registration, retries, and timeouts. When called via `ctx.step()` inside a workflow, the result is checkpointed so a restart never runs it twice.

## Creating a function

One thing is required: a decorated async (or sync) Python function.

```python
from agnt5 import function, FunctionContext

@function
async def send_email(ctx: FunctionContext, to: str, subject: str, body: str) -> str:
    # call your email provider here
    return f"Sent to {to}"
```

| Parameter | Type | Default | Description |
|---|---|---|---|
| `name` | `str` | `function.__name__` | How the function appears in the platform. |
| `retries` | `int \| RetryPolicy` | `None` | How many times to retry on failure. |
| `backoff` | `str \| BackoffPolicy` | `None` | How to space out retries: `"constant"`, `"linear"`, or `"exponential"`. |
| `timeout_ms` | `int` | `None` | Cut off the function after this many milliseconds. |

**Example with retries and timeout:**

```python
@function(name="send_email", retries=3, backoff="exponential", timeout_ms=10000)
async def send_email(ctx: FunctionContext, to: str, subject: str, body: str) -> str:
    ctx.logger.info("Sending email", to=to)
    # call your email provider here
    return f"Sent to {to}"
```

Sync functions work too. AGNT5 automatically runs them in a thread pool.


## FunctionContext

Name the first parameter `ctx` and AGNT5 injects a `FunctionContext` automatically.

```python
@function
async def send_email(ctx: FunctionContext, to: str, subject: str, body: str) -> str:
    ctx.logger.info("Sending email", to=to, attempt=ctx.attempt)
    # call your email provider here
    return f"Sent to {to}"
```

| Property / method | Description |
|---|---|
| `ctx.run_id` | Unique ID for this execution (useful for logging and tracing) |
| `ctx.attempt` | Which retry this is (0 = first try) |
| `ctx.logger` | Structured logger. Pass extra fields as keyword args: `ctx.logger.info("msg", key=value)` |
| `ctx.sleep(seconds)` | Pause execution without blocking the event loop |

If you don't need context, leave `ctx` out and the function still works fine.

---

## Retries and backoff

### Shorthand

Pass an integer for retries and a string for the backoff strategy.

```python
@function(retries=3, backoff="exponential")
async def send_email(ctx: FunctionContext, to: str, subject: str, body: str) -> str:
    if ctx.attempt > 0:
        ctx.logger.info("Retrying email", to=to, attempt=ctx.attempt)
    # call your email provider here
    return f"Sent to {to}"
```

### Full control

Use `RetryPolicy` and `BackoffPolicy` for precise tuning.

```python
from agnt5 import function, FunctionContext
from agnt5.types import RetryPolicy, BackoffPolicy, BackoffType

@function(
    retries=RetryPolicy(max_attempts=5, initial_interval_ms=500, max_interval_ms=30000),
    backoff=BackoffPolicy(type=BackoffType.EXPONENTIAL, multiplier=2.0),
)
async def send_email(ctx: FunctionContext, to: str, subject: str, body: str) -> str:
    ctx.logger.info("Sending email", to=to, attempt=ctx.attempt)
    # call your email provider here
    return f"Sent to {to}"
```

`RetryPolicy` parameters:

| Parameter | Default | Description |
|---|---|---|
| `max_attempts` | `3` | Total tries, including the first |
| `initial_interval_ms` | `1000` | Wait before the first retry |
| `max_interval_ms` | `60000` | Maximum wait between retries |

`BackoffPolicy` parameters:

| Parameter | Default | Description |
|---|---|---|
| `type` | `EXPONENTIAL` | `CONSTANT` (fixed wait), `LINEAR` (grows steadily), `EXPONENTIAL` (doubles each time) |
| `multiplier` | `2.0` | How fast the wait grows |

AGNT5 runs your function body once per attempt. Use `ctx.attempt` if you need to vary behaviour on retries.

---

## Calling from a workflow

Inside a workflow, always call functions with `ctx.step()`. This tells AGNT5 to checkpoint the result. If the workflow restarts, the function is skipped and the saved result is returned directly.

```python
from agnt5 import workflow, WorkflowContext
from myapp.functions import send_email

@workflow
async def notify_workflow(ctx: WorkflowContext, user_email: str) -> str:
    result = await ctx.step(send_email, user_email, "Welcome!", "Thanks for signing up.")
    return result
```

`result` is whatever `send_email` returned. A plain `await send_email(ctx, ...)` also works but is not checkpointed. The function re-runs on every replay.

| How you call it | Checkpointed | When to use |
|---|---|---|
| `await ctx.step(send_email, ...)` | Yes | Inside a workflow (always prefer this) |
| `await send_email(ctx, ...)` | No | Outside a workflow, or in local tests |

---

## Human-in-the-loop

_Source: https://agnt5.com/docs/build/human-in-the-loop.md_

> Pause workflows for durable human input, approvals, selections, and follow-up decisions.

Human-in-the-loop (HITL) lets a workflow pause mid-execution, wait for a human to respond, then continue from exactly where it left off. The pause is durable. If the worker restarts while waiting, the workflow resumes correctly when the user eventually replies.

Call `ctx.wait_for_user()` anywhere inside a workflow to trigger a pause.

---

## How it works

Call `ctx.wait_for_user()` at any point in your workflow. The workflow pauses there, shows the question to the user, and resumes from that exact point once they respond. The pause survives worker restarts. The state is saved and nothing is lost.

---

## `ctx.wait_for_user()` parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `question` | `str` | required | The text shown to the user |
| `input_type` | `str` | `"text"` | Input mode (see below) |
| `options` | `list[dict]` | `None` | Choices for `approval`, `select`, and `multiselect`. Each dict needs `"id"` and `"label"` |
| `allow_custom` | `bool` | `False` | Adds a free-text "Something else" option to `select` and `multiselect` |
| `skippable` | `bool` | `False` | Adds a Skip button. Returns `None` when skipped |

---

## Input types

### `text`: free text

The user types any response. Use this for open-ended input like names, instructions, or edited content.

```python
name = await ctx.wait_for_user("What should we call this report?")
```

### `approval`: yes / no

Present a clear action and let the user approve or reject it.

```python
decision = await ctx.wait_for_user(
    question="Deploy to production?",
    input_type="approval",
    options=[
        {"id": "approve", "label": "Approve"},
        {"id": "reject", "label": "Reject"},
    ],
)

if decision == "reject":
    return {"status": "cancelled"}
```

### `select`: pick one

The user picks a single option from a list.

```python
format = await ctx.wait_for_user(
    question="Which output format do you want?",
    input_type="select",
    options=[
        {"id": "pdf", "label": "PDF"},
        {"id": "markdown", "label": "Markdown"},
        {"id": "html", "label": "HTML"},
    ],
)
```

### `multiselect`: pick many

The user picks one or more options. The return value is a comma-separated string of the selected `id`s.

```python
topics = await ctx.wait_for_user(
    question="Which topics should the report cover?",
    input_type="multiselect",
    options=[
        {"id": "market", "label": "Market analysis"},
        {"id": "tech", "label": "Technology trends"},
        {"id": "risk", "label": "Risk factors"},
    ],
)
# topics might be "market,tech"
selected = topics.split(",")
```

---

## Options: `allow_custom` and `skippable`

`allow_custom=True` adds a free-text "Something else" field to `select` or `multiselect`.

`skippable=True` adds a Skip button. The return value is `None` when the user skips.

```python
preference = await ctx.wait_for_user(
    question="Pick a tone for the report:",
    input_type="select",
    options=[
        {"id": "formal", "label": "Formal"},
        {"id": "casual", "label": "Casual"},
    ],
    allow_custom=True,
    skippable=True,
)

if preference is None:
    preference = "formal"   # default when skipped
```

---

## Multiple pauses in one workflow

You can call `ctx.wait_for_user()` as many times as you need. Each call gets its own pause index so the right cached answer is returned on replay.

```python
@workflow
async def review_workflow(ctx: WorkflowContext, draft: str) -> str:
    # First pause: approval
    decision = await ctx.wait_for_user(
        question=f"Approve this draft?\n\n{draft}",
        input_type="approval",
        options=[
            {"id": "approve", "label": "Approve"},
            {"id": "edit", "label": "Edit"},
            {"id": "reject", "label": "Reject"},
        ],
    )

    if decision == "reject":
        return "Rejected."

    if decision == "edit":
        # Second pause: get edited version
        draft = await ctx.wait_for_user(
            question="Paste your revised draft:",
            input_type="text",
        )

    # Third pause: final confirmation before publishing
    confirm = await ctx.wait_for_user(
        question="Publish now?",
        input_type="approval",
        options=[
            {"id": "yes", "label": "Publish"},
            {"id": "no", "label": "Save as draft"},
        ],
    )

    return "Published." if confirm == "yes" else "Saved as draft."
```

---

## Real-world example

A customer submits a refund request. An AI agent reviews it and produces a recommendation. A support agent then steps in at four points: decide the outcome, adjust the amount if needed, pick the refund method, and confirm before money moves.

```python
from agnt5 import Agent, workflow, WorkflowContext, function, FunctionContext
from agnt5.lm import BuiltInTool


# ── Step 1: AI analyses the refund request ──────────────────────────────────

@function
async def analyse_refund(ctx: FunctionContext, order_id: str, reason: str) -> dict:
    """Look up the order and produce a refund recommendation."""
    # In practice: fetch order from your database
    return {
        "order_id": order_id,
        "order_total": 149.99,
        "eligible": True,
        "suggested_amount": 149.99,
        "reason": reason,
        "summary": f"Order {order_id}, $149.99, eligible for full refund. Reason: {reason}",
    }


# ── Step 2: Process the approved refund ─────────────────────────────────────

@function
async def process_refund(
    ctx: FunctionContext,
    order_id: str,
    amount: float,
    method: str,
    notify_channels: list[str],
) -> dict:
    """Issue the refund and send notifications."""
    # In practice: call your payments API and notification service
    ctx.logger.info(f"Refund processed: ${amount} via {method} for order {order_id}")
    return {
        "status": "refunded",
        "order_id": order_id,
        "amount": amount,
        "method": method,
        "notified_via": notify_channels,
    }


# ── Workflow ─────────────────────────────────────────────────────────────────

@workflow
async def refund_approval_workflow(
    ctx: WorkflowContext,
    order_id: str,
    reason: str,
) -> dict:

    # Stage 1: AI reviews the request
    analysis = await ctx.step(analyse_refund, order_id, reason)

    if not analysis["eligible"]:
        return {"status": "ineligible", "order_id": order_id}

    # ── HITL pause 1: approve / modify / reject ──────────────────────────────
    if not ctx._is_replay:
        ctx.logger.info("Waiting for support agent decision...")

    decision = await ctx.wait_for_user(
        question=(
            f"{analysis['summary']}\n\n"
            f"Suggested refund: ${analysis['suggested_amount']}\n\n"
            "What would you like to do?"
        ),
        input_type="select",
        options=[
            {"id": "approve", "label": "Approve full refund"},
            {"id": "modify",  "label": "Approve with a different amount"},
            {"id": "reject",  "label": "Reject refund"},
        ],
    )

    if decision == "reject":
        return {"status": "rejected", "order_id": order_id}

    # ── HITL pause 2: custom amount (only if modifying) ──────────────────────
    refund_amount = analysis["suggested_amount"]

    if decision == "modify":
        raw = await ctx.wait_for_user(
            question=f"Enter the refund amount (order total: ${analysis['order_total']}):",
            input_type="text",
        )
        refund_amount = float(raw)

    # ── HITL pause 3: pick refund method ─────────────────────────────────────
    method = await ctx.wait_for_user(
        question="How should the refund be returned to the customer?",
        input_type="select",
        options=[
            {"id": "original",     "label": "Original payment method"},
            {"id": "store_credit", "label": "Store credit"},
            {"id": "bank",         "label": "Bank transfer"},
        ],
    )

    # ── HITL pause 4: pick notification channels ──────────────────────────────
    channels_raw = await ctx.wait_for_user(
        question="Notify the customer via:",
        input_type="multiselect",
        options=[
            {"id": "email", "label": "Email"},
            {"id": "sms",   "label": "SMS"},
            {"id": "push",  "label": "Push notification"},
        ],
    )
    notify_channels = channels_raw.split(",") if channels_raw else ["email"]

    # ── HITL pause 5: final confirmation before money moves ───────────────────
    confirm = await ctx.wait_for_user(
        question=(
            f"Ready to process:\n"
            f"  Order:   {order_id}\n"
            f"  Amount:  ${refund_amount}\n"
            f"  Method:  {method}\n"
            f"  Notify:  {', '.join(notify_channels)}\n\n"
            "Confirm?"
        ),
        input_type="approval",
        options=[
            {"id": "confirm", "label": "Confirm & Process"},
            {"id": "cancel",  "label": "Cancel"},
        ],
    )

    if confirm == "cancel":
        return {"status": "cancelled", "order_id": order_id}

    # Stage 2: process the refund
    result = await ctx.step(process_refund, order_id, refund_amount, method, notify_channels)
    return result
```

What each pause does:

| Pause | Input type | Purpose |
|---|---|---|
| 1 | `select` | Support agent decides: full refund, modified amount, or reject |
| 2 | `text` | Agent enters a custom amount (only shown when modifying) |
| 3 | `select` | Agent picks the refund method |
| 4 | `multiselect` | Agent picks which channels to notify the customer on |
| 5 | `approval` | Final review before the refund is actually processed |

---

## Under the hood: replay behaviour

Understanding this helps when things do not behave the way you expect.

When `ctx.wait_for_user()` is called for the first time, the workflow saves its state and stops. When the user responds, AGNT5 runs the workflow function again **from the very top**. All the code before `wait_for_user()` runs again, but this time `wait_for_user()` finds the saved answer and returns it immediately without pausing.

This means anything before the pause fires twice: once before the user responds, and once on resume.

```
First run:   generate_draft() → wait_for_user() → pauses ⏸
On resume:   generate_draft() → wait_for_user() → returns answer → publish() ✅
```

**Wrap side effects with `if not ctx._is_replay:`** to make them fire only once:

```python
@workflow
async def publish_workflow(ctx: WorkflowContext, topic: str) -> str:
    draft = await generate_draft(topic)

    # Without the guard, this log fires twice (before and after the pause)
    if not ctx._is_replay:
        ctx.logger.info("Draft ready, waiting for approval...")

    decision = await ctx.wait_for_user(   # never guarded, must run on both passes
        question=f"Approve this draft?\n\n{draft}",
        input_type="approval",
        options=[
            {"id": "approve", "label": "Approve"},
            {"id": "discard", "label": "Discard"},
        ],
    )

    if decision == "discard":
        return "Discarded."

    return await publish(draft)
```

<Callout type="tip">**Rule:** Guard side effects, never guard the pause itself.</Callout>

---

## Edge cases

**User skips the question**

When `skippable=True`, the return value is `None` if the user clicks Skip. Always handle `None` explicitly to avoid a `TypeError` later.

```python
note = await ctx.wait_for_user(
    question="Any special instructions?",
    input_type="text",
    skippable=True,
)

instructions = note or "No special instructions."
```

**User enters unexpected text in a `text` input**

`wait_for_user()` returns whatever the user typed as a plain string. If you need a number or a specific format, validate and convert it yourself:

```python
raw = await ctx.wait_for_user("Enter the refund amount (numbers only):")

try:
    amount = float(raw)
except ValueError:
    return {"status": "error", "message": f"Invalid amount: {raw}"}
```

**Conditional pause: pause only sometimes**

`wait_for_user()` can be inside an `if` block. The pause index is tracked per call that actually executes, so conditional pauses work correctly across replays.

```python
decision = await ctx.wait_for_user(
    question="Approve or modify?",
    input_type="select",
    options=[
        {"id": "approve", "label": "Approve"},
        {"id": "modify",  "label": "Modify amount"},
    ],
)

if decision == "modify":
    # This pause only runs when the agent chose "modify"
    raw = await ctx.wait_for_user("Enter the new amount:")
    amount = float(raw)
```

**Side effects before a pause that must not repeat**

If you need to send a notification or call an external API before the pause, wrap it in `if not ctx._is_replay:` so it only fires on the first pass:

```python
if not ctx._is_replay:
    await send_slack_alert(f"Refund request {order_id} needs review.")

decision = await ctx.wait_for_user("Approve refund?", input_type="approval", options=[...])
```

---

## Local development

_Source: https://agnt5.com/docs/build/local-development.md_

> Run your project locally with agnt5 dev, with live reload plus triggering workflows from Studio, the CLI, or the API.

Use `agnt5 dev` to run your project locally. Once running, you can trigger workflows from Studio in the browser, the CLI, or the API.

---

## Development - `agnt5 dev`

`agnt5 dev` starts the AGNT5 runtime and your worker together. It boots the local platform, then starts your worker and keeps it running.

**Prerequisites:**

- Dependencies installed: `uv sync`
- Your API key set as an environment variable:

```bash
export OPENAI_API_KEY=sk-...
```
**Start:**

```bash
agnt5 dev
```

Terminal output:

```
╭──────────────────────────────────────────────────────────────────╮
│  ⭓  agnt5 dev                                                    │
│     20260530-9694ef · managed                                    │
│     ~/Documents/agnt5/agnt5/sdk/templates/python/travel_booking  │
╰──────────────────────────────────────────────────────────────────╯
  worker       uv run --no-sync python app.py (pid 21991)
  coordinator  http://grpc.agnt5.com:3418
  watch        3 dirs · .py .ts .js .go .env

  Starting customer-service worker…

  customer-service v1.0.0
  ────────────────────────────────────────
  ◆ workflows (1)
    └── travel_booking_workflow
  ● agents (1)
    └── travel_booking_agent
  ◇ tools (3)
    ├── create_itinerary
    ├── search_flights
    └── search_hotels
  ────────────────────────────────────────

  Connecting to coordinator (http://grpc.agnt5.com:3418)...
  Connected to coordinator (http://grpc.agnt5.com:3418)
```

**Studio:** `https://app.agnt5.com/projects/a3e7af1d-c453-4124-be15-f72bd658889d/components`

Once running, open the Studio link printed in the terminal to launch the browser UI. From there you can trigger workflows, run individual functions and agents, and watch traces, all from the UI without writing any extra code.

### Zero-restart development

`agnt5 dev` watches your project and automatically reloads the worker when anything changes, no need to stop and restart:

- **Code changes** - save a source file and the worker restarts and re-registers in seconds.
- **Environment variable changes** - update your `.env` (credentials, API keys, config) and the worker picks them up immediately on reload.

Most tools require you to manually restart your worker after every change. With `agnt5 dev`, the inner loop stays out of your way.

<Callout type="info">Set deployment secrets separately when you deploy.</Callout>

---

## Studio

Studio is the browser UI for triggering workflows, watching traces, and responding to human-in-the-loop pauses. Open it via the Studio link printed when `agnt5 dev` starts.

### Triggering a workflow

1. Open the Studio link from the terminal in your browser.
2. Select `travel_booking_workflow` from the workflow list.
3. Set the input:

```json
{
  "message": "2 adults are traveling from Los Angeles (LAX) to New York (JFK), departing on June 28, 2026, and returning on June 30, 2026."
}
```

4. Click **Run workflow**.

The run appears immediately in the Runs view. Click into it to see the live trace.

### Watching a trace

As the workflow runs, the trace tree updates in real time. Each node shows its duration, inputs, and outputs. Click a node to expand the full detail, including agent tool calls and LLM responses.

<DocsImage
  src="/docs/integrations/Trace-dev-light.png"
  darkSrc="/docs/integrations/Trace-dev-dark.png"
  alt="Screenshot of the AGNT5 Studio trace view for a completed travel_booking_workflow run. The left panel shows the trace tree with workflow, agent iterations, LLM calls, and tool calls. The right panel shows the input and the agent's final output with flight options."
  caption="The trace tree updates in real time as the workflow runs. Expand any node to inspect inputs, outputs, and LLM token usage."
  width={1008}
  height={639}
/>
---

## Creating an X-API-KEY

Both the CLI and API require a service key passed as the `X-API-KEY` header to authenticate requests. Create one before running either.

<Callout type="warning">The key is shown only once. Copy it to a secure location immediately, you cannot retrieve it again.</Callout>

### Via Studio

1. Open Studio and go to your project.
2. Click **Settings** in the left sidebar.
3. Navigate to **Service Keys**.
4. Click **Create service key**, give it a name, and confirm.
5. Copy the key (it starts with `agnt5_sk_`) and save it somewhere secure, it will not be shown again.

### Via the CLI

```bash
agnt5 service-keys create --name "my-service-key" --project <project-id>
```

---

## Running from the CLI

Use `agnt5 run` to trigger a component directly from the terminal. Without `--env`, it automatically routes to your local dev worker with no extra configuration needed.

```bash
# Run a function (streams output as it arrives)
agnt5 run hello_world --input '{"name": "Alice"}'

# Run a workflow
agnt5 run travel_booking_workflow \
  --type workflow \
  --input '{"message": "2 adults traveling from LAX to JFK, June 28–30"}'

# Run a tool
agnt5 run search_flights \
  --type tool \
  --input '{"departure_id": "LAX", "arrival_id": "JFK", "adults": 2}'

# Run an agent — input must include a "message" field
agnt5 run travel_booking_agent \
  --type agent \
  --input '{"message": "Find me flights from LAX to JFK in late June"}'
```

Functions stream output to the terminal as they run. Workflows, tools, and agents return JSON when the execution completes. If `--type` is omitted, the CLI defaults to `function` and auto-detects the actual type if needed.

Pipe or redirect output for scripting:

```bash
agnt5 run search_flights --type tool --input '{"adults": 2}' | jq '.flights[0]'
agnt5 run my_workflow --type workflow --input '{}' > result.json
```

To run against a deployed environment instead of the local worker, add `--env <environment-name>`. See [Deploying](/docs/run/deploying.md#via-the-cli) for the full reference.


---

## Triggering via the API

You can trigger any workflow directly with `curl`. The easiest way to get the exact command, with your workspace ID and deployment ID already filled in, is to copy it straight from Studio:

1. Open Studio and navigate to the component you want to run.
2. Click the **copy curl** button on the component.
3. Paste it into your terminal and replace the `X-API-KEY` value with your service key.

The copied command will look like:

```bash
curl -X POST 'https://gw.agnt5.com/v1/workflows/travel_booking_workflow/run' \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: agnt5_sk_..." \
  -H "X-WORKSPACE-ID: d03e6b5f-da6a-43e6-9533-f492175f554a" \
  -H "X-DEPLOYMENT-ID: 9a0e18d6-c4a3-464d-b114-9d63f67fd8cd" \
  -d '{"message": "2 adults are traveling from Los Angeles (LAX) to New York (JFK), departing on June 28, 2026, and returning on June 30, 2026."}'
```

---

## Model Context Protocol

_Source: https://agnt5.com/docs/build/mcp.md_

> Connect external MCP servers to AGNT5 agents, or expose AGNT5 tools and agents over a local MCP server.

**Model Context Protocol (MCP)** is an open standard for connecting AI systems to external tools and data sources. AGNT5 supports it in both directions:

- **`MCPClient`** pulls tools from any external MCP server into your agents.
- **`MCPServer`** publishes your AGNT5 tools, agents, workflows, and prompts so any MCP-compatible client can call them.

## Connect external MCP servers

`MCPClient` connects to one or more MCP servers, discovers their tools, and converts those tools into AGNT5 `Tool` objects.

```python
from agnt5 import Agent
from agnt5.mcp import MCPClient

mcp = MCPClient(id="deepwiki-client")
mcp.add_streamable_http_server("deepwiki", "https://mcp.deepwiki.com/mcp")
await mcp.connect()

agent = Agent(
    name="researcher",
    model="openai/gpt-4o-mini",
    instructions="Use available tools to answer questions about code repositories.",
    tools=mcp.get_tools(),
)

result = await agent.run("What is CPython and what is it written in?")
print(result.output)

await mcp.disconnect()
```

Use `async with` when you want the client to connect and disconnect around one block:

```python
from agnt5 import Agent
from agnt5.mcp import MCPClient

mcp = MCPClient(id="deepwiki-client")
mcp.add_streamable_http_server("deepwiki", "https://mcp.deepwiki.com/mcp")

async with mcp:
    agent = Agent(
        name="researcher",
        model="openai/gpt-4o-mini",
        instructions="Use available tools to answer questions about code repositories.",
        tools=mcp.get_tools(),
    )
    result = await agent.run("What is CPython and what is it written in?")
    print(result.output)
```

## Client transports

A client transport defines how AGNT5 connects to an MCP server.

| Transport | Use it for | Python | TypeScript |
|---|---|---|---|
| stdio | Local servers launched as a subprocess | Available | Available |
| Streamable HTTP | Current-spec remote MCP servers over HTTP streaming | Available | Available |
| SSE | Legacy remote servers over Server-Sent Events | Available | Available |

Configure servers with the typed helpers:

```python
from agnt5.mcp import MCPClient

mcp = MCPClient(id="tools")

mcp.add_streamable_http_server("deepwiki", "https://mcp.deepwiki.com/mcp")
mcp.add_sse_server("internal-tools", url="https://example.com/sse", api_key="...")
mcp.add_stdio_server("local", command="npx", args=["-y", "my-mcp-server"])
```

TypeScript uses camelCase helper names:

```typescript
const mcp = new MCPClient("tools");

mcp.addStreamableHttpServer("deepwiki", "https://mcp.deepwiki.com/mcp");
mcp.addSseServer("internal-tools", "https://example.com/sse", {
  Authorization: "Bearer ...",
});
mcp.addStdioServer("local", "npx", ["-y", "my-mcp-server"]);
```

## Work with MCP tools

After `connect()`, the client caches discovered tools. Call a tool directly when you know the server name:

```python
result = await mcp.call_tool("deepwiki", "ask_question", {
    "repoName": "python/cpython",
    "question": "What is CPython?",
})

print(result.get_text())
```

Call by tool name when the server does not matter:

```python
result = await mcp.call_tool_auto("ask_question", {
    "repoName": "python/cpython",
    "question": "What language is CPython written in?",
})

print(result.get_text())
```

Common client methods:

| Method | What it does |
|---|---|
| `connect()` / `disconnect()` | Open and close connections to all configured servers |
| `get_tools()` | Return discovered MCP tools as AGNT5 `Tool` objects for `Agent(tools=...)` |
| `list_tools()` | List every discovered tool with its source server |
| `list_server_tools(server)` | List tools from one server |
| `call_tool(server, name, args)` | Call a tool on a specific server |
| `call_tool_auto(name, args)` | Call the first matching tool name across connected servers |
| `is_connected(server)` | Check whether one server is connected |
| `connected_servers()` | Return connected server names |

<Callout type="info">Always call `connect()` first. The tool list is built from the cache populated during connection.</Callout>

## Expose AGNT5 over MCP

`MCPServer` runs the protocol in reverse: it publishes AGNT5 primitives so MCP-compatible clients can call them. Use stdio for local developer workflows in Claude Desktop, Cursor, VS Code, and similar clients. Use Streamable HTTP when you want to host the server behind an HTTP endpoint.

```python
from agnt5 import Agent
from agnt5.mcp import MCPServer
from agnt5.tool import tool

@tool
async def greet(ctx, name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"

assistant = Agent(
    name="assistant",
    model="openai/gpt-4o-mini",
    instructions="Help the user.",
)

server = MCPServer(
    id="my-server",
    name="My AGNT5 Server",
    version="1.0.0",
    tools={"greet": greet},
    agents={"assistant": assistant},
)

await server.run_stdio()
```

You can register primitives when constructing the server or add them later:

```python
server.add_tool("search", search_tool)
server.add_agent("analyst", analyst_agent)
server.add_workflow("pipeline", my_workflow)
```

## Server transports

| Method | Python | TypeScript |
|---|---|---|
| `run_stdio()` / `runStdio()` | Available | Available |
| `run_http(host, port, path)` / `runHTTP()` | Available | Available |

Server-side legacy SSE hosting is not exposed. Current MCP remote hosting should use Streamable HTTP.

## Next steps

- [Tools](/docs/build/tools.md): define AGNT5 tools that agents and MCP clients can call.
- [Agents](/docs/build/agents.md): attach imported MCP tools to an agent loop.
- [AI providers](/docs/integrations/ai-providers.md): configure model credentials for agents that use MCP tools.
- [Local development](/docs/build/local-development.md): run and test AGNT5 code from your laptop.

---

## Build with AGNT5

_Source: https://agnt5.com/docs/build/overview.md_

> Define workflows, functions, agents, prompts, webhooks, and approval steps before you deploy.

Build is where you define the application code AGNT5 runs. A **[workflow](/docs/build/workflows.md)** is a durable program made of checkpointed steps, an **[agent](/docs/build/agents.md)** is a reasoning loop that can call tools, and a **[function](/docs/build/functions.md)** wraps deterministic work with retries and trace visibility. Use these pages when you are shaping behavior locally before creating a **[deployment](/docs/run/deploying.md)**.

## Build guides

<LinkCardGroup compact>
  <LinkCard
    title="Functions"
    href="/docs/build/functions"
    icon="code"
    description="Wrap deterministic work in retryable, observable units."
  />
  <LinkCard
    title="Workflows"
    href="/docs/build/workflows"
    icon="refresh"
    description="Compose multi-step programs with durable state and checkpointed execution."
  />
  <LinkCard
    title="Agents"
    href="/docs/build/agents"
    icon="user"
    description="Define reasoning loops that call tools and keep state across a run."
  />
  <LinkCard
    title="Tools"
    href="/docs/build/tools"
    icon="settings"
    description="Expose capabilities an agent can call during its loop."
  />
  <LinkCard
    title="Sandboxes"
    href="/docs/build/sandboxes"
    icon="terminal"
    description="Attach isolated file and code execution workspaces to agents."
  />
  <LinkCard
    title="Skills"
    href="/docs/build/skills"
    icon="database"
    description="Load capabilities on demand with SKILL.md folders instead of bloating the prompt."
  />
  <LinkCard
    title="Prompts"
    href="/docs/build/prompts"
    icon="chat"
    description="Keep prompt text versioned and runnable from code."
  />
  <LinkCard
    title="Prompt caching"
    href="/docs/build/prompt-caching"
    icon="database"
    description="Reuse stable prompt prefixes across model calls to cut latency and token spend."
  />
  <LinkCard
    title="Human in the Loop"
    href="/docs/build/human-in-the-loop"
    icon="eye"
    description="Pause a workflow until a person approves or supplies input."
  />
  <LinkCard
    title="Webhooks"
    href="/docs/build/webhooks"
    icon="bolt"
    description="Receive external events and route them into AGNT5 workflows."
  />
  <LinkCard
    title="Model Context Protocol"
    href="/docs/build/mcp"
    icon="plug"
    description="Import external MCP tools or expose AGNT5 primitives to MCP clients."
  />
  <LinkCard
    title="Local development"
    href="/docs/build/local-development"
    icon="terminal"
    description="Run your project with agnt5 dev and trigger it from Studio, the CLI, or the API."
  />
</LinkCardGroup>

Outcome: you have local code that defines the workflow behavior, model calls, external inputs, and approval points AGNT5 will run.

## Next steps



After you understand the Build section, start with the path that matches your current project.

- [Run locally](/docs/build/local-development): Start the worker with `agnt5 dev` and trigger runs from Studio.
- [Define a workflow](/docs/build/workflows): Compose durable steps and checkpointed execution.
- [Deploy the code](/docs/run/deploying): Move the worker into an AGNT5 environment.

---

## Prompt caching

_Source: https://agnt5.com/docs/build/prompt-caching.md_

> Enable provider-native prompt caching from one SDK surface across Anthropic, OpenAI, and Gemini.

**Prompt caching** lets a model provider reuse the stable leading portion of a request, such as instructions, tool definitions, documents, and earlier conversation turns. AGNT5 exposes one `cache` option and translates it to the provider-specific request shape under the hood. Use it when repeated calls share a long prefix and you want lower latency, lower input-token spend, and cache-hit metrics in one place.

AGNT5 reports cache hits through `response.usage.cached_tokens` across Anthropic, OpenAI, and Gemini. Providers that expose cache writes also populate `response.usage.cache_creation_tokens`.

## Enable caching

Pass `cache=True` when you want AGNT5 to turn on provider-native prompt caching wherever the provider needs an explicit signal. Pass a `PromptCache` policy when you need TTL, key, retention, or a reusable Gemini cache resource.

### Python

```python
from agnt5 import Agent, lm

agent = Agent(
    name="support_agent",
    model="anthropic/claude-sonnet-4-6",
    instructions=LONG_STABLE_INSTRUCTIONS,
    tools=[lookup_order, create_refund],
    cache=lm.PromptCache(ttl="1h"),
)

result = await agent.run("Customer order 1042 arrived damaged.")
```

Use the same `cache` option for direct model calls:

```python
from agnt5 import lm

response = await lm.generate(
    model="openai/gpt-4o-mini",
    system_prompt=LONG_STABLE_INSTRUCTIONS,
    prompt="Summarize the customer escalation.",
    cache=lm.PromptCache(
        key="support-agent",
        retention="24h",
    ),
)

print(response.usage.cached_tokens)
```

### TypeScript

```ts
const model = LM.anthropic();

const agent = new Agent({
  name: "support_agent",
  model,
  modelName: "anthropic/claude-sonnet-4-6",
  instructions: LONG_STABLE_INSTRUCTIONS,
  tools: [lookupOrder, createRefund],
  cache: { ttl: "1h" },
});

const result = await agent.run("Customer order 1042 arrived damaged.");
```

Direct model calls use `config.cache`:

```ts
const openai = LM.openai();

const response = await openai.generate({
  model: "openai/gpt-4o-mini",
  systemPrompt: LONG_STABLE_INSTRUCTIONS,
  messages: [{ role: "user", content: "Summarize the customer escalation." }],
  config: {
    cache: {
      key: "support-agent",
      retention: "24h",
    },
  },
});

console.log(response.usage?.cachedTokens);
```

### Go

```go
model := agnt5.NewAnthropicModel(agnt5.AnthropicConfig{
    APIKey: os.Getenv("ANTHROPIC_API_KEY"),
    Model:  "claude-sonnet-4-6",
})

agent, err := agnt5.NewAgent(
    "support_agent",
    agnt5.WithAgentModel(model),
    agnt5.WithAgentInstructions(LONG_STABLE_INSTRUCTIONS),
    agnt5.WithAgentTools(lookupOrder, createRefund),
    agnt5.WithAgentPromptCache(agnt5.PromptCacheWithTTL("1h")),
)
if err != nil {
    return err
}

result, err := agent.Run(ctx, agnt5.AgentInput{
    Message: "Customer order 1042 arrived damaged.",
})
```

Direct model calls use `GenerateRequest.Cache`:

```go
response, err := model.Generate(ctx, agnt5.GenerateRequest{
    Messages: []agnt5.Message{
        {Role: agnt5.MessageRoleSystem, Content: LONG_STABLE_INSTRUCTIONS},
        {Role: agnt5.MessageRoleUser, Content: "Summarize the customer escalation."},
    },
    Cache: agnt5.PromptCacheWithTTL("1h"),
})
if err != nil {
    return err
}

fmt.Println(response.Usage.CachedTokens)
```

## Provider behavior

Use the same `cache` option in application code. AGNT5 adapts the request per provider.

| Provider | AGNT5 input | Provider translation | Metrics |
|---|---|---|---|
| Anthropic | `cache=True` or `ttl` | Sends ephemeral `cache_control`; includes TTL when set | `cached_tokens`, `cache_creation_tokens` |
| OpenAI | Stable prefix; optional `key` and `retention` | Uses automatic prompt caching; Responses-backed SDKs map hints to `prompt_cache_key` and `prompt_cache_retention` | `cached_tokens` |
| Gemini implicit | `cache=True` | No request field; Gemini detects repeated prefixes | `cached_tokens` |
| Gemini explicit | `ContextCache` or `resource` | Sends `cachedContent` | `cached_tokens` |

AGNT5 ignores hints a provider does not support. That keeps provider switches from leaking into agent code: a TTL matters for Anthropic, key and retention matter for OpenAI Responses, and resource names matter for Gemini explicit caches.

## Reuse a Gemini context cache

Gemini supports explicit context caches for large, stable content. Create the cache once, pass the returned object through `cache`, and delete it when the workload is finished.

### Python

```python
from agnt5 import lm

cache = await lm.create_cache(
    model="google/gemini-2.5-flash",
    system_prompt="You are a contract analyst.",
    contents=contract_text,
    ttl_seconds=3600,
)

response = await lm.generate(
    model="google/gemini-2.5-flash",
    prompt="List the termination clauses.",
    cache=cache,
)

await cache.delete()
```

### TypeScript

```ts
const gemini = LM.google();

const cache = await gemini.createCache({
  model: "google/gemini-2.5-flash",
  systemPrompt: "You are a contract analyst.",
  contents: contractText,
  ttlSeconds: 3600,
});

const response = await gemini.generate({
  model: "google/gemini-2.5-flash",
  messages: [{ role: "user", content: "List the termination clauses." }],
  config: { cache },
});

await gemini.deleteCache(cache);
```

### Go

```go
gemini := agnt5.NewGoogleModel(agnt5.GoogleConfig{
    APIKey: os.Getenv("GOOGLE_API_KEY"),
    Model:  "google/gemini-2.5-flash",
})

cacheName, err := gemini.CreateCachedContent(
    ctx,
    "google/gemini-2.5-flash",
    "You are a contract analyst.",
    []string{contractText},
    3600,
)
if err != nil {
    return err
}
defer gemini.DeleteCachedContent(ctx, cacheName)

response, err := gemini.Generate(ctx, agnt5.GenerateRequest{
    Messages: []agnt5.Message{
        {Role: agnt5.MessageRoleUser, Content: "List the termination clauses."},
    },
    Cache: agnt5.PromptCacheResource(cacheName),
})
```

## Read cache metrics

Cache metrics are normalized onto the same usage fields in each SDK.

| Field | Meaning |
|---|---|
| `cached_tokens` / `cachedTokens` / `CachedTokens` | Input tokens served from a provider prompt cache. |
| `cache_creation_tokens` / `cacheCreationTokens` / `CacheCreationTokens` | Input tokens written into a cache. Anthropic reports this today. |
| `prompt_tokens` / `promptTokens` / `InputTokens` | All input tokens, including uncached tokens and cached-token reads. |

```python
response = await lm.generate(
    model="anthropic/claude-sonnet-4-6",
    system_prompt=LONG_STABLE_INSTRUCTIONS,
    prompt="Answer the next support question.",
    cache=True,
)

usage = response.usage
print(f"Cache hits: {usage.cached_tokens}")
print(f"Cache writes: {usage.cache_creation_tokens}")
```

The first matching call usually records a cache write or a cache miss. Later calls with the same stable prefix should report cache hits.

## Design for hits

Prompt caching only works when the provider sees the same leading tokens.

* **Keep instructions stable**: Put request-specific facts in the user message, not in `Agent(instructions=...)` or `system_prompt`.
* **Keep tool schemas stable**: Adding, removing, or reordering tools changes the cacheable prefix.
* **Keep serialization deterministic**: Sort JSON keys before embedding generated JSON in instructions.
* **Keep model IDs stable**: Changing the model string creates a different provider cache boundary.

<Callout type="warning">
Avoid timestamps, UUIDs, random seeds, and per-user template branches in the stable prefix. Put those values after the cached prefix so the reusable portion remains byte-identical.
</Callout>

## Next steps

* [Agents](/docs/build/agents.md): configure the agent loop that carries stable instructions and tools.
* [Prompts](/docs/build/prompts.md): version prompt text so cacheable prefixes stay reproducible across deployments.
* [AI providers](/docs/integrations/ai-providers.md): configure provider credentials and model routing.

---

## Prompts

_Source: https://agnt5.com/docs/build/prompts.md_

> Manage prompt text as a first-class artifact, run it from Python or TypeScript, and keep production prompt versions tied to code.

A **Prompt** is a managed LLM prompt that can be drafted and tested in AGNT5, then committed with your application code for production. Use Prompts when the prompt itself is an artifact you want to version, evaluate, and deploy, instead of burying instructions inside function bodies.

In development, a Prompt can resolve through AGNT5's prompt store so you can test drafts quickly. In production, AGNT5 resolves Prompts from files bundled with the deployed code artifact. That keeps production behavior reproducible: the code version and prompt version move together.

---

## Run a Prompt

Python:

```python
from agnt5 import lm
from agnt5.lm import Prompt

response = await lm.generate(
    model="openai/gpt-4o-mini",
    prompt=Prompt(
        id="support_reply",
        variables={
            "customer": {"name": "Ada"},
            "topic": "shipping",
        },
    ),
)

print(response.text)
```

TypeScript:

```ts
const lm = LM.openai();

const response = await lm.generate({
  model: "openai/gpt-4o-mini",
  prompt: {
    id: "support_reply",
    variables: {
      customer: { name: "Ada" },
      topic: "shipping",
    },
  },
});

console.log(response.text);
```

<Callout type="info">`prompt` replaces inline `messages` for the call. If you provide a Prompt, do not also pass raw prompt text or message arrays for the same generation request.</Callout>

---

## Commit a production Prompt

Create a prompt file under `prompts/<id>.mdx` in your application repo:

```mdx
---
id: support_reply
version: 3
version_id: 018f0000-0000-7000-8000-000000000003
model: openai/gpt-4o-mini
temperature: 0.2
max_tokens: 600
variables:
  - customer.name
  - topic
response_format: text
---

<System>
You are a concise support agent.
</System>

<User>
Reply to {{customer.name}} about {{topic}}.
</User>
```

AGNT5 parses the front matter for routing and generation settings, then renders the body into ordered chat messages. The body supports `<System>`, `<User>`, and `<Assistant>` blocks. If no block is present, the body is treated as a single user message.

Production Prompt resolution looks in this order:

1. `AGNT5_PROMPT_OVERRIDE`
2. `AGNT5_PROMPTS_MANIFEST`
3. `prompts/<id>.mdx`
4. `prompts/<id>.md`
5. AGNT5 prompt-run API fallback for non-production draft and test workflows

Prompt files must be Markdown or MDX. AGNT5 does not load prompt text from `prompts.lock` or JSON files; prompts are meant to be readable authored artifacts.

<Callout type="warning">In production environments, the Prompt must be bundled with the deployed artifact. Missing Prompts fail closed and do not fall back to control-plane state.</Callout>

---

## Select a version

Use `version` when constructing the Prompt object, or pass the SDK's version option for the call.

Python:

```python
response = await lm.generate(
    model="openai/gpt-4o-mini",
    prompt=Prompt(id="support_reply", version="version-3"),
)
```

TypeScript:

```ts
const response = await lm.generate({
  model: "openai/gpt-4o-mini",
  prompt: { id: "support_reply", version: "version-3" },
});
```

The version can match either the prompt file's `version` or `version_id`.

---

## Override runtime settings

Use runtime LLM overrides when you want to test the same prompt with a different model or generation settings. This is useful in the Playground, experiments, and one-off comparisons because workflow code can stay unchanged.

Python:

```python
ctx.runtime.llm.model = "openai/gpt-4o"
ctx.runtime.llm.temperature = 0.6
ctx.runtime.llm.max_tokens = 800
ctx.runtime.llm.top_p = 0.9

response = await lm.generate(
    model="openai/gpt-4o-mini",
    prompt=Prompt(
        id="support_reply",
        variables={"topic": "shipping"},
    ),
)
```

TypeScript:

```ts
ctx.runtime.llm.model = "openai/gpt-4o";
ctx.runtime.llm.temperature = 0.6;
ctx.runtime.llm.maxOutputTokens = 800;
ctx.runtime.llm.topP = 0.9;

const response = await lm.generate({
  model: "openai/gpt-4o-mini",
  prompt: {
    id: "support_reply",
    variables: { topic: "shipping" },
  },
});
```

For workflows with multiple prompts, set prompt-specific overrides by prompt id:

```python
ctx.runtime.prompts["draft"] = LLMRuntimeOptions(
    model="anthropic/claude-3-5-haiku-20241022",
    temperature=0.7,
)
ctx.runtime.prompts["review"] = LLMRuntimeOptions(
    model="openai/gpt-4o",
    temperature=0.3,
)

await lm.generate(model="openai/gpt-4o-mini", prompt=Prompt(id="classify"))
await lm.generate(model="openai/gpt-4o-mini", prompt=Prompt(id="draft"))
await lm.generate(model="openai/gpt-4o-mini", prompt=Prompt(id="review"))
```

The Prompt file remains the source of truth for prompt text. Runtime overrides only change model execution settings for the current run. Prompt-specific overrides win over the global runtime default.

---

## Use Prompts inside workflows

Prompts work anywhere you can call the language model SDK. Inside workflows, keep the LLM call inside a checkpointed step so replay can reuse the completed result.

```python
from agnt5 import function, FunctionContext, lm
from agnt5.lm import Prompt

@function
async def draft_reply(ctx: FunctionContext, customer_name: str, topic: str) -> str:
    response = await lm.generate(
        model="openai/gpt-4o-mini",
        prompt=Prompt(
            id="support_reply",
            variables={
                "customer": {"name": customer_name},
                "topic": topic,
            },
        ),
    )
    return response.text
```

When this function is called through `ctx.step()` from a workflow, the generated reply is checkpointed with the rest of the step result.

---

## Compatibility

Older SDK code may still use `PromptRef`, `prompt_ref`, or `promptRef`. Those names remain supported for compatibility, but new docs and new code should use **Prompt** as the concept:

```python
# Supported, but prefer prompt=Prompt(...)
await lm.generate(
    model="openai/gpt-4o-mini",
    prompt_ref="support_reply",
    variables={"topic": "shipping"},
)
```

```ts
// Supported, but prefer prompt: { id: "support_reply" }
await lm.generate({
  model: "openai/gpt-4o-mini",
  promptRef: "support_reply",
  variables: { topic: "shipping" },
});
```

Use `PromptRef` only when maintaining older code that already uses that terminology.

---

## Use sandboxes with agents

_Source: https://agnt5.com/docs/build/sandboxes.md_

> Give an agent an isolated workspace where it can write files, read files, list files, and execute code.

A **sandbox** is an isolated workspace attached to an **[agent](/docs/build/agents.md)**. The agent can write files, read files, list directories, and execute code without running generated code in your worker process. Use sandboxes when an agent needs to inspect code, create scripts, run tests, or verify calculations before it answers.

## Attach a sandbox

Pass `Sandbox()` to the agent constructor. AGNT5 creates the provider sandbox on first use, keeps the workspace available for the duration of the run, and closes it when the run ends.



**Python:**

```python
from agnt5 import Agent, Sandbox

agent = Agent(
    name="coder",
    model="openai/gpt-4o-mini",
    instructions=(
        "Use the sandbox workspace to write files, inspect files, "
        "and run code before you return an answer."
    ),
    sandbox=Sandbox(),
)

result = await agent.run(
    "Create answer.py, make it print 6 * 7 as JSON, run it, and show the output."
)

print(result.output)
```





**TypeScript:**

```ts
const agent = new Agent({
  name: 'coder',
  model: LM.openai(),
  modelName: 'openai/gpt-4o-mini',
  instructions:
    'Use the sandbox workspace to write files, inspect files, and run code before you return an answer.',
  sandbox: new Sandbox(),
});

const result = await agent.run(
  'Create answer.py, make it print 6 * 7 as JSON, run it, and show the output.'
);

console.log(result.output);
```



The agent can write files, read files, list files, and execute code automatically. You still pass custom tools through `tools=[...]` or `tools: [...]` when the agent needs other capabilities.

## Choose a provider

`Sandbox()` auto-detects the first configured provider from environment variables. Pass a provider name to use a specific one.



**Python:**

```python
from agnt5 import Agent, Sandbox

agent = Agent(
    name="daytona_coder",
    model="openai/gpt-4o-mini",
    instructions="Use the Daytona sandbox for code and file work.",
    sandbox=Sandbox(provider="daytona"),
)
```





**TypeScript:**

```ts
const agent = new Agent({
  name: 'daytona-coder',
  model: LM.openai(),
  modelName: 'openai/gpt-4o-mini',
  instructions: 'Use the Daytona sandbox for code and file work.',
  sandbox: new Sandbox({ provider: 'daytona' }),
});
```



Common provider names are `e2b`, `daytona`, `vercel`, `northflank`, and `together`. Configure the provider credentials before running the agent. See [Sandbox providers](/docs/integrations/sandbox-providers.md) for the required environment variables.

> **Together limitation:** The Together provider only supports Python code execution. Shell commands (`run_command`) are not available, and sessions expire automatically after 60 minutes and cannot be destroyed early. `auto_destroy` / `autoDestroy` is ignored.

## Configure the sandbox

Beyond `provider`, the `Sandbox` constructor accepts options to control the environment, resources, and lifetime.



**Python:**

```python
sandbox = Sandbox(
    provider="e2b",
    template="my-custom-image",        # specific sandbox image or snapshot
    env={"OPENAI_API_KEY": "sk-..."},  # environment variables inside the sandbox
    timeout_secs=600,                  # sandbox lifetime in seconds (default: 300)
    cpu_cores=2,                       # CPU cores to allocate
    memory_mib=2048,                   # memory in MiB to allocate
)
```





**TypeScript:**

```ts
const sandbox = new Sandbox({
  provider: 'e2b',
  template: 'my-custom-image',          // specific sandbox image or snapshot
  env: { OPENAI_API_KEY: 'sk-...' },   // environment variables inside the sandbox
  timeoutSecs: 600,                     // sandbox lifetime in seconds
  cpuCores: 2,                          // CPU cores to allocate
  memoryMib: 2048,                      // memory in MiB to allocate
});
```



Not all providers support every option. `template`, `cpu_cores`/`cpuCores`, and `memory_mib`/`memoryMib` are passed through to the provider and have no effect when the provider does not support them.

## Use the sandbox from custom tools

Custom tools can use the same sandbox through `ctx.sandbox`. This lets you add project-specific behavior while sharing the agent's workspace.



**Python:**

```python
from agnt5 import Agent, Sandbox, tool
from agnt5.context import Context

@tool
async def count_lines(ctx: Context, path: str) -> dict:
    """Count lines in a sandbox file.

    Args:
        path: Path to the file inside the sandbox workspace.
    """
    content = await ctx.sandbox.read_file(path)
    text = content.content.decode("utf-8")
    return {"path": path, "lines": len(text.splitlines())}

agent = Agent(
    name="code_reviewer",
    model="openai/gpt-4o-mini",
    instructions="Use the sandbox and count_lines tool to inspect generated files.",
    sandbox=Sandbox(provider="e2b"),
    tools=[count_lines],
)
```





**TypeScript:**

```ts
const countLines = tool(
  'count_lines',
  {
    description: 'Count lines in a sandbox file.',
    inputSchema: {
      type: 'object',
      properties: {
        path: { type: 'string', description: 'Path to the file inside the sandbox workspace.' },
      },
      required: ['path'],
    },
  },
  async (ctx, args) => {
    if (!ctx.sandbox) throw new Error('No sandbox is attached to this agent.');

    const file = await ctx.sandbox.readFile(args.path);
    return {
      path: args.path,
      lines: file.content.toString('utf-8').split('\n').length,
    };
  }
);

const agent = new Agent({
  name: 'code-reviewer',
  model: LM.openai(),
  modelName: 'openai/gpt-4o-mini',
  instructions: 'Use the sandbox and count_lines tool to inspect generated files.',
  sandbox: new Sandbox({ provider: 'e2b' }),
  tools: [countLines],
});
```



## Run shell commands

The Python SDK exposes `run_command()` on the sandbox for running arbitrary shell commands, not just code. Use it from a custom tool when you need to install packages, run build steps, or execute scripts.



**Python:**

```python
from agnt5 import Agent, Sandbox, tool
from agnt5.context import Context

@tool
async def install_and_run(ctx: Context, package: str, script: str) -> dict:
    """Install a package and run a script inside the sandbox."""
    install = await ctx.sandbox.run_command("pip", args=["install", package])
    run = await ctx.sandbox.run_command("python", args=[script])
    return {"install": install.stdout, "output": run.stdout, "error": run.stderr}

agent = Agent(
    name="builder",
    model="openai/gpt-4o-mini",
    instructions="Use install_and_run to set up dependencies and execute scripts.",
    sandbox=Sandbox(provider="e2b"),
    tools=[install_and_run],
)
```



`run_command` accepts `args`, `working_dir`, `env`, and `timeout_ms`. It returns `stdout`, `stderr`, and `exit_code`. A streaming variant `run_command_stream` is also available for long-running commands.

> **Note:** `run_command` is Python-only. TypeScript supports `executeCode` for running code but does not have a built-in shell command method. See [Sandbox providers](/docs/integrations/sandbox-providers.md) for provider-specific capabilities.

## Control lifecycle

By default, AGNT5 owns the sandbox lifecycle for the agent run:

- **Create**: the provider sandbox is created on first use.
- **Share**: file and execution state stays available across sandbox calls in the run.
- **Close**: the provider sandbox is destroyed when the agent run finishes.

Set `auto_destroy=False` in Python or `autoDestroy: false` in TypeScript when you need to keep the provider sandbox alive after the run for debugging.



**Python:**

```python
sandbox = Sandbox(provider="e2b", auto_destroy=False)
```





**TypeScript:**

```ts
const sandbox = new Sandbox({ provider: 'e2b', autoDestroy: false });
```



> **Warning:** Leaving provider sandboxes running incurs ongoing provider cost and leaves your files accessible in the provider environment until the session expires. Use `auto_destroy=False` only for short debugging sessions.

## Validate your provider setup

Use the `sandbox-smoke` template when you want to confirm that your credentials and provider are working correctly before building.

```bash
agnt5 create --template python/sandbox-smoke sandbox-smoke
cd sandbox-smoke
cp .env.example .env
agnt5 --env-file .env dev
```

Run the lifecycle check after the worker is connected:

```bash
agnt5 --env-file .env run sandbox_lifecycle_check \
  --input '{"provider": "e2b", "code": "print(6 * 7)", "language": "python"}'
```

The smoke template also includes checks for file write, file read, file list, direct code execution, and an agent that uses the sandbox through its built-in tools.

## Next steps

- [Sandbox providers](/docs/integrations/sandbox-providers.md): configure E2B, Daytona, Vercel, Northflank, or Together credentials.
- [Agents](/docs/build/agents.md): configure agent loops, tools, handoffs, and iteration limits.
- [Tools](/docs/build/tools.md): add custom tools that share the agent's sandbox workspace.
- [Local development](/docs/build/local-development.md): run a worker locally with `agnt5 dev`.

---

## Give agents skills and project guidance

_Source: https://agnt5.com/docs/build/skills.md_

> Load capabilities on demand with SKILL.md folders, and apply always-on project guidance with AGENTS.md, instead of stuffing everything into one large prompt.

**Skills** give an agent a library of capabilities without bloating its prompt. Each skill is a folder with a `SKILL.md` file. Only the skill's name and description stay in the agent's context; when a task matches, the agent loads the full instructions on demand.

Skills work alongside **`AGENTS.md`**, which provides always-on project guidance. Use `AGENTS.md` for conventions that apply to every task, such as coding style or project structure, and use skills for capabilities the agent reaches for only when relevant.

## Write a skill

A skill is a folder with a `SKILL.md` file. The `name` and `description` fields at the top of the file are the only parts that stay in context; the body loads when the agent decides the skill is relevant.

```text
skills/
  pdf-extraction/
    SKILL.md
    scripts/
      extract.py
```

```markdown
---
name: pdf-extraction
description: Extract tables and text from PDF files
---

# PDF extraction

To extract content from a PDF:

1. Write the PDF bytes to `input.pdf` in the sandbox.
2. Run `scripts/extract.py input.pdf` to produce `output.json`.
3. Read `output.json` and summarize the tables it contains.
```

Because `SKILL.md` is plain markdown, skills written for other agent frameworks work in AGNT5 unchanged. The `skills/` folder ships alongside your worker code in the same deployment bundle.

## Give an agent skills

Pass a curated list of skill names and the directory pool they resolve against. Each agent sees only the skills you select, so its catalog and context cost stay small.



**Python:**

```python
from agnt5 import Agent, Sandbox

researcher = Agent(
    name="researcher",
    model="openai/gpt-4o-mini",
    instructions="Help the user analyze documents.",
    skills_dir="./skills",
    skills=["pdf-extraction", "sql-reporting"],
    sandbox=Sandbox(),
)

reporter = Agent(
    name="reporter",
    model="openai/gpt-4o-mini",
    instructions="Build reports from warehouse data.",
    skills_dir="./skills",
    skills=["sql-reporting"],
)
```





**TypeScript:**

```ts
const researcher = new Agent({
  name: 'researcher',
  model: LM.openai(),
  modelName: 'openai/gpt-4o-mini',
  instructions: 'Help the user analyze documents.',
  skillsDir: './skills',
  skills: ['pdf-extraction', 'sql-reporting'],
  sandbox: new Sandbox(),
});

const reporter = new Agent({
  name: 'reporter',
  model: LM.openai(),
  modelName: 'openai/gpt-4o-mini',
  instructions: 'Build reports from warehouse data.',
  skillsDir: './skills',
  skills: ['sql-reporting'],
});
```



Two agents can draw different subsets from the same `skills/` pool. A name that isn't in the pool fails at construction with the list of available skills, so typos surface immediately.

## Run a skill's bundled scripts

If a **[sandbox](/docs/build/sandboxes.md)** is attached, loading a skill also copies its bundled files into the sandbox workspace under `skills/<name>/`. The agent can then run those files using sandbox tools without any extra setup. Without a sandbox, `load_skill` still returns the skill's instructions; running the bundled scripts requires one.

## How loading works

When an agent has skills, the SDK adds a `<skills>` catalog of names and descriptions to the system prompt and registers a built-in `load_skill` tool. When a task matches, the agent calls `load_skill("pdf-extraction")` and receives the full instructions for that skill. Only loaded skills consume context; everything else stays out of the prompt.

Each load emits a `skill.loaded` event carrying the skill name, instruction length, and how many bundled files were copied into the sandbox, so a run's timeline shows exactly which skills were pulled in and when. To observe skill loads in your own code, iterate the agent's event stream.



**Python:**

```python
from agnt5 import SkillLoaded

async for event in agent.stream("Analyze this PDF"):
    if isinstance(event, SkillLoaded):
        print(f"Loaded: {event.skill_name} ({event.instructions_length} chars)")
```





**TypeScript:**

```ts
for await (const event of agent.stream('Analyze this PDF')) {
  if (event.eventType === 'skill.loaded') {
    console.log(`Loaded: ${event.skillName} (${event.instructionsLength} chars)`);
  }
}
```



## Load every skill in a pool

Omit `skills` to load every skill in the directory. This is convenient for a single agent that should have the whole pool.



**Python:**

```python
agent = Agent(
    name="generalist",
    model="openai/gpt-4o-mini",
    instructions="Use whichever skill fits the task.",
    skills_dir="./skills",
)
```





**TypeScript:**

```ts
const agent = new Agent({
  name: 'generalist',
  model: LM.openai(),
  modelName: 'openai/gpt-4o-mini',
  instructions: 'Use whichever skill fits the task.',
  skillsDir: './skills',
});
```



You can also load individual skills by path when you don't want a shared pool.



**Python:**

```python
from agnt5 import Agent, Skill

agent = Agent(
    name="analyst",
    model="openai/gpt-4o-mini",
    instructions="Analyze documents.",
    skills=[Skill.from_path("./my-skills/pdf-extraction")],
)
```





**TypeScript:**

```ts
const agent = new Agent({
  name: 'analyst',
  model: LM.openai(),
  modelName: 'openai/gpt-4o-mini',
  instructions: 'Analyze documents.',
  skills: [Skill.fromPath('./my-skills/pdf-extraction')],
});
```



### Inspect the pool directly

Use `discover_skills` / `discoverSkills` to inspect the pool without constructing an agent, for example to list available skills at startup or validate the directory.



**Python:**

```python
from agnt5 import discover_skills

pool = discover_skills("./skills")
for name, skill in pool.items():
    print(f"{name}: {skill.description}")
```





**TypeScript:**

```ts
const pool = discoverSkills('./skills');
for (const [name, skill] of pool) {
  console.log(`${name}: ${skill.description}`);
}
```



## Apply always-on project guidance with AGENTS.md

`AGENTS.md` is always-on guidance loaded into every prompt, so use it for conventions that always apply. Point the agent at a file, a directory (which uses its `AGENTS.md`), or a list of paths where later entries are more specific than earlier ones.



**Python:**

```python
agent = Agent(
    name="researcher",
    model="openai/gpt-4o-mini",
    instructions="Help the user analyze documents.",
    agents_md="./AGENTS.md",
    skills_dir="./skills",
    skills=["pdf-extraction"],
)
```





**TypeScript:**

```ts
const agent = new Agent({
  name: 'researcher',
  model: LM.openai(),
  modelName: 'openai/gpt-4o-mini',
  instructions: 'Help the user analyze documents.',
  agentsMd: './AGENTS.md',
  skillsDir: './skills',
  skills: ['pdf-extraction'],
});
```



To pass multiple files, use a list. The agent reads them in order, so put the most general file first and the most specific last.



**Python:**

```python
agent = Agent(
    name="researcher",
    model="openai/gpt-4o-mini",
    instructions="Help the user analyze documents.",
    agents_md=["./AGENTS.md", "./research/AGENTS.md"],
)
```





**TypeScript:**

```ts
const agent = new Agent({
  name: 'researcher',
  model: LM.openai(),
  modelName: 'openai/gpt-4o-mini',
  instructions: 'Help the user analyze documents.',
  agentsMd: ['./AGENTS.md', './research/AGENTS.md'],
});
```



Guidance loads before the skills catalog, so the agent reads its standing rules before the list of on-demand capabilities. To automatically merge a root `AGENTS.md` with any directory-specific ones, use `discover_agents_md` / `discoverAgentsMd` and pass the result.



**Python:**

```python
from agnt5 import Agent, discover_agents_md

agent = Agent(
    name="researcher",
    model="openai/gpt-4o-mini",
    instructions="Help the user analyze documents.",
    agents_md=discover_agents_md("."),  # root AGENTS.md first, most specific last
)
```





**TypeScript:**

```ts
const agent = new Agent({
  name: 'researcher',
  model: LM.openai(),
  modelName: 'openai/gpt-4o-mini',
  instructions: 'Help the user analyze documents.',
  agentsMd: discoverAgentsMd('.'), // root AGENTS.md first, most specific last
});
```



`discover_agents_md` / `discoverAgentsMd` walks upward from the start directory and stops at the repository root (the directory containing `.git`), so it never reads files outside your project.

## When to use which

| Use | For | Loaded |
|-----|-----|--------|
| `AGENTS.md` | Standing rules that apply to every task | Always, in every prompt |
| Skills | Capabilities the agent reaches for occasionally | On demand, when a task matches |

Both are optional. An agent with neither behaves exactly as before. Guidance and skills only change the prompt when you configure them.

---

## Tools

_Source: https://agnt5.com/docs/build/tools.md_

> Give agents typed callable actions for APIs, code execution, search, and provider-hosted capabilities.

Tools give your agent the ability to take actions: call an API, run code, or search the web. The agent decides when to call a tool based on the conversation, runs it, then loops back with the result until it has a final answer.

---

## Custom tools

Define a tool with the `@tool` decorator. The SDK reads your type hints and docstring to build the JSON schema the model uses to call it correctly.

```python
from agnt5 import Agent
from agnt5.context import Context
from agnt5.tool import tool

@tool
async def get_weather(ctx: Context, city: str) -> str:
    """Get the current weather for a city.

    Args:
        city: Name of the city to check.
    """
    # call your weather API here
    return f"Sunny, 22°C in {city}"

agent = Agent(
    name="assistant",
    model="openai/gpt-4o-mini",
    instructions="You help users with weather queries.",
    tools=[get_weather],
)

result = await agent.run("What is the weather in Paris?")
print(result.output)
```

**Things to know**

- The first parameter must be `ctx: Context` (injected automatically, not exposed to the model).
- Every other parameter becomes a field the model can fill in. Type hints (`str`, `int`, `bool`, `list`) and docstring `Args:` descriptions are used to build the schema.
- Sync functions are wrapped in a thread pool automatically.
- The tool is registered globally at import time and can be reused across agents.

`@tool` decorator options:

| Parameter | Type | Default | Description |
|---|---|---|---|
| `name` | `str` | function's `__name__` | How the tool appears to the model |
| `description` | `str` | first line of docstring | What the model reads to decide when to call this tool |
| `confirmation` | `bool` | `False` | Reserved for future human-approval flow |

---

## Inspecting tool calls

After `agent.run()`, `result.tool_calls` lists every tool the agent invoked during its loop.

```python
result = await agent.run("What is the weather in Paris?")

print(result.output)      # final answer
print(result.tool_calls)  # [{"name": "get_weather", "arguments": '{"city": "Paris"}', "iteration": 1}]
```

---

## Agents as tools

Pass another `Agent` directly in the `tools` list. The SDK wraps it automatically. The calling agent invokes it like any other tool and gets the specialist's response back before continuing its own reasoning.

```python
from agnt5 import Agent

lookup_agent = Agent(
    name="lookup",
    model="openai/gpt-4o-mini",
    instructions="You look up factual information and return concise answers.",
)

orchestrator = Agent(
    name="orchestrator",
    model="openai/gpt-4o-mini",
    instructions="Use lookup to find information, then summarize it for the user.",
    tools=[lookup_agent],   # auto-wrapped as ask_lookup
)

result = await orchestrator.run("What is the capital of Japan?")
print(result.output)
```

---

## Sandbox workspaces

Pass a **[sandbox](/docs/build/sandboxes.md)** to an agent when it needs an isolated file and code execution workspace. AGNT5 adds the standard sandbox capabilities to the agent, and your custom tools can use the same workspace through `ctx.sandbox`.

```python
from agnt5 import Agent, Sandbox

agent = Agent(
    name="coder",
    model="openai/gpt-4o-mini",
    instructions=(
        "Use the sandbox workspace to write files, inspect files, "
        "and run code before returning an answer."
    ),
    sandbox=Sandbox(),
)

result = await agent.run("Calculate the first 10 fibonacci numbers in Python")
print(result.output)
```

The agent can use the sandbox to:

- write files to the workspace
- read files from the workspace
- list files and directories
- execute `python`, `javascript`, or `bash` code

See [Use sandboxes with agents](/docs/build/sandboxes.md) for provider selection, lifecycle, and custom tools that read from `ctx.sandbox`.

---

## Built-in tools

Built-in tools run entirely on the provider's infrastructure. You enable them and the provider handles execution. Results are already included in the model's response; no local code runs.

```python
from agnt5 import Agent
from agnt5.lm import BuiltInTool

agent = Agent(
    name="researcher",
    model="openai/gpt-4o-mini",
    instructions=(
        "You are a research assistant. Always use web_search to find current "
        "information, never answer from training knowledge alone."
    ),
    built_in_tools=[BuiltInTool.WEB_SEARCH],
)

result = await agent.run("Who won the most recent Formula 1 championship?")
print(result.output)
```

Available built-in tools:

| Tool | What it does | Provider |
|---|---|---|
| `BuiltInTool.WEB_SEARCH` | Live web search with cited results | OpenAI, Anthropic |
| `BuiltInTool.CODE_INTERPRETER` | Run code in a provider-hosted sandbox | OpenAI only |
| `BuiltInTool.FILE_SEARCH` | Search over files uploaded to the provider | OpenAI only |
| `BuiltInTool.WEB_FETCH` | Fetch the content of a specific URL | Anthropic only |

You can mix built-in tools with sandbox workspaces and custom tools on the same agent:

```python
from agnt5 import Agent, Sandbox
from agnt5.lm import BuiltInTool

agent = Agent(
    name="assistant",
    model="openai/gpt-4o-mini",
    instructions="Search the web for information and run code when needed.",
    built_in_tools=[BuiltInTool.WEB_SEARCH],
    sandbox=Sandbox(),
)
```

---

## MCP tools

Use [Model Context Protocol](/docs/build/mcp.md) when a tool already exists in an external MCP server. `MCPClient` connects to the server, discovers tools, and returns AGNT5 `Tool` objects that you pass to an agent.

```python
from agnt5 import Agent
from agnt5.mcp import MCPClient

mcp = MCPClient(id="repo-tools")
mcp.add_streamable_http_server("deepwiki", "https://mcp.deepwiki.com/mcp")
await mcp.connect()

agent = Agent(
    name="repository_researcher",
    model="openai/gpt-4o-mini",
    instructions="Use available tools to answer questions about code repositories.",
    tools=mcp.get_tools(),
)
```

See [Model Context Protocol](/docs/build/mcp.md) for transports, direct tool calls, and exposing AGNT5 primitives as an MCP server.

---

## Human-in-the-loop tools

Two built-in tool classes let an agent pause and wait for a human response before continuing. Both require a workflow context because execution must durably suspend while waiting.

```python
from agnt5 import Agent, workflow, WorkflowContext
from agnt5.tool import AskUserTool, RequestApprovalTool

@workflow
async def agent_with_hitl(ctx: WorkflowContext, task: str) -> dict:
    agent = Agent(
        name="assistant",
        model="openai/gpt-4o-mini",
        instructions=(
            "Ask the user for clarification when the request is ambiguous. "
            "Always request approval before making any changes."
        ),
        tools=[AskUserTool(ctx), RequestApprovalTool(ctx)],
    )
    result = await agent.run(task, context=ctx)
    return {"response": result.output}
```

| Tool | Behaviour |
|---|---|
| `AskUserTool(ctx)` | Agent calls `ask_user` with a question. Workflow pauses until the user types a response |
| `RequestApprovalTool(ctx)` | Agent calls `request_approval` with an action description. Workflow pauses and shows Approve / Reject to the user |

---

## Webhooks

_Source: https://agnt5.com/docs/build/webhooks.md_

> Trigger workflows from external events sent by Standard Webhooks, Sentry, Stripe, GitHub, or Slack, with signature verification and idempotent delivery.

A webhook lets an external system start one of your workflows by POSTing an event to AGNT5. The gateway verifies the sender's signature, turns the delivery into a durable event, and starts every workflow subscribed to it. You write a workflow and declare which event it listens for. AGNT5 handles receipt, verification, deduplication, and dispatch.

This page covers the mechanism end to end using **Standard Webhooks**, a publisher you control. To connect a specific third-party service, see [Integrations → Event sources](/docs/integrations/event-sources/overview.md), which layers provider-specific setup on top of everything here.

---

## How it works

1. You create a webhook integration in Studio and receive a URL and a signing secret.
2. The external system POSTs events to `/v1/webhooks/{source}/{integration_id}` (Studio shows the full URL).
3. The gateway verifies the HMAC signature against your secret and rejects anything that fails with `401` before any workflow runs.
4. It derives an event name of the form `{source}.{event}` and starts every workflow whose trigger matches.
5. It returns `200` once the event is durably persisted to the log, which happens before your workflow finishes running.

---

## Declare a trigger

Subscribe a workflow to a webhook event with the `webhook()` trigger:

```python
from agnt5 import workflow, webhook

@workflow(
    name="triage_issue",
    triggers=[webhook("sentry", event="issue.created")],
)
async def triage_issue(ctx, event: dict) -> dict:
    payload = json.loads(event["body"])  # raw request body, as a string
    issue = payload["data"]["issue"]
    ...
```

`webhook("sentry", event="issue.created")` subscribes the workflow to the event `sentry.issue.created`. The `source` is one of `standard`, `sentry`, `stripe`, `github`, or `slack`. The `event` is the identifier within that source. The format differs per provider; see [Event names](#event-names) below.

A single event can fan out to multiple workflows: every workflow whose trigger matches `{source}.{event}` starts independently.

---

## What your workflow receives

Each matched workflow starts with one envelope as its input:

```json
{
  "_webhook": true,
  "source": "sentry",
  "integration_id": "int_abc123",
  "event_type": "sentry.issue.created",
  "idempotency_key": "req_9f3c…",
  "timestamp": 1733337600,
  "headers": { "sentry-hook-resource": "issue", "request-id": "req_9f3c…" },
  "body": "{\"action\":\"created\",\"data\":{ … }}"
}
```

`body` is the raw request body as a string. Parse it yourself so you operate on exactly the bytes that were signature-verified. `headers` keys are lowercased. `idempotency_key` is the provider's stable per-delivery id (absent for Slack, see [Delivery semantics](#delivery-semantics)).

---

## Set up an integration

You connect the sending side in Studio, once per source:

1. **Studio → Integrations → New**, then pick a source.
2. Choose the **environment** whose deployment should receive the triggers.
3. Provide the **signing secret**. For GitHub and Standard Webhooks, AGNT5 generates the secret. Copy it into the publisher. For Stripe, Slack, and Sentry, paste the secret the provider issues; generating one here would never match.
4. Copy the **webhook URL** Studio shows (`…/v1/webhooks/{source}/{integration_id}`) into the provider's webhook settings.

Provider-by-provider walkthroughs live under [Integrations → Event sources](/docs/integrations/event-sources/overview.md).

---

## Signature verification

Every delivery must carry a valid signature; AGNT5 rejects unsigned or mismatched requests with `401` before any workflow runs. Each source uses its provider's native HMAC-SHA256 scheme:

| Source | Signature header | Signed payload | Replay window |
|---|---|---|---|
| `standard` | `webhook-signature` (`v1,<base64>`) | `{id}.{timestamp}.{body}` | 5 min |
| `sentry` | `sentry-hook-signature` (hex) | raw body | n/a |
| `stripe` | `Stripe-Signature` (`t=…,v1=…`) | `{timestamp}.{body}` | 5 min |
| `github` | `X-Hub-Signature-256` (`sha256=…`) | raw body | n/a |
| `slack` | `X-Slack-Signature` (`v0=…`) + timestamp | `v0:{timestamp}:{body}` | 5 min |

Standard Webhooks and Stripe accept several signatures on one delivery, so you can rotate signing keys without dropping events.

---

## Delivery semantics

Webhook delivery is **at-least-once**. Publishers retry on any non-2xx response, and AGNT5 collapses retries using the provider's per-delivery idempotency key: `webhook-id` for Standard Webhooks, `Request-ID` for Sentry, the event `id` for Stripe, `X-GitHub-Delivery` for GitHub. A retried delivery replays the original run instead of starting a new one.

Two cases fall outside that deduplication, and either can start a workflow more than once for the same event:

- **Slack** carries no stable per-delivery id, so Slack retries are not de-duplicated.
- The idempotency cache is per–gateway instance and time-bounded. A retry that arrives after a gateway restart, or lands on a different gateway in a multi-node deployment, sees a cold cache.

<Callout type="warning">**Make webhook-triggered workflows idempotent.** Key your side effects off `event_type` and `idempotency_key` (or an id inside the body) so a re-delivery is a no-op. AGNT5 guarantees a workflow runs at least once per event, not exactly once.</Callout>

---

## Event names

The event your trigger matches is always `{source}.{event}`. What you pass as `event` depends on the source:

| Source | `event` you pass | Resulting event name |
|---|---|---|
| `standard` | the `webhook-event` header value | `standard.<event>` |
| `sentry` | `<resource>.<action>` | `sentry.issue.created` |
| `stripe` | the body `type` | `stripe.payment_intent.succeeded` |
| `github` | `<event>.<action>`, or just `<event>` | `github.issues.opened` |
| `slack` | the event-callback type | `slack.app_mention` |

---

## Related

- [Integrations → Event sources](/docs/integrations/event-sources/overview.md): connect Sentry, Stripe, GitHub, and Slack
- [Integrations → Overview](/docs/integrations/overview.md): how integrations and signing secrets are stored
- [Workflows](/docs/build/workflows.md): what a workflow is and how it runs

---

## Workflows

_Source: https://agnt5.com/docs/build/workflows.md_

> Define durable orchestrators that sequence functions, agents, and human approvals into reliable pipelines.

A **workflow** is a durable orchestrator that sequences functions, agents, and human approvals into a reliable pipeline. If a workflow crashes mid-run, it restarts and picks up from the last completed step rather than starting over.

---

## Defining a workflow

Decorate any async function with `@workflow`. The function is registered automatically at import time.

```python
from agnt5 import workflow, WorkflowContext

@workflow
async def onboarding_workflow(ctx: WorkflowContext, user_email: str) -> dict:
    account = await ctx.step(create_account, user_email)
    await ctx.step(send_welcome_email, account["id"])
    return {"status": "done", "account_id": account["id"]}
```

The first parameter must be `ctx: WorkflowContext`. Everything after that is your workflow's input (whatever the caller passes) when triggering the run.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `name` | `str` | `function.__name__` | Name registered with the platform |
| `triggers` | `list[TriggerSpec]` | `None` | Event or webhook triggers that start this workflow automatically |

---

## Steps: the unit of durable work

Use `ctx.step()` to call a `@function` inside a workflow. The result is checkpointed after the first successful run. On replay (after a restart), the cached result is returned immediately. The function is not called again.

```python
from agnt5 import workflow, WorkflowContext, function, FunctionContext

@function
async def fetch_user(ctx: FunctionContext, user_id: str) -> dict:
    # call your database here
    return {"id": user_id, "name": "Ada"}

@function
async def send_email(ctx: FunctionContext, user: dict, subject: str) -> str:
    # call your email provider here
    return f"Sent to {user['name']}"

@workflow
async def notify_workflow(ctx: WorkflowContext, user_id: str) -> str:
    user   = await ctx.step(fetch_user, user_id)
    result = await ctx.step(send_email, user, "Welcome!")
    return result
```

Calling `await fetch_user(ctx, user_id)` directly also works, but that result is **not** checkpointed. The function re-runs every time the workflow replays.

| Call style | Checkpointed | Use when |
|---|---|---|
| `await ctx.step(fn, *args)` | Yes | Always prefer this inside a workflow |
| `await fn(ctx, *args)` | No | One-off calls where replay is fine |

---

## Running in parallel

### `ctx.parallel()`: run tasks concurrently, collect in order

```python
@workflow
async def report_workflow(ctx: WorkflowContext, report_id: str) -> dict:
    sales, inventory, customers = await ctx.parallel(
        ctx.step(fetch_sales, report_id),
        ctx.step(fetch_inventory, report_id),
        ctx.step(fetch_customers, report_id),
    )
    return await ctx.step(compile_report, sales, inventory, customers)
```

Results come back in the same order as the tasks.

### `ctx.gather()`: run tasks concurrently, collect by name

```python
@workflow
async def dashboard_workflow(ctx: WorkflowContext) -> dict:
    data = await ctx.gather(
        revenue=fetch_revenue(),
        users=fetch_active_users(),
        errors=fetch_error_rate(),
    )
    # data["revenue"], data["users"], data["errors"]
    return data
```

### `ctx.batch()`: run a function across many inputs

Use `batch()` when you have a list of items and want to process them in parallel with controlled concurrency.

```python
@function
async def process_document(ctx: FunctionContext, doc_id: str) -> dict:
    # process one document
    return {"doc_id": doc_id, "status": "processed"}

@workflow
async def bulk_processor(ctx: WorkflowContext, doc_ids: list[str]) -> dict:
    result = await ctx.batch(
        process_document,
        [{"doc_id": d} for d in doc_ids],
        max_concurrency=20,
    )
    return {
        "processed": result.stats.completed_items,
        "failed":    result.stats.failed_items,
    }
```

`ctx.map()` is a simpler wrapper around `batch()`. It returns just the outputs and raises if any item fails:

```python
outputs = await ctx.map(process_document, [{"doc_id": d} for d in doc_ids])
```

---

## Durable sleep

`ctx.sleep()` pauses the workflow for a set duration. Unlike `asyncio.sleep()`, it survives restarts. If the worker crashes during the wait, the workflow resumes and only sleeps for the time that remains.

```python
@workflow
async def follow_up_workflow(ctx: WorkflowContext, user_id: str) -> str:
    await ctx.step(send_confirmation, user_id)

    await ctx.sleep(24 * 60 * 60, name="wait_24h")   # wait 24 hours

    await ctx.step(send_follow_up, user_id)
    return "Follow-up sent."
```

---

## State

Workflows have access to three state scopes through `ctx`.

```python
@workflow
async def stateful_workflow(ctx: WorkflowContext, user_id: str) -> dict:
    # Run-scoped: lives for this run only
    await ctx.state.set("phase", "started")

    # Session-scoped: persists across turns for the same session
    count = await ctx.session.state.get("visit_count", 0)
    await ctx.session.state.set("visit_count", count + 1)

    return {"visits": count + 1}
```

| Scope | Access | Persists |
|---|---|---|
| Run | `ctx.state` | Current run only. Cleared when the run finishes |
| Session | `ctx.session.state` | Across multiple runs with the same `session_id` |

---

## Triggering workflows

### Event trigger

Start a workflow automatically when a named event fires.

```python
from agnt5 import workflow, WorkflowContext
from agnt5.types import event

@workflow(triggers=[event("user.signed_up")])
async def welcome_workflow(ctx: WorkflowContext, user_id: str) -> str:
    await ctx.step(send_welcome_email, user_id)
    return "Welcome email sent."
```

### Webhook trigger

Start a workflow from an incoming webhook.

```python
from agnt5.types import webhook

@workflow(triggers=[webhook("stripe", event="payment_intent.succeeded")])
async def payment_workflow(ctx: WorkflowContext, amount: int, currency: str) -> str:
    await ctx.step(record_payment, amount, currency)
    return "Payment recorded."
```

---

## Human-in-the-loop

Pause a workflow and wait for user input using `ctx.wait_for_user()`. See [Human-in-the-loop](/docs/build/human-in-the-loop.md) for the full reference.

```python
@workflow
async def approval_workflow(ctx: WorkflowContext, order_id: str) -> dict:
    summary = await ctx.step(prepare_order_summary, order_id)

    decision = await ctx.wait_for_user(
        question=f"Approve this order?\n\n{summary}",
        input_type="approval",
        options=[
            {"id": "approve", "label": "Approve"},
            {"id": "reject",  "label": "Reject"},
        ],
    )

    if decision == "reject":
        return {"status": "rejected"}

    result = await ctx.step(fulfil_order, order_id)
    return result
```

---

## Real-world example

An order processing pipeline: validate the order, charge the customer, and send a confirmation, all as durable steps. If any step fails, the workflow retries from that point without re-running earlier steps.

```python
from agnt5 import workflow, WorkflowContext, function, FunctionContext


@function
async def validate_order(ctx: FunctionContext, order_id: str) -> dict:
    # check stock, validate address, etc.
    return {"order_id": order_id, "total": 89.99, "valid": True}


@function
async def charge_customer(ctx: FunctionContext, order_id: str, amount: float) -> dict:
    # call your payments API
    return {"order_id": order_id, "charge_id": "ch_abc123", "status": "paid"}


@function
async def send_confirmation(ctx: FunctionContext, order_id: str, charge_id: str) -> str:
    # send confirmation email
    return f"Confirmation sent for order {order_id}"


@workflow
async def order_workflow(ctx: WorkflowContext, order_id: str) -> dict:
    # Step 1: validate
    order = await ctx.step(validate_order, order_id)

    if not order["valid"]:
        return {"status": "invalid", "order_id": order_id}

    # Step 2: charge (checkpointed, never charged twice even if workflow restarts)
    charge = await ctx.step(charge_customer, order_id, order["total"])

    # Step 3: confirm
    await ctx.step(send_confirmation, order_id, charge["charge_id"])

    return {"status": "complete", "order_id": order_id, "charge_id": charge["charge_id"]}
```

Each step is checkpointed. If the worker restarts between step 2 and step 3, the charge is not made again. The saved result is used and execution continues at step 3.

---

## Defining a workflow

_Source: https://agnt5.com/docs/build/workflows/defining-a-workflow.md_

> Write durable, multi-step workflows with automatic checkpointing and retries

A Workflow is a durable, multi-step program where every step is checkpointed and every call is retried. If the process crashes mid-run, the workflow resumes from the last completed step, not from the start.

<Callout type="tip">
  A Workflow is a try/catch block that spans hours. Functions are the units of work inside it: each one retries on failure, and each result is saved before the next step runs.
</Callout>

## Mental model

You write normal async Python. AGNT5 records every input and every result. When something fails, it replays the record. The function does not re-execute. When a step is new, it runs and its output is checkpointed before the workflow moves on.

Two primitives compose here. **Functions** are stateless units of computation with automatic retries and optional idempotency. **Workflows** chain functions into multi-step processes with checkpointing and parallelism.

## A minimal workflow

```python
from agnt5 import workflow, function, WorkflowContext

@function(retries=3, backoff="exponential")
async def fetch_papers(topic: str) -> list[dict]:
    return await arxiv_search(topic)

@function()
async def summarize(papers: list[dict]) -> str:
    return await call_llm(f"Summarize: {papers}")

@workflow()
async def research_pipeline(ctx: WorkflowContext, topic: str) -> dict:
    papers = await ctx.step(fetch_papers, topic)
    summary = await ctx.step(summarize, papers)
    return {"topic": topic, "summary": summary}
```

Invoke it:

```python
from agnt5 import Client

client = Client()
result = client.run("research_pipeline", {"topic": "quantum computing"}, component_type="workflow")
```

If the process dies after `fetch_papers`, the next run replays that checkpoint and only re-executes `summarize`.

## Functions: the unit of work

A Function is a durable, retryable computation. Failures retry with backoff. Every call is traced. Idempotency keys guarantee exactly-once execution.

```python
from agnt5 import function, FunctionContext

@function(retries=3)
async def call_flaky_api(ctx: FunctionContext, query: str) -> dict:
    ctx.log("Searching", query=query, attempt=ctx.attempt)
    return await external_api.search(query)
```

`FunctionContext` is optional. When present, it provides structured logging, a run ID, and the current retry attempt:

| Property | Description |
|----------|-------------|
| `ctx.log(msg, **kv)` | Structured logging with correlation IDs |
| `ctx.run_id` | Unique execution identifier |
| `ctx.attempt` | Current retry attempt (0-indexed) |

### Idempotency

Pass an `idempotency_key` when retries could cause side effects (payments, emails, record creation:

```python
client.run("charge_payment", {"amount": 99.99}, idempotency_key=f"order-{order_id}")
```

Same key returns the cached result. Different key executes fresh. Use deterministic keys derived from the logical operation (`payment-{order_id}`, `email-{user_id}-{campaign_id}`).

### Retry policies

Configure retry behavior on the decorator:

```python
from agnt5 import function, RetryPolicy, BackoffPolicy, BackoffType

@function(
    retries=RetryPolicy(max_attempts=5, initial_interval_ms=1000),
    backoff=BackoffPolicy(type=BackoffType.EXPONENTIAL, multiplier=2.0),
)
async def call_flaky_api(query: str) -> dict:
    return await external_api.search(query)
```

| Strategy | Pattern | Use case |
|----------|---------|----------|
| Exponential | 1s → 2s → 4s → 8s | Rate limits, overloaded services |
| Linear | 1s → 2s → 3s → 4s | Predictable recovery time |
| Constant | 1s → 1s → 1s → 1s | Fast retry for transient errors |

## Composition

`ctx.step()` runs a function with checkpointing. `ctx.parallel()` runs several at once:

```python
@workflow()
async def multi_source(ctx: WorkflowContext, topic: str) -> dict:
    arxiv, wiki, news = await ctx.parallel(
        ctx.step(search_arxiv, topic),
        ctx.step(search_wikipedia, topic),
        ctx.step(search_news, topic),
    )
    return {"arxiv": arxiv, "wiki": wiki, "news": news}
```

`ctx.step` accepts two forms: pass a `@function` with its arguments (above), or an explicit checkpoint name with an awaitable:

```python
@workflow()
async def research(ctx: WorkflowContext, topic: str) -> dict:
    research = await ctx.step("initial_research", call_llm(f"Research: {topic}"))
    analysis = await ctx.step("deep_analysis", call_llm(f"Analyze: {research}"))
    return {"analysis": analysis}
```

## Execution model

```mermaid
sequenceDiagram
    participant C as Client
    participant W as Workflow
    participant S as State Store

    C->>W: run(workflow, input)
    W->>W: Execute step 1
    W->>S: Checkpoint result
    W->>W: Execute step 2
    W->>S: Checkpoint result
    Note over W: Crash
    C->>W: Resume
    W->>S: Load checkpoints
    W->>W: Execute step 3
    W-->>C: Final result
```

Every `ctx.step()` writes to the checkpoint log before the next instruction runs. On replay, reads from that log short-circuit re-execution.

## When to use workflows

Workflows shine when the shape of the work is known ahead of time:

- Multi-step pipelines where each step is expensive and you don't want to re-run the early ones on failure
- Processes that must survive crashes mid-execution
- Fan-out / fan-in over N inputs with combined checkpointing
- Anything where the sequence of steps is a property of the code, not a decision made at runtime

If the next step depends on something you only learn at runtime (a tool result, an LLM's reasoning, a user's reply), reach for an [Agent](/docs/concepts/agents.md) instead.

## Common pitfalls

- **Side effects outside `ctx.step()`.** Anything called directly (not through a step) won't be checkpointed and will re-execute on replay.
- **Missing idempotency keys.** Without one, a retried payment can charge twice. With one, it can't.
- **Mixing durable and in-memory state.** Workflow-local variables don't survive a crash. They're scoped to the running process. Use checkpointed state via `ctx.step()` for anything that must persist across replays.

## Learn more

- [Workflows](/docs/concepts/workflows.md): the conceptual foundation
- [Agents](/docs/concepts/agents.md): when control flow is LLM-decided
- [Durable execution](/docs/concepts/durable-execution.md): what checkpoint and replay guarantee
- [Event sourcing and replay](/docs/concepts/event-sourcing-and-replay.md): how the journal works under the hood


# home

---

## AGNT5 Documentation

_Source: https://agnt5.com/docs/home.md_

> Build, run, and improve agentic workflows in one platform.

{/* Hero — text-only for v1. Code sample returns later as a polyglot tabbed example. */}
<div class="not-prose mb-16">
  <p class="text-muted-foreground text-lg max-w-2xl mb-8">
    AGNT5 is the runtime and all the tools needed for building agentic workflows, running them at any scale, and improving them against real production data. With AGNT5, teams can write agents in Python or TypeScript, deploy with a single command, inspect every step of every execution, and run experiments to measure whether a prompt change actually improves output quality.
  </p>
  <a
    href="/docs/quickstart"
    class="group bg-primary/10 border border-primary text-foreground px-6 h-10 text-base font-semibold rounded-md hover:bg-primary/30 transition-all duration-200 inline-flex items-center shadow-lg justify-center no-underline"
  >
    Quickstart
    <svg
      class="inline-block ml-2 w-4 h-4 group-hover:translate-x-1 transition-transform"
      fill="none"
      stroke="currentColor"
      viewBox="0 0 24 24"
    >
      <path
        stroke-linecap="round"
        stroke-linejoin="round"
        stroke-width="2"
        d="M13 7l5 5m0 0l-5 5m5-5H6"
      />
    </svg>
  </a>
</div>

<LinkCardGroup title="Start, build, run, and improve">
  <LinkCard
    title="Learning path"
    description="Follow a practical sequence from first workflow to deployment, operations, and improvement."
    href="/docs/learning-path"
    icon="play"
  />
  <LinkCard
    title="Build"
    description="Define workflows, agents, tools, prompts, webhooks, and human approval flows in application code."
    href="/docs/build/overview"
    icon="code"
  />
  <LinkCard
    title="Run"
    description="Deploy workers, trigger production runs, inspect traces, stream logs, and watch runtime metrics."
    href="/docs/run/overview"
    icon="eye"
  />
  <LinkCard
    title="Improve"
    description="Turn production run data into datasets, scorers, experiments, and safer prompt changes."
    href="/docs/improve/overview"
    icon="refresh"
  />
</LinkCardGroup>


# improve

---

## Batch eval

_Source: https://agnt5.com/docs/improve/batch-eval.md_

> Run a component against multiple inputs in parallel, score every output, and inspect aggregate results using the Python or TypeScript SDK.

**Batch eval** lets you evaluate a component against a list of inputs in a single call. The SDK runs each input in parallel, scores every output, and returns a single result object with per-item scores and aggregate statistics. Use batch eval for local regression testing, CI pipelines that don't need the full [Experiments](/docs/improve/experiments.md) workflow, or quick quality checks during development.

You need a running AGNT5 worker and at least one scorer. Point the client at your worker by setting `AGNT5_GATEWAY_URL` in your environment — `Client()` and `AsyncClient()` pick it up automatically and fall back to `https://gw.agnt5.com` when the variable is not set.

```bash
# local dev
export AGNT5_GATEWAY_URL=http://localhost:34181
```

## Run a single eval

`client.eval()` evaluates one input and returns a scored result:

```python
from agnt5 import Client
from agnt5.eval import Correctness

client = Client()

result = client.eval(
    component="support_agent",
    component_type="agent",
    input_data={"message": "Where is my order #1234?"},
    expected="Your order #1234 is in transit",
    scorers=[Correctness()],
)

print(result.passed)           # True / False
print(result.output)           # Component output
for score in result.scores:
    print(score.scorer, score.score, score.passed, score.explanation)
```

## Run a batch

`client.batch_eval()` accepts a list of inputs and runs them in parallel:

```python
from agnt5 import Client, BatchEvalItem

client = Client()

result = client.batch_eval(
    component="support_agent",
    component_type="agent",
    items=[
        BatchEvalItem(
            input={"message": "Where is my order #1234?"},
            expected="Your order #1234 is in transit",
            item_id="order-status",
        ),
        BatchEvalItem(
            input={"message": "I want to cancel order #5678"},
            expected="Order #5678 has been cancelled",
            item_id="order-cancel",
        ),
    ],
    scorers=["exact_match"],
)

print(f"Pass rate: {result.pass_rate:.0%}")
for item in result.results:
    status = "PASS" if item.passed else "FAIL"
    print(f"{item.item_id}: {status} ({item.duration_ms}ms)")
```

## Input formats

`batch_eval()` accepts items in several forms — mix them freely:

**Plain dicts with a separate `expected` list:**

```python
result = client.batch_eval(
    component="greet",
    items=[{"name": "Alice"}, {"name": "Bob"}],
    expected=["Hello, Alice!", "Hello, Bob!"],
    scorers=["exact_match"],
)
```

**Dicts with `input` and `expected` keys:**

```python
result = client.batch_eval(
    component="add",
    items=[
        {"input": {"a": 1, "b": 2}, "expected": 3},
        {"input": {"a": 3, "b": 4}, "expected": 7, "item_id": "add-2"},
    ],
    scorers=["exact_match"],
)
```

**`BatchEvalItem` objects for full control:**

```python
from agnt5 import BatchEvalItem

result = client.batch_eval(
    component="add",
    items=[
        BatchEvalItem(input={"a": 1, "b": 2}, expected=3, item_id="add-1"),
        BatchEvalItem(input={"a": 3, "b": 4}, expected=7, item_id="add-2"),
    ],
    scorers=["exact_match"],
)
```

## Scorers

Pass scorer names, SDK preset classes, or `LLMJudge` instances. Combine them freely:

```python
from agnt5.eval import Correctness, Helpfulness, LLMJudge

scorers = [
    "json_valid",          # Fast structure check
    "contains",            # Required substring
    Correctness(),         # Managed correctness preset
    Helpfulness(model="openai/gpt-4o"),
    LLMJudge(
        criteria="Is the response under 50 words?",
        model="openai/gpt-4o-mini",
    ),
]
```

All [built-in deterministic scorers](/docs/improve/scorers.md#built-in-deterministic-scorers) work as strings. All [SDK evaluator presets](/docs/improve/scorers.md#sdk-evaluator-presets) work as class instances.

## Concurrency and timeouts

```python
result = client.batch_eval(
    component="slow_agent",
    component_type="agent",
    items=test_items,
    scorers=[Correctness()],
    max_concurrency=5,   # Parallel evaluations (default 10)
    timeout=60.0,        # Per-item timeout in seconds
)
```

For large batches, start with `max_concurrency=3` and `timeout=30.0` during development, then increase for production runs.

## Async client

```python
const client = new Client();

const result = await client.batchEval(
  'support_agent',
  [
    { input: { message: 'Where is my order #1234?' }, expected: 'Your order #1234 is in transit', itemId: 'order-status' },
    { input: { message: 'I want to cancel order #5678' }, expected: 'Order #5678 has been cancelled', itemId: 'order-cancel' },
  ],
  {
    scorers: [new Correctness()],
    componentType: 'agent',
    maxConcurrency: 5,
  },
);

console.log(`Pass rate: ${(result.passRate * 100).toFixed(0)}%`);
for (const item of result.results) {
  const status = item.passed ? 'PASS' : 'FAIL';
  console.log(`${item.itemId}: ${status} (${item.durationMs}ms)`);
}
```

`Client` reads `AGNT5_GATEWAY_URL` from `process.env` automatically. All input formats from the Python section work the same way in TypeScript.


**Python API**: `client.eval(component, input, expected?, scorers?, component_type?)` -> `EvalResponse`; `client.batch_eval(component, items, scorers?, expected?, component_type?, max_concurrency=10, timeout?)` -> `BatchEvalResult`.
**Input normalization**: plain dicts use positional `expected` list; dicts with `input` key use embedded `expected`; `BatchEvalItem(input, expected?, item_id?, index?)` for full control.
**Scorers**: strings ("exact_match"), SDK preset instances (`Correctness()`, `Helpfulness(model=...)`), or `LLMJudge(criteria, model, include_input, temperature)`.
**BatchEvalResult**: `batch_id`, `status` ("completed"/"partial_failure"/"failed"), `results: BatchEvalItemResult[]`, `stats: BatchEvalStats`, `pass_rate`, `passing_items()`, `failing_items()`, `failed_items()`.
**BatchEvalItemResult**: `index`, `run_id`, `output`, `scores: ScorerResultSummary[]`, `passed`, `duration_ms`, `item_id?`, `trace_id?`, `error?`, `get_score(name)`.


## Next steps

* [Scorers](/docs/improve/scorers.md): full reference for built-in scorers, SDK presets, and custom scorer code.
* [Experiments](/docs/improve/experiments.md): run a component against a versioned dataset, compare runs, and gate CI.
* [Datasets](/docs/improve/datasets.md): curate test cases from production runs and publish immutable versions.
* [Agents](/docs/build/agents.md): structure agent tool use so scorers have predictable events to check.

---

## Datasets

_Source: https://agnt5.com/docs/improve/datasets.md_

> Curate eval datasets from production runs, manual examples, or file uploads, then publish immutable versions for experiments.

A **dataset** is a curated collection of test cases (inputs, expected outputs, and optional trace events) that [experiments](/docs/improve/experiments.md) run your components against. You build a dataset from real production runs, hand-written examples, or bulk file uploads, then publish it as an immutable version so experiment results stay comparable over time.

---

## Drafts and versions

Every dataset has one mutable **draft** and zero or more immutable **versions**.

- **Draft**: the working set. Adding runs, uploading files, and removing duplicates all edit the draft.
- **Version**: a numbered, immutable snapshot of the draft. Experiments run against a version, never the draft, so a result always points at the exact items it was scored on.

Each **dataset item** carries:

| Field | Description |
|---|---|
| `input` | JSON input passed to the component under test |
| `expected_output` | Optional JSON the scorers compare against |
| `metadata` | Optional JSON object for your own labels |
| `events` | Optional trace events, captured when importing from a run |
| `split` | Optional partition label (e.g. `train`, `test`) |

---

## Create a dataset

Via the CLI:

```bash
agnt5 datasets create \
  --name support-agent-golden-set \
  --description "Curated support conversations with verified answers"
```

Via Studio: open your project, go to **Evaluate** -> **Datasets**, and create a dataset from there.

```bash
# Find the dataset ID later
agnt5 datasets list --search support-agent
```

---

## Add examples

### From production runs

Importing a run captures its input, output, and trace events, so trace-level scorers (tool calls, token budgets) can score it later.

1. Find the run you want: `agnt5 inspect runs ls`, or copy the run ID from the **Runs** page in Studio.
2. Import it into the draft:

```bash
agnt5 datasets add-run <dataset-id> <run-id> \
  --expected-output '{"answer": "Refund issued within 5 business days"}'
```

The run's recorded output becomes the item's expected output unless you override it with `--expected-output`.

### Manual examples

```bash
agnt5 datasets add-example <dataset-id> \
  --input '{"message": "Where is my order #4512?"}' \
  --expected-output '{"intent": "order_status"}'
```

### Bulk upload from JSONL

One JSON object per line, with the same fields as a dataset item:

```jsonl
{"input": {"message": "Cancel my subscription"}, "expected_output": {"intent": "cancellation"}}
{"input": {"message": "Where is my order #4512?"}, "expected_output": {"intent": "order_status"}, "split": "test"}
```

```bash
agnt5 datasets upload <dataset-id> --file examples.jsonl

# Or pipe from stdin
cat examples.jsonl | agnt5 datasets upload <dataset-id>
```

### Bulk upload from CSV

Map CSV columns to item fields. By default the `input` and `expected_output` column headers map directly:

```bash
agnt5 datasets upload-csv <dataset-id> --file examples.csv \
  --input-column question \
  --expected-output-column answer \
  --split-column split
```

> **Note:** Valid rows import even when some rows are rejected (`--partial` defaults to true). Pass `--partial=false` to make the upload all-or-nothing.

---

## Remove duplicates

Imports from multiple sources can land the same example twice. Preview duplicates before removing anything:

```bash
# See duplicate groups in the draft
agnt5 datasets dedup preview <dataset-id> --include-preview

# Keep the earliest item in each group, remove the rest
agnt5 datasets dedup apply <dataset-id>

# Or remove specific items
agnt5 datasets dedup apply <dataset-id> --remove-item-id <item-id>
```

---

## Publish a version

Publishing snapshots the draft as the next immutable version:

```bash
agnt5 datasets publish <dataset-id> \
  --description "Adds 40 cancellation cases from last week's runs"
```

The draft stays editable after publishing. Keep curating and publish again when ready.

Manage versions:

```bash
# List versions
agnt5 datasets versions list <dataset-id>

# Export a version as JSONL
agnt5 datasets versions export <dataset-id> <version-id>

# Compare two versions (added, removed, changed items)
agnt5 datasets versions compare <dataset-id> <base-version-id> <compare-version-id>

# Reset the draft to a published version
agnt5 datasets versions restore-draft <dataset-id> <version-id>
```

```bash
# Inspect items in the draft or a specific version
agnt5 datasets examples list <dataset-id> --version 2 --include-payload
```


**Commands**: `agnt5 datasets {list,create,add-run,add-example,upload,upload-csv,dedup preview|apply,publish,versions list|export|compare|restore-draft,examples list}`
**Required**: authenticated session (`agnt5 auth login`); project binding (run inside the project directory)
**Item schema (JSONL)**: `{"input": <json>, "expected_output": <json?>, "metadata": <object?>, "events": <json?>, "split": <string?>}`
**Model**: one mutable draft per dataset; `publish` creates immutable numbered versions; experiments reference a dataset version ID.
**Global flags**: `--format table|json|jsonl` (output format; jsonl for piping to jq); `--project-id <uuid>` (target a specific project instead of the current context).


## Next steps

* [Scorers](/docs/improve/scorers.md): define how outputs in your dataset get judged.
* [Experiments](/docs/improve/experiments.md): run a component against a dataset version and score the results.
* [Deploying](/docs/run/deploying.md): produce the production runs that feed dataset curation.

---

## Experiments

_Source: https://agnt5.com/docs/improve/experiments.md_

> Run a deployed component against a dataset version, score every item, compare runs, and gate CI on the results.

An **experiment** binds a target (a deployed component or a prompt) to a [dataset](/docs/improve/datasets.md) version and a set of [scorers](/docs/improve/scorers.md). Each **experiment run** executes the target against every dataset item, scores the outputs, and produces a pass/fail summary you can compare across runs or enforce in CI.

---

## Experiment versions

- An experiment's definition (target, scorers, config) is versioned. Starting a run snapshots it as an immutable **experiment version**, so older runs always show the exact configuration that produced them.
- A run pairs one experiment version with one dataset version. Because both sides are immutable, two runs over the same dataset version are directly comparable.
- Each dataset item becomes a **run item** with its own output and per-scorer scores.

---

## List experiments

```bash
# All experiments in the current project
agnt5 experiments list

# Filter by dataset, status, or type
agnt5 experiments list --dataset-id <dataset-id> --status active
```

Available filters: `--dataset-id`, `--status`, `--type`. Use `--page` and `--page-size` for pagination.

---

## Create an experiment

The target component must already be [deployed](/docs/run/deploying.md). Then:

```bash
agnt5 experiments create \
  --name support-agent-quality \
  --dataset-id <dataset-id> \
  --dataset-version-id <dataset-version-id> \
  --target-type component \
  --deployment-id <deployment-id> \
  --component-name support_agent \
  --component-type agent \
  --builtin-scorer json_valid \
  --builtin-scorer '{"name":"tool_called","config":{"tool":"search_orders"}}' \
  --config '{"passed_threshold":1}'
```

- `--builtin-scorer` attaches a [built-in scorer](/docs/improve/scorers.md#built-in-deterministic-scorers) by name, or by JSON object when it needs config. Repeat for each scorer.
- `--scorer-id` attaches a deployed [custom scorer](/docs/improve/scorers.md#custom-scorers) by UUID.
- `--target-type prompt` with `--prompt-id` targets a [Prompt](/docs/build/prompts.md) instead of a component:

```bash
agnt5 experiments create \
  --name support-prompt-comparison \
  --dataset-id <dataset-id> \
  --dataset-version-id <dataset-version-id> \
  --target-type prompt \
  --deployment-id <deployment-id> \
  --prompt-id <prompt-id> \
  --prompt-version-id <prompt-version-id> \
  --builtin-scorer correctness
```

Via Studio: open your project, go to **Evaluate** -> **Experiments**, and create the experiment with the same choices — dataset version, target, and scorers.

---

## Run an experiment

```bash
# Fire and forget
agnt5 experiments run <experiment-id>

# Block until the run finishes; exit non-zero if the gate fails
agnt5 experiments run <experiment-id> --wait --timeout 15m
```

Useful overrides:

| Flag | Purpose |
|---|---|
| `--name` | Label the run (e.g. `pr-1234`) |
| `--deployment-id` | Compare a candidate deployment against the baseline for the same component |
| `--experiment-version-id` | Re-run an older immutable experiment version |
| `--fail-on-gate` | Return non-zero when the CI gate fails (default true with `--wait`) |
| `--config` | Override run-level config JSON (e.g. `'{"passed_threshold":0.9}'`) |

---

## Inspect results

```bash
# Runs for an experiment
agnt5 experiments runs list <experiment-id>

# One run's summary: status, pass rate, per-scorer aggregates
agnt5 experiments runs show <run-id>
# Also available as a standalone command:
agnt5 reports summary <run-id>

# Failed items only
agnt5 reports failures <run-id>

# Scores for a run — filter by scorer, item, component, or time window
agnt5 scores list --run-id <run-id>
agnt5 scores list --run-id <run-id> --scorer-id <scorer-id>
agnt5 scores list --run-id <run-id> --run-item-id <item-id>
agnt5 scores list --since 2h --component-name support_agent

# Hydrate scorer input, output, and evidence for one score
agnt5 scores evidence <score-id> --include scorer_input,scorer_output,evidence
```

In Studio, the experiment run page shows the run timeline, per-item results, and per-scorer scores; click any item to see its output and score evidence side by side.

Cancel a stuck run with `agnt5 experiments runs cancel <experiment-id> <run-id>`.

---

## Compare runs

Compare a candidate against a baseline over the same dataset version:

```bash
agnt5 experiments runs compare <base-run-id> <compare-run-id>
```

The comparison shows aggregate score movement and which items flipped between pass and fail. Studio renders the same comparison under **Evaluate** -> **Experiments** when you select two runs.

---

## Gate CI on eval results

Use the reports commands in a CI job to block a merge or deploy on eval regressions:

```bash
# Start a run for the freshly deployed candidate, wait, and gate
agnt5 experiments run <experiment-id> \
  --deployment-id "$CANDIDATE_DEPLOYMENT_ID" \
  --name "ci-$GIT_SHA" \
  --wait --fail-on-gate

# Or wait on an already-started run
agnt5 reports wait <run-id> --timeout 15m

# Print the gate verdict for a finished run
agnt5 reports ci <run-id>

# Export full artifacts for the build log
agnt5 reports export <run-id> --artifact-format csv --out-file eval-results.csv
```

Exit codes from `--wait`, `reports wait`, and `reports ci`:

| Code | Meaning |
|---|---|
| `0` | Gate passed |
| `2` | CI gate failed (run completed but pass rate below threshold) |
| `3` | Run failed or was cancelled |
| `4` | Wait timed out |

Use `--fail-on-gate=false` to suppress non-zero exits and inspect the result yourself.

The gate verdict comes from the experiment's config (for example `{"passed_threshold": 1}`), so the threshold lives with the experiment, not the pipeline.

---

## Turn failures into a regression dataset

After a run with failures, capture the failing items as a new dataset so fixes stay fixed:

```bash
agnt5 experiments runs regression-dataset <run-id> \
  --name support-agent-regressions \
  --start-run --wait

# Rerun against a specific deployment (e.g. a fix candidate)
agnt5 experiments runs regression-dataset <run-id> \
  --name support-agent-regressions \
  --start-run --deployment-id <candidate-deployment-id> --wait
```

This creates a dataset from the failed items (all of them, or specific ones via repeatable `--run-item-id`), a regression experiment over it, and — with `--start-run` — kicks off the first rerun immediately. Pass `--deployment-id` to run the regression against a specific deployment rather than the experiment's default.

---

## Rescore a completed run

After updating a scorer's logic or thresholds, rescore an existing completed run without re-executing the component. The original outputs stay intact; only the score records are replaced.

```bash
# Rescore all scorers on a run
curl -X POST "https://api.agnt5.com/api/v1/projects/<project-id>/experiments/<experiment-id>/runs/<run-id>/rescore" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "updated_rubric",
    "replace_latest": true
  }'
```

Optional request fields:

| Field | Purpose |
|---|---|
| `scorer_version_ids` | Restrict rescore to specific scorer version UUIDs (default: all) |
| `run_item_ids` | Restrict rescore to specific item UUIDs (default: all) |
| `reason` | Label for the rescore in audit history (default: `manual_rescore`) |
| `replace_latest` | Replace the current aggregate scores and gate result (default: `true`) |
| `idempotency_key` | Deduplicate concurrent rescore requests |

The response reports how many scoring jobs were enqueued, already queued, processed, completed, and skipped. Run the gate command after to see the updated verdict:

```bash
agnt5 reports ci <run-id>
```

Only **completed** runs can be rescored; running or pending runs return an error.

---

## Annotate run items

Add a human label to any run item to capture reviewer decisions alongside scorer verdicts. Annotations are stored separately from scores and used for meta-evaluation (measuring scorer accuracy against human judgement).

```bash
curl -X POST "https://api.agnt5.com/api/v1/projects/<project-id>/experiments/<experiment-id>/runs/<run-id>/items/<item-id>/annotations" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "human_label",
    "label": "pass",
    "metadata": {"reviewer": "alice", "note": "Correct order ID cited"}
  }'
```

Fields:

| Field | Required | Description |
|---|---|---|
| `label` | Yes | Reviewer verdict (any string, e.g. `pass`, `fail`, `partial`) |
| `name` | No | Annotation name (default: `human_label`) |
| `metadata` | No | JSON object with reviewer notes (max 64 KB) |

List annotations for an item:

```bash
curl "https://api.agnt5.com/api/v1/projects/<project-id>/experiments/<experiment-id>/runs/<run-id>/items/<item-id>/annotations" \
  -H "Authorization: Bearer <token>"
```

In Studio, annotations appear inline next to scorer results in the run item detail view.

## Output formats and project targeting

All eval commands accept two persistent flags:

| Flag | Description |
|---|---|
| `--format table\|json\|jsonl` | Output format. Defaults to `table` in the terminal, `json` when `--output json` is set globally. Use `jsonl` to stream one record per line for piping to `jq`. |
| `--project-id <uuid>` | Target a specific project UUID instead of the current project context. |

```bash
# Machine-readable output for scripting
agnt5 experiments list --format json | jq '.[].id'

# Pipe failures to jq for filtering
agnt5 reports failures <run-id> --format jsonl | jq 'select(.item.passed == false)'

# Target a specific project
agnt5 datasets list --project-id <project-id>
```

---


**Commands**: `agnt5 experiments {list,create,run,runs list|show|cancel|compare|regression-dataset}`, `agnt5 reports {summary,failures,ci,wait,export}`, `agnt5 scores {list,evidence}`
**Create requires**: `--name`, `--dataset-id`, `--dataset-version-id`, target (`--target-type component --deployment-id --component-name --component-type`, or `--target-type prompt --prompt-id`), at least one `--builtin-scorer <name|json>` or `--scorer-id <uuid>`
**CI gating**: `experiments run --wait --fail-on-gate` and `reports ci|wait` exit non-zero on gate failure; threshold set via experiment `--config '{"passed_threshold": <0..1>}'`; exit codes: 2=gate failed, 3=run failed/cancelled, 4=timeout
**Rescore**: `POST /api/v1/projects/{projectId}/experiments/{experimentId}/runs/{runId}/rescore` — only completed runs; optional `scorer_version_ids` and `run_item_ids` to narrow scope; `replace_latest: true` refreshes aggregates.
**Annotations**: `POST /api/v1/projects/{projectId}/experiments/{experimentId}/runs/{runId}/items/{itemId}/annotations` with `label` (required), `name`, `metadata`; used for meta-evaluation against human judgement.
**Model**: experiment versions and dataset versions are immutable; a run = one experiment version × one dataset version; per-item scores queryable via `scores list --run-id`.


## Next steps

* [Datasets](/docs/improve/datasets.md): grow the dataset behind the experiment and publish a new version.
* [Scorers](/docs/improve/scorers.md): tighten what pass/fail means, or write a custom scorer.
* [Quality cases](/docs/improve/quality-cases.md): track regressions and production failures through a structured lifecycle.
* [Deploying](/docs/run/deploying.md): ship the candidate deployment your experiment runs against.
* [Prompts](/docs/build/prompts.md): version the prompt artifacts that prompt-target experiments compare.

---

## Enable online evals

_Source: https://agnt5.com/docs/improve/online-evals.md_

> Sample production runs, score them asynchronously, and alert when pass rate drops below a threshold.

Online evals let you measure production behavior without blocking user traffic. You attach a published **scorer**, a rule that grades a run or trace, to a **deployment**, a running AGNT5 worker, then AGNT5 samples completed runs and scores them in the background. After setup, Studio shows live score aggregates, sample decisions, alerts, and recent scores for that deployment.

## Prerequisites

- A deployment that is receiving production runs.
- At least one enabled scorer with a published version.
- A user or service token with developer access to the project.

## Set up online evals in Studio

1. Open the deployment in Studio.
2. Select the **Quality** tab.
3. Choose a **Scorer**.
4. Set **Sample %** for ordinary runs.
5. Set **Slow-run %** and **Slow-run threshold ms** when slow runs should be sampled more often.
6. Set **Pass-rate floor** and **Min count** for the optional alert.
7. Select **Preview** to estimate observed runs, selected runs, scorer jobs, and alert status.
8. Select **Enable** to create the online eval policy and alert.

Use the policy table to disable or enable a policy, disable or enable its alert, or select edit to create a new policy version with updated sampling and scorer settings.

## Preview with the API

Previewing does not create a policy. It evaluates the proposed sampling config against recent completed runs and returns selected/skipped counts, reason buckets, scorer job estimates, and optional alert status.

```bash
curl -X POST "https://api.agnt5.com/api/v1/projects/<project-id>/eval/online/preview" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "lookback_seconds": 86400,
    "max_runs": 1000,
    "policy": {
      "mode": "async_online",
      "binding_scope": "deployment",
      "deployment_id": "<deployment-id>",
      "sampling_config": {
        "type": "uniform",
        "rate": 0.02,
        "boost": [
          {
            "field": "duration_ms",
            "op": "gte",
            "value": 30000,
            "rate": 0.10
          }
        ]
      },
      "scorers": [
        {
          "scorer_id": "<scorer-id>",
          "scorer_version_id": "<scorer-version-id>",
          "scope": "run",
          "ordinal": 1,
          "required": true,
          "threshold": 0.9,
          "weight": 1
        }
      ]
    },
    "alert": {
      "name": "Production quality drop",
      "severity": "warning",
      "deployment_id": "<deployment-id>",
      "scorer_id": "<scorer-id>",
      "scorer_version_id": "<scorer-version-id>",
      "window_seconds": 1800,
      "metric": "pass_rate",
      "operator": "lt",
      "threshold": 0.9,
      "min_count": 50,
      "action_type": "notify"
    }
  }'
```

The preview response includes job volume, not a price estimate. Scorer cost depends on model/provider configuration and custom scorer runtime.

## Enable with the API

Create the policy first, then create an alert linked to the returned policy ID.

```bash
curl -X POST "https://api.agnt5.com/api/v1/projects/<project-id>/eval/policies" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "async_online",
    "binding_scope": "deployment",
    "deployment_id": "<deployment-id>",
    "sampling_config": {
      "type": "uniform",
      "rate": 0.02,
      "boost": [
        {
          "field": "duration_ms",
          "op": "gte",
          "value": 30000,
          "rate": 0.10
        }
      ]
    },
    "scorers": [
      {
        "scorer_id": "<scorer-id>",
        "scorer_version_id": "<scorer-version-id>",
        "scope": "run",
        "ordinal": 1,
        "required": true,
        "threshold": 0.9,
        "weight": 1
      }
    ]
  }'
```

```bash
curl -X POST "https://api.agnt5.com/api/v1/projects/<project-id>/eval/online/alerts" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production quality drop",
    "severity": "warning",
    "evaluation_policy_id": "<policy-id>",
    "deployment_id": "<deployment-id>",
    "scorer_id": "<scorer-id>",
    "scorer_version_id": "<scorer-version-id>",
    "window_seconds": 1800,
    "metric": "pass_rate",
    "operator": "lt",
    "threshold": 0.9,
    "min_count": 50,
    "action_type": "notify"
  }'
```

## Operate online evals

Use these endpoints to inspect or change a running setup:

| Task | Endpoint |
| --- | --- |
| List policies | `GET /api/v1/projects/<project-id>/eval/policies?mode=async_online&deployment_id=<deployment-id>` |
| Disable a policy | `PATCH /api/v1/projects/<project-id>/eval/policies/<policy-id>` with `{ "enabled": false }` |
| Create a new policy version | `PATCH /api/v1/projects/<project-id>/eval/policies/<policy-id>` with new `sampling_config` or `scorers` |
| List sample decisions | `GET /api/v1/projects/<project-id>/eval/online/sample-decisions?deployment_id=<deployment-id>` |
| List live scores | `GET /api/v1/projects/<project-id>/eval/scores?source=live&deployment_id=<deployment-id>` |
| Get live score aggregate | `GET /api/v1/projects/<project-id>/eval/online/scores/aggregate?source=live&deployment_id=<deployment-id>` |
| Disable an alert | `PATCH /api/v1/projects/<project-id>/eval/online/alerts/<alert-id>` with `{ "enabled": false }` |

## Next steps

- [Improve with AGNT5](/docs/improve/overview.md): understand how production runs feed scorers, datasets, and experiments.
- [Deploying](/docs/run/deploying.md): deploy a worker before attaching online evals.
- [Workflows](/docs/build/workflows.md): structure runs so scorers can inspect stable inputs and outputs.

---

## Improve with AGNT5

_Source: https://agnt5.com/docs/improve/overview.md_

> Use production run data to create datasets, score outputs, compare candidates, and gate changes.

Improve covers the eval loop for deployed AGNT5 components. You use production runs to curate datasets, score outputs, and compare candidate prompts, models, or agent behavior before rolling changes forward.

## What you'll do

- **[Datasets](/docs/improve/datasets.md)**: collect representative inputs from production runs or authored examples.
- **[Scorers](/docs/improve/scorers.md)**: define how AGNT5 decides whether an output meets the target behavior.
- **[Experiments](/docs/improve/experiments.md)**: compare a candidate prompt, model, or agent behavior against a baseline.
- **[Online evals](/docs/improve/online-evals.md)**: score production runs asynchronously and alert when quality drops.
- **[Batch eval](/docs/improve/batch-eval.md)**: run evaluations from code using `client.eval()` or `client.batch_eval()`.
- **[Quality cases](/docs/improve/quality-cases.md)**: track regressions and production issues through a structured lifecycle.
- **[Prompts](/docs/build/prompts.md)**: version prompt changes and compare them before they affect production traffic.

Outcome: you can decide whether a change improves agent behavior using the same platform that runs the agent.

## Next steps

- [Datasets](/docs/improve/datasets.md): curate test cases from production runs and publish immutable versions.
- [Scorers](/docs/improve/scorers.md): pick built-in checks or write custom scorer code.
- [Experiments](/docs/improve/experiments.md): run, compare, and gate CI on eval results.
- [Batch eval](/docs/improve/batch-eval.md): run evaluations directly from the Python or TypeScript SDK.
- [Quality cases](/docs/improve/quality-cases.md): track issues from discovery to verified fix.
- [Run with AGNT5](/docs/run/overview.md): capture the production run data that feeds improvement work.

---

## Quality cases

_Source: https://agnt5.com/docs/improve/quality-cases.md_

> Track production failures, eval regressions, and behavior issues through a structured lifecycle from discovery to verified fix.

A **quality case** is a structured issue record that tracks a behavior problem from discovery to resolution. When an [online eval](/docs/improve/online-evals.md) alert fires, an [experiment](/docs/improve/experiments.md) run regresses, or a production run fails in an unexpected way, you open a quality case to investigate the root cause, iterate on a fix, and verify it before shipping.

Quality cases connect directly to the runs, scores, datasets, and deployments already in AGNT5 with no separate issue tracker required. Studio surfaces them under **Evaluate** -> **Quality cases**.

## Case anatomy

Every case has:

| Field | Description |
|---|---|
| `title` | Short summary of the problem |
| `description` | Detail about what happened and why it matters |
| `category` | Problem type (see below) |
| `severity` | `low`, `medium`, `high`, or `critical` |
| `status` | Current lifecycle stage (see below) |
| `source_type` | What triggered the case |
| `expected_behavior` | What the component should have done |
| `observed_behavior` | What it actually did |
| `labels` | Free-form tags for filtering |

### Categories

| Category | When to use |
|---|---|
| `behavior_quality` | Output was wrong, incomplete, or unhelpful |
| `eval_regression` | An experiment run score dropped below baseline |
| `production_failure` | A live run raised an error or timed out |
| `deployment_health` | A deployment is unhealthy or unresponsive |
| `runtime_infra` | Platform-level infrastructure issue |
| `support_request` | Issue escalated from a user report |
| `release_risk` | A change introduces risk before a planned release |

## Lifecycle

Cases flow through a fixed set of statuses:

```
open → triaged → investigating → candidate_ready → verified → shipped → closed
```

| Status | Meaning |
|---|---|
| `open` | Newly created; not yet reviewed |
| `triaged` | Reviewed; severity and category confirmed |
| `investigating` | Root cause analysis in progress |
| `candidate_ready` | A fix candidate is ready for eval |
| `verified` | Eval results confirm the fix works |
| `shipped` | Fix deployed to production |
| `closed` | Resolved or won't fix |

Move a case forward by updating its status via the API or Studio.

## Create a case

### From Studio

Open **Evaluate** -> **Quality cases** -> **New case**, fill in the fields, and optionally link a run, experiment, or alert at creation time.

### From the API

```bash
curl -X POST "https://api.agnt5.com/api/v1/projects/<project-id>/quality/cases" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Support agent cites wrong order status",
    "description": "Agent reported order as shipped when it was still processing for 3 of 50 eval items.",
    "category": "behavior_quality",
    "severity": "high",
    "source_type": "eval_run_item",
    "experiment_run_id": "<run-id>",
    "expected_behavior": "Agent returns current status from orders API",
    "observed_behavior": "Agent returned stale cached status",
    "labels": ["orders", "caching"]
  }'
```

### From an MCP tool

If you're using Claude with AGNT5, three MCP tools let you create and query cases from inside agent workflows or conversations: `create_quality_case`, `get_quality_case`, and `list_quality_cases`. These accept the same fields as the REST API and return the same case structure.

### From an experiment run failure

After a run with failures, create a case directly from the failing items:

```bash
# From the experiment run page in Studio:
# Select failing items → Actions → Create quality case

# Or link an existing case to a run item via API:
curl -X POST "https://api.agnt5.com/api/v1/projects/<project-id>/quality/cases/<case-id>/links" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"link_type": "experiment_run_item", "link_id": "<run-item-id>"}'
```

## Update a case

```bash
# Move to investigating
curl -X PATCH "https://api.agnt5.com/api/v1/projects/<project-id>/quality/cases/<case-id>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "investigating",
    "description": "Root cause: prompt does not refresh order cache. Fixing in PR #42."
  }'
```

## List and filter cases

```bash
# All open high-severity cases
curl "https://api.agnt5.com/api/v1/projects/<project-id>/quality/cases?status=open&severity=high" \
  -H "Authorization: Bearer <token>"

# Cases in a specific category
curl "https://api.agnt5.com/api/v1/projects/<project-id>/quality/cases?category=eval_regression" \
  -H "Authorization: Bearer <token>"

# Cases with a label
curl "https://api.agnt5.com/api/v1/projects/<project-id>/quality/cases?label=orders" \
  -H "Authorization: Bearer <token>"
```

Filters: `status`, `severity`, `category`, `source_type`, `label`. All filters are optional and combinable.

## Create a regression dataset from a case

Once a fix is in review (`candidate_ready`), build a regression dataset from the failing items so the fix can be verified before shipping:

```bash
# In Studio: quality case detail → Actions → Create regression dataset
# Or via the experiments regression-dataset command linked to the run:
agnt5 experiments runs regression-dataset <run-id> \
  --name "order-status-regression" \
  --start-run --wait
```

Link the resulting dataset and experiment run back to the case:

```bash
curl -X PATCH "https://api.agnt5.com/api/v1/projects/<project-id>/quality/cases/<case-id>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"status": "verified"}'
```

When the regression experiment passes, mark the case `verified`, then `shipped` after deployment.

## Add events to the audit trail

Every status change, note, or link creates a case event automatically. Add an explicit note at any lifecycle stage:

```bash
curl -X POST "https://api.agnt5.com/api/v1/projects/<project-id>/quality/cases/<case-id>/events" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "note_added",
    "note": "Confirmed the stale cache issue reproduces on 10% of cold-start runs."
  }'
```

Event types: `note_added`, `investigation_added`, `candidate_linked`, `release_evidence_linked`.

## Source types

Cases can originate from any AGNT5 signal:

| Source type | Typical trigger |
|---|---|
| `eval_run_item` | Failing item in an experiment run |
| `eval_alert` | Online eval alert threshold breach |
| `runtime_run` | A specific production run failure |
| `guardrail_decision` | A guardrail blocked or flagged a run |
| `deployment` | Generic deployment health issue |
| `deployment_failure` | A deployment went unhealthy |
| `worker_health` | A worker is unhealthy or unreachable |
| `runtime_cluster` | Cluster-level runtime infrastructure issue |
| `manual` | Manually created from a report or observation |
| `support_ticket` | Escalated from a user |


**REST endpoints**: `POST /api/v1/projects/{id}/quality/cases` (create), `GET /api/v1/projects/{id}/quality/cases` (list, filters: status/severity/category/source_type/label), `GET /api/v1/projects/{id}/quality/cases/{caseId}` (get), `PATCH /api/v1/projects/{id}/quality/cases/{caseId}` (update), `POST /api/v1/projects/{id}/quality/cases/{caseId}/events` (add event), `POST /api/v1/projects/{id}/quality/cases/{caseId}/links` (add link).
**MCP tools**: `create_quality_case`, `get_quality_case`, `list_quality_cases`.
**Statuses**: open → triaged → investigating → candidate_ready → verified → shipped → closed.
**Categories**: behavior_quality, eval_regression, production_failure, deployment_health, runtime_infra, support_request, release_risk.
**Severities**: low, medium, high, critical.
**Source types**: eval_run_item, eval_alert, runtime_run, guardrail_decision, deployment_failure, worker_health, runtime_cluster, manual, support_ticket.


## Next steps

* [Experiments](/docs/improve/experiments.md): run a fix candidate against a regression dataset and gate on the result.
* [Online evals](/docs/improve/online-evals.md): set up alerts that automatically surface cases when production quality drops.
* [Datasets](/docs/improve/datasets.md): build the regression dataset that proves a fix works before shipping.
* [Deploying](/docs/run/deploying.md): ship the verified fix and close the case.

---

## Scorers

_Source: https://agnt5.com/docs/improve/scorers.md_

> Score component outputs with built-in deterministic checks, trace assertions, LLM-as-judge presets, or your own custom scorer code.

A **scorer** decides whether a component's output meets the target behavior. Each scorer returns a score between 0.0 and 1.0, a pass/fail verdict, and an optional explanation. [Experiments](/docs/improve/experiments.md) attach one or more scorers and run them against every [dataset](/docs/improve/datasets.md) item.

---

## Scorer classes

AGNT5 has exactly three scorer classes:

| Class | Examples | Needs deployment? |
|---|---|---|
| **Built-in deterministic** | `exact_match`, `json_schema`, `tool_called` | No — runs as AGNT5-owned logic |
| **Built-in LLM-as-judge** | `llm_judge`, `correctness`, `faithfulness` | No — AGNT5-owned, configurable model and rubric |
| **Custom** | Your `@scorer` functions | Yes — registered and deployed with your worker |

Built-ins work out of the box: select them in Studio or pass them to `agnt5 experiments create --builtin-scorer <name>`. Only custom scorers require your own code.

Scorers also differ by what they evaluate:

- **Output scorers** compare a single item's output against its input and expected output.
- **Trace scorers** assert on execution behavior — which tools were called, how many LLM calls were made, how long the run took. They need trace events, which dataset items carry when [imported from production runs](/docs/improve/datasets.md#from-production-runs).

---

## Built-in deterministic scorers

Output scorers:

| Scorer | Checks |
|---|---|
| `exact_match` | Output equals the expected output exactly |
| `contains` | Output contains a substring |
| `regex_match` | Output matches a regular expression |
| `json_valid` | Output is well-formed JSON |
| `json_schema` | Output validates against a JSON Schema |
| `numeric_range` | Numeric output falls within a range |
| `levenshtein` | Output is similar to expected by edit distance |
| `structured_assertions` | Configured assertions over input, output, and expected JSON |

Trace scorers:

| Scorer | Checks |
|---|---|
| `tool_called` / `tool_not_called` | A named tool was (or was not) called |
| `tool_sequence` / `tool_sequence_in_order` | Tools were called in the configured order |
| `tool_sequence_exact` | The tool trajectory matches exactly |
| `tool_sequence_any_order` | Configured tools all appear, in any order |
| `tool_trajectory` | Tools match a selected trajectory pattern |
| `tool_params_match` | Tool-call arguments match configured parameters |
| `max_tool_calls` / `max_llm_calls` | Total tool or LLM calls stay under a limit |
| `max_tokens` | Total LLM tokens stay under a budget |
| `duration_under` | Session duration stays under a limit |
| `no_errors` | The execution produced no errors |
| `state_equals` | A named state snapshot equals an expected value |

Pass a bare name for default behavior, or a JSON object for configuration:

```bash
agnt5 experiments create \
  --name support-agent-quality \
  --dataset-id <dataset-id> \
  --dataset-version-id <dataset-version-id> \
  --deployment-id <deployment-id> \
  --component-name support_agent \
  --component-type agent \
  --builtin-scorer json_valid \
  --builtin-scorer '{"name":"tool_called","config":{"tool":"search_orders"}}' \
  --builtin-scorer '{"name":"max_llm_calls","config":{"max":5}}'
```

---

## Built-in LLM-as-judge scorers

LLM-as-judge scorers use a language model to grade outputs against criteria. All are AGNT5-owned — no registration or deployment needed — and accept overridable judge settings: model, provider, prompt, and rubric.

| Scorer | What it grades |
|---|---|
| `llm_judge` | Generic judge — you supply the criteria and rubric |
| `correctness` | Output correctly answers the input and matches expected output |
| `faithfulness` | Output stays faithful to configured context fields; penalizes hallucination |

Pass them to an experiment the same way as deterministic scorers:

```bash
agnt5 experiments create \
  --name my-experiment \
  --dataset-id <dataset-id> \
  --dataset-version-id <dataset-version-id> \
  --deployment-id <deployment-id> \
  --component-name my_agent \
  --component-type agent \
  --builtin-scorer correctness \
  --builtin-scorer '{"name":"llm_judge","config":{"criteria":"Is the response concise and actionable?","model":"openai/gpt-4o-mini"}}'
```

> **Note:** Judge scorers call an LLM provider, so the project needs the provider credential configured (for example `OPENAI_API_KEY` as a [project secret](/docs/run/deploying.md#secrets)).

### SDK evaluator presets

The Python and TypeScript SDKs export typed preset classes for common LLM judge patterns. Use these with `client.eval()` and `client.batch_eval()` instead of raw scorer strings:

| Preset class | Grades |
|---|---|
| `Correctness` | Output correctly answers the input and matches expected |
| `Faithfulness` | Output is faithful to provided context; penalizes unsupported claims |
| `Helpfulness` | Output is useful, complete, and actionable for the user's task |
| `Coherence` | Output is logically organized and internally consistent |
| `Conciseness` | Output is concise while preserving all needed information |
| `ResponseRelevance` | Output directly addresses the input without off-topic content |
| `InstructionFollowing` | Output follows all explicit and implied instructions |
| `GoalSuccess` | Session achieved the user's goal (uses journal events and session state) |
| `Refusal` | Refusals are appropriate, well-explained, and offer safe alternatives |
| `Harmfulness` | Output avoids instructions or claims that could enable harm |
| `Stereotyping` | Output avoids stereotypes and biased generalizations |

```python
from agnt5.eval import Correctness, Helpfulness, Faithfulness

scorers = [
    Correctness(),
    Helpfulness(model="openai/gpt-4o"),
    Faithfulness(context_fields=["retrieved_chunks"]),
]
```

All presets accept an optional `model` (default `openai/gpt-4o-mini`), `temperature` (default `0.0`), `threshold` (default `0.7`), and `include_input`. See [Batch eval](/docs/improve/batch-eval.md) for full SDK usage.

---

## Custom scorers

When built-ins can't express your check, write a **custom scorer** — user code that receives the eval context and returns a result. Custom scorers are components: they register with your worker and deploy with your code.

Python:

```python
from agnt5.eval import scorer, EvalContext, ScorerResult

@scorer(name="cites_order_id", description="Reply must cite the order ID from the input")
def cites_order_id(ctx: EvalContext) -> ScorerResult:
    order_id = ctx.input.get("order_id", "")
    cited = order_id in str(ctx.output)
    return ScorerResult(
        score=1.0 if cited else 0.0,
        passed=cited,
        explanation=f"Order ID {order_id} {'found' if cited else 'missing'} in reply",
    )
```

The `EvalContext` carries `input`, `output`, `expected`, `run_id`, `trace_id`, and `events` (trace events for trace-level scorers, declared with `scope="trace"`).

TypeScript:

```typescript
const citesOrderId = scorer("cites_order_id", "Reply must cite the order ID from the input")(
  async (ctx, request) => {
    const orderId = (request.input as { order_id?: string }).order_id ?? "";
    const cited = String(request.output).includes(orderId);
    return new ScorerResult({ score: cited ? 1 : 0, passed: cited });
  },
);
```

Custom scorers register with the worker like any other component — auto-registration picks up decorated scorers, or pass them explicitly via the worker's `scorers` list. After [deploying](/docs/run/deploying.md), the scorer appears in Studio under **Evaluate** -> **Scorers**. Attach it to an experiment by ID:

```bash
agnt5 experiments create ... --scorer-id <scorer-id>
```

---

## Trace assertions in the SDK

For glassbox testing — asserting on execution behavior rather than output content — the SDK provides `TraceAssertion` and `trace_scorer()`. These are used inside custom scorers or directly in [batch eval](/docs/improve/batch-eval.md) code; they do not map to CLI scorer names.

Python:

```python
from agnt5.eval import TraceAssertion, trace_scorer, EvalContext, ScorerResult
from agnt5 import scorer

@scorer(name="efficiency_check", scope="trace")
def efficiency_check(ctx: EvalContext) -> ScorerResult:
    assertions = [
        TraceAssertion.max_tokens(2000),
        TraceAssertion.max_lm_calls(4),
        TraceAssertion.no_errors(),
        TraceAssertion.duration_under(15000),
    ]
    result = trace_scorer(ctx.events, assertions)
    return ScorerResult(
        score=result.score,
        passed=result.passed,
        explanation=result.explanation,
    )
```

TypeScript:

```typescript
const efficiencyCheck = scorer("efficiency_check", "Checks token use, LLM calls, and duration", "trace")(
  async (ctx, request) => {
    const result = traceScorer(request.trace ?? [], [
      TraceAssertion.maxTokens(2000),
      TraceAssertion.maxLmCalls(4),
      TraceAssertion.noErrors(),
      TraceAssertion.durationUnder(15000),
    ]);
    return { score: result.score, passed: result.passed, explanation: result.explanation };
  },
);
```

Available assertions:

| Method | Asserts |
|---|---|
| `max_tokens(n)` / `maxTokens(n)` | Total LLM tokens ≤ n |
| `max_lm_calls(n)` / `maxLmCalls(n)` | LLM call count ≤ n |
| `no_errors()` / `noErrors()` | No error events in the trace |
| `duration_under(ms)` / `durationUnder(ms)` | Execution duration < ms |
| `event_sequence([...])` / `eventSequence([...])` | Named events appear in order |
| `step_memoized(name)` / `stepMemoized(name)` | Step was served from cache |
| `event_count(type, min)` / `eventCount(type, min)` | Event type appeared ≥ min times |

`trace_scorer()` returns a score equal to the proportion of assertions that passed, plus a combined explanation.

---

## Inspect scores

Every scorer execution produces a **score** record with evidence — the inputs the scorer saw and why it decided what it decided.

```bash
# All scores for an experiment run
agnt5 scores list --run-id <run-id>

# Scores for a specific run item
agnt5 scores list --run-id <run-id> --run-item-id <item-id>

# Scores produced by a specific scorer
agnt5 scores list --scorer-id <scorer-id>

# Scores from the last 2 hours for a component
agnt5 scores list --component-name support_agent --since 2h

# Live production scores (for online evals)
agnt5 scores list --root-run-id <root-run-id>
agnt5 scores list --session-id <session-id>

# Show evidence for one score — scorer input, output, and reasoning
agnt5 scores evidence <score-id> --include scorer_input,scorer_output,evidence
```

Available filters on `scores list`:

| Flag | Filters by |
|---|---|
| `--run-id` | Experiment run UUID |
| `--run-item-id` | Specific experiment run item UUID |
| `--scorer-id` | Scorer UUID |
| `--scorer-version-id` | Specific scorer version UUID |
| `--subject-type` | Subject type (e.g. `experiment_run_item`, `span`, `session`) |
| `--subject-id` | Subject UUID |
| `--session-id` | Runtime session ID |
| `--root-run-id` | Root runtime run ID |
| `--component-name` | Component name |
| `--component-type` | Component type |
| `--since` | Scores created at or after (RFC3339 or Unix timestamp) |
| `--until` | Scores created at or before (RFC3339 or Unix timestamp) |

In Studio, open **Evaluate** -> **Experiments**, select a run, and click into any item to see its per-scorer results and evidence.


**Scorer classes**: built-in deterministic (SDK-core owned, no registration), built-in LLM-as-judge (`llm_judge`, `correctness`, `faithfulness`; configurable model/prompt/rubric), custom (user components, require worker registration + deployment).
**Built-in deterministic names**: `exact_match`, `contains`, `regex_match`, `json_valid`, `json_schema`, `numeric_range`, `levenshtein`, `structured_assertions`, `tool_called`, `tool_not_called`, `tool_sequence`, `tool_sequence_in_order`, `tool_sequence_exact`, `tool_sequence_any_order`, `tool_trajectory`, `tool_params_match`, `max_tool_calls`, `max_llm_calls`, `max_tokens`, `duration_under`, `no_errors`, `state_equals`.
**SDK evaluator presets** (wrap `llm_judge` or named built-ins): `Correctness`, `Faithfulness`, `Helpfulness`, `Coherence`, `Conciseness`, `ResponseRelevance`, `InstructionFollowing`, `GoalSuccess`, `Refusal`, `Harmfulness`, `Stereotyping`.
**TraceAssertion** (glassbox, used inside custom scorers with `scope="trace"`): `max_tokens`, `max_lm_calls`, `no_errors`, `duration_under`, `event_sequence`, `step_memoized`, `event_count`; composed with `trace_scorer()`.
**Result shape**: `{score: 0.0–1.0, passed: bool, label?: string, explanation?: string, metadata?: object}`.
**Code primitives**: `@scorer(name, description, scope)` decorator + `EvalContext` -> `ScorerResult` (Python); `scorer(name, description, scope)(handler)` (TypeScript).
**Errors**: built-ins fail with typed scorer errors (`input_error`, `config_error`, `provider_error`, `auth_error`, `artifact_error`, `timeout_error`); only custom scorers can return `scorer_not_found`.


## Next steps

* [Experiments](/docs/improve/experiments.md): attach scorers to an experiment and run them against a dataset version.
* [Batch eval](/docs/improve/batch-eval.md): run scorers from code using `client.eval()` or `client.batch_eval()`.
* [Datasets](/docs/improve/datasets.md): curate the items your scorers grade, including trace events for trace scorers.
* [Agents](/docs/build/agents.md): structure agent tool use so trace assertions have meaningful events to check.


# install-cli

---

## Install the CLI

_Source: https://agnt5.com/docs/install-cli.md_

> Install the AGNT5 CLI, verify it, and authenticate with your account.

The `agnt5` CLI scaffolds projects, runs `agnt5 dev` against AGNT5 from your laptop, and ships projects to managed environments.

**Prerequisites:**

- macOS (Apple Silicon or Intel), Linux (x86_64 or ARM64), or Windows via WSL2. Native Windows binaries are not yet shipped.
- An AGNT5 account. Sign up at [app.agnt5.com](https://app.agnt5.com).

<details>
<summary><strong>Set up with an AI coding assistant</strong> — paste this prompt into Claude Code, Cursor, Copilot, etc.</summary>

The assistant will run the install end-to-end. Use this if you'd rather have an AI driver handle the steps below.



**Setup prompt:**

```text
Help me install the AGNT5 CLI.

What to do:

1. I need an AGNT5 account. If I don't have one, point me to https://app.agnt5.com to sign up. Wait for me to confirm.
2. Install the AGNT5 CLI: curl -LsSf https://agnt5.com/cli.sh | bash
3. Run ~/.agnt5/bin/agnt5 version and confirm the output names a version, Go toolchain, and platform. Use the absolute path; the current shell has not reloaded yet, so plain "agnt5" will not be on PATH in this session.
4. Run ~/.agnt5/bin/agnt5 auth login and wait for me to complete browser auth.
5. Run ~/.agnt5/bin/agnt5 auth status and confirm I am signed in.
6. Tell me to open a new terminal so future agnt5 commands resolve from PATH without the ~/.agnt5/bin/ prefix.
7. When done, point me to https://docs.agnt5.com/docs/quickstart for the next step.

Critical rules:

- DO NOT run agnt5 create or scaffold a project. Project scaffolding belongs in the quickstart, not the install.
- The current shell does NOT pick up the new PATH automatically. The installer wrote the PATH line into ~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish, but those changes only apply to new shells. In this session, always invoke ~/.agnt5/bin/agnt5 with the absolute path. Do not edit the rc file as a "fix" — it is already correct.
- If agnt5 version still fails after using the absolute path, the binary did not download. Re-run the curl install and check the output for errors before debugging PATH.
```



</details>

## Step 1: Install




**curl (macOS, Linux, WSL2):**

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




**Homebrew (macOS only):**

```bash
brew install agnt5/tap/agnt5
```




The installer writes `agnt5` to `~/.agnt5/bin` and appends that directory to your shell's `PATH`. Open a new terminal, or reload the current shell:

```bash
source ~/.zshrc                    # zsh
source ~/.bashrc                   # bash
source ~/.config/fish/config.fish  # fish
```

## Step 2: Verify

```bash
agnt5 version
```

Expected output (version numbers will vary):

```
agnt5-cli version v1.x.x
  - Go version: go1.25.x
  - Platform: darwin/arm64
```

## Step 3: Authenticate

Sign in via OAuth in your browser:

```bash
agnt5 auth login
```

The CLI opens your default browser, completes the PropelAuth flow, and writes the issued API key to `~/.agnt5/config.yaml`. Confirm:

```bash
agnt5 auth status
```

The output names the authenticated user, the active environment, and the API base URL.

For CI or non-interactive environments, pass an API key directly or set `AGNT5_API_KEY` in the environment:

```bash
agnt5 auth login --api-key agnt5_sk_...
# or
export AGNT5_API_KEY=agnt5_sk_...
```

API keys are issued during the OAuth flow above, or generated in [app.agnt5.com](https://app.agnt5.com) account settings. See the [auth command reference](/cli/auth.md) for `agnt5 auth logout` and the full flag list.

## Troubleshooting

**`command not found: agnt5`** — your shell hasn't picked up the new `PATH` entry. Confirm `~/.agnt5/bin` is on `PATH`:

```bash
echo $PATH | tr ':' '\n' | grep agnt5
```

If nothing prints, add this line to your shell config and reload:

```bash
export PATH="$HOME/.agnt5/bin:$PATH"   # bash, zsh
# fish:
fish_add_path "$HOME/.agnt5/bin"
```

**`agnt5 version` still fails after fixing `PATH`** — the binary did not download. Re-run the install command and check its output for errors before further `PATH` debugging.

**Authentication errors after running `agnt5 dev` or `agnt5 deploy`** — re-authenticate with `agnt5 auth login`. If you switched accounts or contexts, run `agnt5 auth logout` first.

## Next steps

- **[Quickstart](/docs/quickstart.md)** — build and run the Hacker News digest workflow.
- **[CLI Reference](/cli)** — every command and flag.


# Integrations

---

## AI providers

_Source: https://agnt5.com/docs/integrations/ai-providers.md_

> Connect model API keys in Studio, then call provider-prefixed models from agents, prompts, and low-level generation code.

An **AI provider** integration stores the API key AGNT5 uses when your agents and prompts call a model API. You name models with a `"provider/model"` string, for example `"openai/gpt-4o-mini"` or `"anthropic/claude-3-5-sonnet-20241022"`. In managed deployments, configure provider keys in Studio so workers can resolve credentials without putting secrets in source code.

## Supported providers

Studio exposes these AI provider integrations for project and workspace configuration:

| Provider | Model prefix | API key env var |
|---|---|---|
| OpenAI | `openai` | `OPENAI_API_KEY` |
| Anthropic | `anthropic` | `ANTHROPIC_API_KEY` |
| Google AI | `google` or `gemini` | `GOOGLE_API_KEY` or `GEMINI_API_KEY` |
| Groq | `groq` | `GROQ_API_KEY` |
| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` |
| Mistral AI | `mistral` | `MISTRAL_API_KEY` |
| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` |
| xAI | `xai` | `XAI_API_KEY` |

The Python and TypeScript SDKs also understand additional provider prefixes for local or advanced use, including `azure`, `bedrock`, `ollama`, `huggingface`, and `hf`. Those providers are not all exposed as first-class Studio integrations yet, so use ordinary environment configuration when you use them outside the Studio integration catalog.

## Configure credentials

For local development, set the provider API key before your worker starts:

```bash
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export GOOGLE_API_KEY=...
export GROQ_API_KEY=...
export OPENROUTER_API_KEY=...
export MISTRAL_API_KEY=...
export DEEPSEEK_API_KEY=...
export XAI_API_KEY=...
```

For deployed workers, store provider keys in Studio:

1. Open your project in Studio.
2. Open **Settings** -> **Integrations**.
3. Add the provider integration and paste the API key.
4. Choose the narrowest scope that works: workspace, project, or environment-specific secret.

<DocsImage
  src="/docs/integrations/integrations-light.png"
  darkSrc="/docs/integrations/integrations-dark.png"
  alt="Screenshot of the AGNT5 Studio Settings → Integrations page showing configured AI provider integrations."
  caption="Studio Settings → Integrations — add a provider key and choose its scope."
  width={1682}
  height={1060}
/>

Your code should not pass raw provider keys. AGNT5 injects the credential into the worker environment or resolves it through the managed credential path at runtime.

## Use a provider in an agent

Create an agent with a provider-prefixed model string. To change providers, change the model string and make sure the matching credential is configured.

```python
from agnt5 import Agent

agent = Agent(
    name="summarizer",
    model="openai/gpt-4o-mini",
    instructions="Summarize articles into three concise bullet points.",
)

result = await agent.run("Summarize the product launch notes.")
print(result.output)
```

The same pattern works with another provider:

```python
from agnt5 import Agent

agent = Agent(
    name="summarizer",
    model="anthropic/claude-3-5-sonnet-20241022",
    instructions="Summarize articles into three concise bullet points.",
)
```

## Generate without an agent

Use the low-level `lm.generate()` API when you need one model call instead of an agent loop:

```python
from agnt5 import lm

response = await lm.generate(
    model="openai/gpt-4o-mini",
    prompt="Write a one-paragraph incident summary for a resolved API outage.",
)

print(response.text)
```

The `model` value still uses the same `"provider/model"` format, and the provider key still comes from the environment or the configured integration.

## Provider-hosted tools

Provider-hosted tools run on the model provider's infrastructure. AGNT5 sends the tool request to the provider and records the result in the model response; your worker does not execute local tool code for these calls.

```python
from agnt5 import Agent
from agnt5.lm import BuiltInTool

agent = Agent(
    name="researcher",
    model="openai/gpt-4o-mini",
    instructions="Use web search for current facts before answering.",
    built_in_tools=[BuiltInTool.WEB_SEARCH],
)

result = await agent.run("What changed in the latest product release?")
print(result.output)
```

| Tool | What it does | Providers |
|---|---|---|
| `BuiltInTool.WEB_SEARCH` | Live web search with provider-returned results | OpenAI, Anthropic, Google |
| `BuiltInTool.CODE_INTERPRETER` | Run code in a provider-hosted sandbox | OpenAI |
| `BuiltInTool.FILE_SEARCH` | Search files hosted by the provider | OpenAI |
| `BuiltInTool.WEB_FETCH` | Fetch the content of a specific URL | Anthropic |

You can mix provider-hosted tools with AGNT5 custom tools on the same agent. See [Tools](/docs/build/tools.md) for custom tools, sandbox workspaces, and human-in-the-loop tools.

## Next steps

- [Agents](/docs/build/agents.md): configure model-backed reasoning loops.
- [Prompts](/docs/build/prompts.md): run managed prompts with provider-backed models.
- [Tools](/docs/build/tools.md): add custom, sandbox, and provider-hosted capabilities.
- [Deploying](/docs/run/deploying.md): deploy workers with integrations and secrets configured.

---

## Event sources

_Source: https://agnt5.com/docs/integrations/event-sources/overview.md_

> Connect Sentry, Stripe, GitHub, Slack, or any Standard Webhooks publisher so their events trigger your AGNT5 workflows.

An **event source** is a third-party service that emits events AGNT5 turns into workflow triggers. Each one delivers events over a signed webhook: you store the provider's signing secret once, then [declare a trigger](/docs/build/webhooks.md#declare-a-trigger) on any workflow that should run when an event arrives.

If you control the sending side, point any Standard Webhooks publisher straight at AGNT5 — see [Webhooks](/docs/build/webhooks.md). The pages here cover the providers that sign their deliveries their own way.

---

## Supported sources

| Source | Emits | Signing secret |
|---|---|---|
| Standard Webhooks | Anything you publish | AGNT5-generated — copy in |
| [Slack](/docs/integrations/event-sources/slack.md) | Events API callbacks | Provider-issued — paste |
| [GitHub](/docs/integrations/event-sources/github.md) | Repository and workflow events | AGNT5-generated — copy in |
| [Stripe](/docs/integrations/event-sources/stripe.md) | Payment and billing events | Provider-issued — paste |
| [Sentry](/docs/integrations/event-sources/sentry.md) | Issue and error alerts | Provider-issued — paste |





---

## The shape of every setup

Connecting any event source follows the same four steps:

1. **Create the integration** in Studio → Integrations and choose the target environment.
2. **Store the signing secret** — generate one in AGNT5 (GitHub, Standard Webhooks) or paste the one the provider issues (Sentry, Stripe, Slack).
3. **Copy the webhook URL** (`…/v1/webhooks/{source}/{integration_id}`) into the provider's webhook settings.
4. **Declare a trigger** on your workflow with `webhook("{source}", event="…")`.

The per-provider pages cover only what differs at steps 2 and 3 — where to find the secret, where to paste the URL, and which events the source emits. Steps 1 and 4, along with [signature verification](/docs/build/webhooks.md#signature-verification) and [delivery semantics](/docs/build/webhooks.md#delivery-semantics), are identical everywhere and live in [Webhooks](/docs/build/webhooks.md).

---

## Related

- [Webhooks](/docs/build/webhooks.md) — the trigger mechanism, end to end
- [Integrations](/docs/integrations/overview.md) — how credentials are stored and scoped

---

## Sentry

_Source: https://agnt5.com/docs/integrations/event-sources/sentry.md_

> Start AGNT5 workflows automatically from Sentry issues, errors, and comments.

Connect Sentry to AGNT5 and your workflows will start automatically whenever an issue, error, or comment event fires. Every delivery is signature-verified before any workflow runs.

---

## Setup

### 1. Create the integration in Studio

1. Go to **Settings → Integrations** and click **Add Integration**.
2. Pick **Sentry**.
3. Fill in a name for the integration.
4. Choose the environment that should receive triggers.

<DocsImage
  src="/docs/integrations/sentry-integration-light.png"
  darkSrc="/docs/integrations/sentry-integration-dark.png"
  alt="Studio New Sentry Webhook panel showing Name, Environment, Webhook URL, and Signing Secret fields."
  caption="Fill in the name, select the environment, copy the webhook URL, and paste the signing secret from Sentry."
  width={1746}
  height={1060}
/>

### 2. Create an integration in Sentry

1. Go to [**Settings → Integrations → Custom Integrations**](https://agnt5.sentry.io/settings/developer-settings/) and click **Create New Integration**.
2. Fill in the required details and paste the webhook URL from AGNT5 Studio.
3. Under **Permissions**, configure access for each resource. For example:

   <Callout type="info">
   | Permission | Value |
   |---|---|
   | Project | Read |
   | Team | Read |
   | Release | No Access |
   | Distribution | No Access |
   | Issue & Event | Read |
   | Organization | Read |
   | Member | Read |
   | Alerts | No Access |
   </Callout>

4. Under **Webhooks**, check the event types you want to trigger workflows. For example:

   <Callout type="info">
   issue, error, comment, seer, preprod_artifact
   </Callout>
5. Click **Save Changes**.
6. Copy the **Client Secret** and paste it into the **Signing secret** field in Studio.

_[screenshot: Sentry Custom Integrations page with the Create New Integration button and the Client Secret field highlighted]_

---

## Events

Each Sentry event has a name in the format `sentry.<resource>.<action>`. Pass this name to `event()` in your workflow trigger.

| Resource | Action | Full event name |
|---|---|---|
| `issue` | `created` | `sentry.issue.created` |
| `issue` | `resolved` | `sentry.issue.resolved` |
| `issue` | `assigned` | `sentry.issue.assigned` |
| `issue` | `ignored` | `sentry.issue.ignored` |
| `error` | `created` | `sentry.error.created` |
| `comment` | `created` | `sentry.comment.created` |

---

## Workflow examples

### Issue events

Workflows receive the webhook envelope as keyword arguments (`**envelope`). The `body` field is the raw verified request body. It may arrive as a JSON string or an already-parsed dict, so parse defensively.

```python
import json
from agnt5 import WorkflowContext, workflow
from agnt5.types import event


def _parse_body(envelope: dict) -> dict:
    body = envelope.get("body", {})
    if isinstance(body, str):
        try:
            body = json.loads(body)
        except json.JSONDecodeError:
            return {}
    return body if isinstance(body, dict) else {}


@workflow(
    name="triage_sentry_issue",
    triggers=[event("sentry.issue.created")],
)
async def triage_sentry_issue(ctx: WorkflowContext, **envelope) -> dict:
    body = _parse_body(envelope)
    issue = body.get("data", {}).get("issue", {})

    ctx.logger.info(
        "Sentry issue.created: %s (level=%s)"
        % (issue.get("title", "unknown"), issue.get("level", "unknown"))
    )

    # add your triage logic here, e.g. open a ticket, page on-call
    return {
        "issue_id": issue.get("id"),
        "title": issue.get("title"),
        "level": issue.get("level"),
        "event_type": envelope.get("event_type"),
    }
```

### Comment events

Comment payloads nest the comment text several levels deep. Extract defensively:

```python
@workflow(
    name="log_sentry_comment",
    triggers=[event("sentry.comment.created")],
)
async def log_sentry_comment(ctx: WorkflowContext, **envelope) -> dict:
    body = _parse_body(envelope)
    data = body.get("data", {})
    comment = data.get("comment") or body.get("comment") or {}
    issue = data.get("issue") or body.get("issue") or {}
    actor = body.get("actor") or {}
    user = comment.get("user") or comment.get("author") or {}

    author = (
        comment.get("author_name")
        or user.get("name")
        or actor.get("name")
        or "unknown"
    )
    text = (
        comment.get("text")
        or comment.get("message")
        or data.get("text")
        or ""
    )

    ctx.logger.info(
        "Sentry comment from %s on %s: %s"
        % (author, issue.get("short_id", "unknown"), text[:200])
    )
    return {"author": author, "issue": issue.get("short_id"), "comment": text}
```

### Viewing triggered runs in Studio

After a Sentry event fires, the run appears in **Studio → Runs** within seconds. Open the run to see the envelope inputs and workflow output in the trace.

_[screenshot: Studio Runs list showing a completed triage_sentry_issue run, with the run detail open showing the sentry.issue.created event_type and the workflow output]_

---

## Envelope structure

Every Sentry-triggered run receives this envelope as `**envelope`:

```json
{
  "_webhook": true,
  "source": "sentry",
  "integration_id": "int_abc123",
  "event_type": "sentry.issue.created",
  "idempotency_key": "req_9f3c…",
  "timestamp": 1733337600,
  "headers": { "sentry-hook-resource": "issue", "request-id": "req_9f3c…" },
  "body": "{\"action\":\"created\",\"data\":{\"issue\":{…}}}"
}
```

`body` is the raw signature-verified request body. Parse it with `json.loads` before use.

---

## Signature verification

- Every delivery is verified using `sentry-hook-signature` before any workflow runs.
- Requests with an invalid or missing signature are rejected with `401`.

---

## Delivery semantics

- Sentry retries failed deliveries automatically.
- AGNT5 deduplicates using the `Request-ID` header.
- A retry replays the original run instead of starting a new one.

---

## Related

- [Event sources overview](/docs/integrations/event-sources/overview.md)
- [Webhooks](/docs/build/webhooks.md): trigger mechanism, signature verification, and delivery semantics
- [Workflows](/docs/build/workflows.md): how to write and run workflows

---

## Slack

_Source: https://agnt5.com/docs/integrations/event-sources/slack.md_

> Start AGNT5 workflows automatically from Slack messages, mentions, and reactions using the Slack Events API.

Connect Slack to AGNT5 and your workflows will start automatically whenever a Slack event fires. Every delivery is signature-verified before any workflow runs.

---

## Setup

### 1. Create the integration in Studio

1. Go to **Settings → Integrations** and click **Add Integration**.
2. Pick **Slack**.
3. Studio walks you through creating the Slack app and choosing the target environment.

<DocsImage
  src="/docs/integrations/slack-integration-light.png"
  darkSrc="/docs/integrations/slack-integration-dark.png"
  alt="Studio Add Slack App panel showing app name, OAuth scopes, and bot events configuration."
  caption="Enter an app name, select the OAuth scopes and bot events you need, then click Create Slack App."
  width={1746}
  height={1060}
/>

### 2. Copy the app credentials from Slack

Go to **Basic Information → App Credentials** and copy the following values

<Callout type="info">
| Field | Used for |
|---|---|
| **App ID** | Identifying your Slack app |
| **Client ID** | Identifies your app during OAuth authorization; included in the redirect URL when requesting user permissions |
| **Client Secret** | Paired with Client ID to exchange an authorization code for an access token, keep this server-side and never expose it publicly |
| **Signing Secret** | AGNT5 webhook verification (required) |
</Callout>

Paste each value into the required fields in Studio when prompted.


### 3. Complete the setup in Studio

Paste the credentials into the required fields and save. Studio registers the webhook URL automatically.

---

## Events

The event name your trigger matches is `slack.<event_type>`, where `event_type` is the value of the Slack `event.type` field inside the payload.

| Event | Full event name | Required scope |
|---|---|---|
| `app_mention` | `slack.app_mention` | `app_mentions:read` |
| `message` (channels) | `slack.message` | `channels:history` |
| `message` (groups) | `slack.message` | `groups:history` |
| `message` (DMs) | `slack.message` | `im:history` |
| `reaction_added` | `slack.reaction_added` | `reactions:read` |
| `reaction_removed` | `slack.reaction_removed` | `reactions:read` |
| `member_joined_channel` | `slack.member_joined_channel` | `channels:read` |

A single workflow can subscribe to multiple event types at once by passing multiple `event()` calls in `triggers`.

---

## Workflow examples

### Logging messages and mentions

1. Workflows receive the envelope as `**envelope`.
2. Subscribe to both `slack.message` and `slack.app_mention` to cover channels and mentions in one workflow.
3. `body` may be a JSON string or a dict, so parse defensively.
4. Filter out bot messages (`bot_id`, `subtype`) to avoid reply loops.

```python
import json
from agnt5 import WorkflowContext, workflow
from agnt5.types import event


def _parse_body(envelope: dict) -> dict:
    body = envelope.get("body", {})
    if isinstance(body, str):
        try:
            body = json.loads(body)
        except json.JSONDecodeError:
            return {}
    return body if isinstance(body, dict) else {}


@workflow(
    name="slack_message_logger",
    triggers=[event("slack.message"), event("slack.app_mention")],
)
async def slack_message_logger(ctx: WorkflowContext, **envelope) -> dict:
    body = _parse_body(envelope)
    slack_event = body.get("event", {})

    # skip bot messages to avoid reply loops
    if slack_event.get("bot_id") or slack_event.get("subtype"):
        ctx.logger.info("Slack message skipped: bot or unsupported subtype")
        return {"status": "skipped"}

    user = slack_event.get("user", "unknown")
    text = slack_event.get("text", "")
    channel = slack_event.get("channel", "")

    ctx.logger.info("Slack message from %s in %s: %s" % (user, channel, text[:200]))

    # add your processing logic here, e.g. call an agent, look up data
    return {"status": "logged", "user": user, "channel": channel, "text": text}
```

### Viewing triggered runs in Studio

After a Slack event fires, the run appears in **Studio → Runs** within seconds. Open it to inspect the envelope, extracted fields, and any reply output.

_[screenshot: Studio Runs list showing a completed slack_message_logger run triggered by a slack.app_mention event, with the run detail open showing the event body and workflow output]_

---

## Envelope structure

Every Slack-triggered run receives this envelope as `**envelope`:

```json
{
  "_webhook": true,
  "source": "slack",
  "integration_id": "int_abc123",
  "event_type": "slack.app_mention",
  "timestamp": 1733337600,
  "headers": { "x-slack-signature": "v0=…", "x-slack-request-timestamp": "…" },
  "body": "{\"type\":\"event_callback\",\"event\":{\"type\":\"app_mention\",\"user\":\"U123\",\"text\":\"<@U456> hello\",\"channel\":\"C789\",\"ts\":\"…\"}}"
}
```

`body` is the raw verified request body. Parse it with `json.loads`. Slack does not include an `idempotency_key` (see [Delivery semantics](#delivery-semantics)).

---

## Signature verification

- Uses `X-Slack-Signature` (`v0=<hex>`) with `X-Slack-Request-Timestamp`.
- 5-minute replay window enforced.
- Requests with an invalid or expired signature are rejected with `401`.

---

## Delivery semantics

- Slack retries up to 3 times on non-2xx responses.
- **Retries are not deduplicated.** Slack provides no stable per-delivery id.
- Make your workflow idempotent using an id from the event body (e.g. `event.client_msg_id`).

---

## Related

- [Event sources overview](/docs/integrations/event-sources/overview.md)
- [Webhooks](/docs/build/webhooks.md): trigger mechanism, signature verification, and delivery semantics
- [Workflows](/docs/build/workflows.md): how to write and run workflows

---

## Integrations

_Source: https://agnt5.com/docs/integrations/overview.md_

> Connect AGNT5 to external services - model providers, event sources, and more - with credentials stored once and scoped to a workspace, project, or environment.

An **integration** connects AGNT5 to an external service and holds the credentials that connection needs. You configure each integration once in Studio; your agents, prompts, and workflows then use it without handling secrets in code.

Integrations fall into these families today:

- **[AI providers](/docs/integrations/ai-providers.md)** - model APIs your agents and prompts call: OpenAI, Anthropic, Google, Groq, OpenRouter, Mistral, DeepSeek, and xAI. The credential is an **API key**.
- **[Sandbox providers](/docs/integrations/sandbox-providers.md)** - isolated code execution providers your agents use through `Sandbox()`: E2B, Daytona, Vercel, Northflank, and Together. The credential is an **API key** or provider token.
- **[Event sources](/docs/integrations/event-sources/overview.md)** - third-party services that trigger your workflows over webhooks: Sentry, Stripe, GitHub, Slack, and any Standard Webhooks publisher. The credential is a **signing secret**.

---

## How an integration is stored

Every integration is a **provider** plus one or more **secrets**:

- **Provider** - which service it connects (for example `openai` or `sentry`).
- **Secret role** - what the credential is for. `api_key` calls a provider's API; `webhook_secret` verifies the signature on an inbound webhook.

Secrets are stored encrypted and decrypted only at the point of use: the gateway fetches a `webhook_secret` to verify a delivery, and a worker receives an `api_key` as an environment variable when it deploys. Your code never sees the raw secret material.

---

## Scope

An integration applies at the scope you create it in:

- **Workspace** — available to every project in the workspace.
- **Project** — available to a single project.

A secret can additionally be pinned to one **environment**, so a production key can differ from staging. Choose the narrowest scope that works: a production billing secret belongs on the project or environment, not the whole workspace.

---

## Manage integrations

In Studio, open **Integrations** to add, view, and remove integrations and their secrets. Adding one has the same shape regardless of category: pick the provider, choose the scope, and supply the credential.

<DocsImage
  src="/docs/integrations/configure-light.png"
  darkSrc="/docs/integrations/configure-dark.png"
  alt="Screenshot of the AGNT5 Studio Integrations page. The page shows a search field, display control, add integration button, and configured integrations grouped by provider type and connection status."
  caption="Studio shows configured integrations with provider type and connection status before you add or edit a credential."
  width={1008}
  height={639}
/>

What that credential is, and where you get it, depends on the category — follow the guide for [AI providers](/docs/integrations/ai-providers.md), [sandbox providers](/docs/integrations/sandbox-providers.md), or [event sources](/docs/integrations/event-sources/overview.md).

---

## Related

- [AI providers](/docs/integrations/ai-providers.md): connect model APIs for agents and prompts.
- [Sandbox providers](/docs/integrations/sandbox-providers.md): connect isolated code execution providers for agents.
- [Event sources](/docs/integrations/event-sources/overview.md): connect Sentry, Stripe, GitHub, and Slack.
- [Webhooks](/docs/build/webhooks.md): trigger workflows from inbound events.

---

## Sandbox providers

_Source: https://agnt5.com/docs/integrations/sandbox-providers.md_

> Configure sandbox provider credentials for isolated agent code execution.

A **sandbox provider** creates the isolated workspace used by `Sandbox()` in the SDK. AGNT5 keeps the agent API provider-neutral, so your code can use `Sandbox()` or select a provider by name while credentials stay in the worker environment or Studio integration configuration.

## Supported providers

Use these provider names with `Sandbox(provider=...)` in Python or `new Sandbox({ provider: ... })` in TypeScript.

| Provider | Selector | Required environment variables |
|---|---|---|
| E2B | `e2b` | `E2B_API_KEY` |
| Daytona | `daytona` | `DAYTONA_API_KEY` |
| Vercel Sandbox | `vercel` | `VERCEL_TOKEN` or `VERCEL_OIDC_TOKEN`, plus `VERCEL_TEAM_ID` and `VERCEL_PROJECT_ID` |
| Northflank | `northflank` | `NORTHFLANK_API_TOKEN` and `NORTHFLANK_PROJECT_ID` |
| Together Code Interpreter | `together` | `TOGETHER_API_KEY` |

`Sandbox()` auto-detects the first configured provider. Use an explicit selector when more than one provider is configured.

## Configure local credentials

For local development, put sandbox credentials in `.env` and start the worker with `agnt5 --env-file .env dev`.

```bash
# Choose one provider for local testing.
AGNT5_SANDBOX_PROVIDER=e2b
E2B_API_KEY=e2b_...
```

For Daytona:

```bash
AGNT5_SANDBOX_PROVIDER=daytona
DAYTONA_API_KEY=...
```

For Vercel Sandbox:

```bash
AGNT5_SANDBOX_PROVIDER=vercel
VERCEL_TOKEN=...
VERCEL_TEAM_ID=team_...
VERCEL_PROJECT_ID=prj_...
```

For Northflank:

```bash
AGNT5_SANDBOX_PROVIDER=northflank
NORTHFLANK_API_TOKEN=...
NORTHFLANK_PROJECT_ID=...
```

For Together Code Interpreter:

```bash
AGNT5_SANDBOX_PROVIDER=together
TOGETHER_API_KEY=...
```

Do not commit `.env`. The worker reads these variables when it starts.

## Select a provider in code

Use `Sandbox()` when one provider is configured. Pass a provider name when you want to route a specific agent to a specific backend.



**Python:**

```python
from agnt5 import Agent, Sandbox

agent = Agent(
    name="coder",
    model="openai/gpt-4o-mini",
    instructions="Use the configured sandbox provider.",
    sandbox=Sandbox(),
)

daytona_agent = Agent(
    name="daytona_coder",
    model="openai/gpt-4o-mini",
    instructions="Use Daytona for this task.",
    sandbox=Sandbox(provider="daytona"),
)
```





**TypeScript:**

```ts
const agent = new Agent({
  name: 'coder',
  model: LM.openai(),
  modelName: 'openai/gpt-4o-mini',
  instructions: 'Use the configured sandbox provider.',
  sandbox: new Sandbox(),
});

const daytonaAgent = new Agent({
  name: 'daytona-coder',
  model: LM.openai(),
  modelName: 'openai/gpt-4o-mini',
  instructions: 'Use Daytona for this task.',
  sandbox: new Sandbox({ provider: 'daytona' }),
});
```



## Configure deployed workers

In managed deployments, configure sandbox provider credentials in Studio so workers receive the required environment variables without storing secrets in source code.

1. Open your project in Studio.
2. Open **Settings** -> **Integrations**.
3. Add the sandbox provider integration.
4. Store the provider credential at the narrowest scope that works for the worker.
5. Deploy or restart the worker so the updated environment is available.

Provider credentials are not shown to the model. The agent receives sandbox capabilities; the SDK and worker use the provider credential to create and manage the sandbox.

## Validate a provider

Use the `sandbox-smoke` template to verify provider credentials from a worker before you rely on the provider in an agent.

```bash
agnt5 create --template python/sandbox-smoke sandbox-smoke
cd sandbox-smoke
cp .env.example .env
agnt5 --env-file .env dev
```

Run the lifecycle check:

```bash
agnt5 --env-file .env run sandbox_lifecycle_check \
  --input '{"provider": "e2b", "code": "print(6 * 7)", "language": "python"}'
```

Run the file and execution check:

```bash
agnt5 --env-file .env run sandbox_agent_tools_check \
  --input '{"provider": "e2b"}'
```

For a real agent loop, run:

```bash
agnt5 --env-file .env run sandbox_coding_agent_check \
  --input '{"provider": "e2b", "model": "openai/gpt-4o-mini"}'
```

## Troubleshoot

| Symptom | What to check |
|---|---|
| `Sandbox provider 'auto' is not configured` | The worker did not receive any supported provider environment variables. Restart with `agnt5 --env-file .env dev` or update the deployed worker environment. |
| Provider creation fails | Confirm the provider key is valid and the provider account has sandbox access enabled. |
| File operations fail but code execution works | Run `sandbox_agent_tools_check` to isolate write, list, read, and execute behavior. |
| Shutdown does not complete | Check provider-side quota, active sandbox limits, and provider API status. |

## Next steps

- [Use sandboxes with agents](/docs/build/sandboxes.md): attach a sandbox to an agent and use it from custom tools.
- [AI providers](/docs/integrations/ai-providers.md): configure model credentials for agents and prompts.
- [Local development](/docs/build/local-development.md): run workers with explicit environment files.
- [Deploying](/docs/run/deploying.md): deploy workers after integrations are configured.


# learning-path

---

## AGNT5 learning path

_Source: https://agnt5.com/docs/learning-path.md_

> Follow a practical sequence from your first local workflow to deployment, operations, and improvement.

Use this path when you are new to AGNT5 and want a clear order through the docs. AGNT5 is organized around three jobs: build durable agentic workflows, run them in managed environments, and improve them from production evidence. Each stage below links to the task pages you need without turning the docs into a course.

## 1. Run a working workflow

Start with a small project that produces a visible **trace**: the recorded execution path of a workflow run, including steps, model calls, timing, and cost.

1. [Install the CLI](/docs/install-cli.md): install `agnt5`, verify the binary, and authenticate.
2. [Hacker News digest quickstart](/docs/quickstart.md): create a workflow project, run it in an AGNT5 Cloud dev environment, and inspect the trace.
3. [Build with AI coding agents](/docs/build-with-ai.md): give Codex, Claude Code, Cursor, Windsurf, Cline, or Copilot an AGNT5-aware task prompt.

Outcome: you have seen a workflow run and can inspect what happened.

## 2. Learn the build model

AGNT5 code is built from a few primitives. A **workflow** is a durable program, a **function** is a retryable unit of work, an **agent** reasons and calls tools, and a **prompt** keeps model instructions versioned with code.

- **[Workflows](/docs/build/workflows.md)**: compose checkpointed steps, durable sleep, parallel work, state, and triggers.
- **[Functions](/docs/build/functions.md)**: wrap deterministic work with retries, backoff, timeouts, and trace visibility.
- **[Agents](/docs/build/agents.md)**: configure model instructions, tools, handoffs, and loop limits.
- **[Tools](/docs/build/tools.md)**: expose typed actions that agents can call.
- **[Prompts](/docs/build/prompts.md)**: keep prompt text runnable from Python or TypeScript and tied to production versions.

Outcome: you can choose the smallest AGNT5 primitive for the behavior you need.

## 3. Build locally

Use local development when you are changing workflow behavior and want fast feedback before deploying. Keep secrets outside git, run the worker with hot reload, and trigger runs from Studio, the CLI, or the API.

1. [Local development](/docs/build/local-development.md): run `agnt5 dev`, trigger local runs, and watch traces.
2. [Human-in-the-loop](/docs/build/human-in-the-loop.md): pause workflows for approvals, selections, and follow-up input.
3. [Webhooks](/docs/build/webhooks.md): receive signed external events and route them into workflows.
4. [Integrations](/docs/integrations/overview.md): store credentials once and scope them to a workspace, project, or environment.

Outcome: your project runs locally with the inputs, prompts, approvals, events, and credentials it needs.

## 4. Go live

Move from local development to a managed AGNT5 environment when you need a worker that runs outside your laptop. A **deployment** is your worker running in AGNT5 Cloud with environment-scoped configuration and observable runs.

1. [Deploying](/docs/run/deploying.md): set secrets, deploy a worker, verify it, and trigger a run.
2. [Run with AGNT5](/docs/run/overview.md): understand the run-time surfaces for deployments, runs, traces, logs, and metrics.
3. [Event sources](/docs/integrations/event-sources/overview.md): connect Sentry, Stripe, GitHub, Slack, or any Standard Webhooks publisher.

Outcome: your workflow can run in a managed environment and receive production inputs.

## 5. Operate with trust

After a workflow is live, use AGNT5's run data to debug behavior and understand reliability. A **run** is one workflow execution; its trace, logs, metrics, and cost records are the evidence you use to operate it.

- **[Runs and traces](/docs/run/deploying.md#runs)**: list runs, describe one run, and open it in Studio.
- **[Trace inspection](/docs/run/deploying.md#traces)**: inspect model calls, tool calls, inputs, outputs, retries, and timing.
- **[Logs](/docs/run/deploying.md#logs)**: stream deployment logs or fetch logs scoped to a run.
- **[Metrics](/docs/run/deploying.md#metrics)**: monitor executions, success rate, latency, and LLM cost.

Outcome: you can answer what happened during a production run and where to look next.

## 6. Improve behavior

Use production evidence to decide whether a prompt, model, or workflow change is better than the current version. Improvement work starts with real runs and ends with a measured decision.

1. [Improve with AGNT5](/docs/improve/overview.md): understand datasets, scorers, experiments, and prompt changes.
2. [Prompts](/docs/build/prompts.md): commit production prompts and select versions from code.
3. [Workflows](/docs/build/workflows.md): structure agentic work so it can be observed and evaluated.

Outcome: you can turn observed behavior into safer prompt, model, and workflow changes.

## Next steps

- [Quickstart](/docs/quickstart.md): create and run the first workflow in the path.
- [Build with AGNT5](/docs/build/overview.md): jump into the authoring docs when you know what you want to build.
- [Run with AGNT5](/docs/run/overview.md): deploy and operate a workflow outside local development.
- [Improve with AGNT5](/docs/improve/overview.md): use production run data to measure behavior changes.


# quickstart

---

## Hacker News digest quickstart

_Source: https://agnt5.com/docs/quickstart.md_

> Create a Hacker News digest workflow, run it in an AGNT5 Cloud dev environment, and inspect the execution trace.

In this quickstart, you create a **[workflow](/docs/build/workflows.md)**: a durable program that AGNT5 runs with checkpointed steps. The workflow summarizes the top Hacker News stories, runs in an AGNT5 Cloud dev environment, and records a **[trace](/docs/run/overview.md)** that shows each step, model call, and result. The Hacker News API is public, so you only need an Anthropic or OpenAI API key for the summarizer.

**You'll need:** the **[CLI](/docs/install-cli.md)** (`agnt5`), Python 3.12+ or Node.js 22+ with npm, an [Anthropic API key](https://console.anthropic.com/settings/keys) or [OpenAI API key](https://platform.openai.com/api-keys), and about 3 minutes.



> **Build with your AI coding agent**
> Give Codex, Claude Code, Cursor, Windsurf, Cline, or Copilot a copyable prompt for this quickstart. If you want durable project instructions first, install AGNT5 skills.
> Installs the CLI, scaffolds the project, configures ANTHROPIC_API_KEY or OPENAI_API_KEY, starts agnt5 dev, and walks you through the first run.
> [Install AGNT5 skills](/docs/build-with-ai)
> Running the manual commands yourself? Skip this prompt. The same steps are below.


**Python:**

    

```text
Help me run the AGNT5 Hacker News digest quickstart.

1. Install the AGNT5 CLI if it is 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 --template python/quickstart my-agnt5-quickstart
     cd my-agnt5-quickstart

4. Copy .env.example to .env. Ask me whether I want to use Anthropic or OpenAI.
   - If I choose Anthropic, ask for my Anthropic API key, uncomment ANTHROPIC_API_KEY in .env, fill it in, and change the summarizer model in src/agnt5_quickstart/functions.py to "anthropic/claude-3-5-haiku-20241022".
   - If I choose OpenAI, ask for my OpenAI API key, uncomment OPENAI_API_KEY in .env, and fill it in.
   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:
- Do not modify workflows.py or functions.py except for the Anthropic model switch if I choose Anthropic.
- Keep the default summarizer model as openai/gpt-5-mini when I choose OpenAI.
- The Hacker News API is public. No Hacker News token is needed.
```


  


  

**TypeScript:**

    

```text
Help me run the AGNT5 Hacker News digest quickstart.

1. Install the AGNT5 CLI if it is 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 --template typescript/quickstart my-agnt5-quickstart
     cd my-agnt5-quickstart

4. Install dependencies:
     npm install

5. Copy .env.example to .env. Ask me whether I want to use Anthropic or OpenAI.
   - If I choose Anthropic, ask for my Anthropic API key, uncomment ANTHROPIC_API_KEY in .env, fill it in, change model to LM.anthropic(), and change modelName in src/functions.ts to "anthropic/claude-3-5-haiku-20241022".
   - If I choose OpenAI, ask for my OpenAI API key, uncomment OPENAI_API_KEY in .env, and fill it in.
   Do not commit .env.

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

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

8. 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 7 and get_trace on the latest run to verify completion and show me the trace tree.

Rules:
- Do not modify workflows.ts or functions.ts except for the Anthropic model switch if I choose Anthropic.
- Keep the default summarizer model as openai/gpt-5-mini when I choose OpenAI.
- The Hacker News API is public. No Hacker News token is needed.
```


  





## 1. Install the CLI

Install `agnt5`, then authenticate the CLI against your AGNT5 account.


  

**curl (macOS, Linux, WSL2):**

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


  

**Homebrew (macOS only):**

```bash
brew install agnt5/tap/agnt5
```




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.

```bash
agnt5 auth login
```

The command opens a browser window to sign you in. For install verification and API-key auth, see the [install guide](/docs/install-cli.md).

## 2. Create the workflow project

Create the quickstart project from the Hacker News digest template.



**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
npm install
```



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

## 3. Configure a model API key

Create a local `.env` file from the template example, then uncomment and fill in one provider key. The template uses OpenAI by default. For Anthropic, set `ANTHROPIC_API_KEY` and switch the summarizer model before starting the dev server.

```bash
cp .env.example .env
```

`.env.example` starts with both provider keys commented out:

```bash
# ANTHROPIC_API_KEY="sk-ant-..."
# OPENAI_API_KEY="sk-..."
```

In `.env`, remove `#` from exactly one key and fill in the value.

If you use Anthropic, change the summarizer model.



**Python:**

```python
summarizer = Agent(
    name="hn_summarizer",
    model="anthropic/claude-3-5-haiku-20241022",
    instructions=SUMMARIZER_PROMPT,
)
```





**TypeScript:**

```ts
const agent = new Agent({
  name: 'hn_summarizer',
  model: LM.anthropic(),
  modelName: 'anthropic/claude-3-5-haiku-20241022',
  instructions: SUMMARIZER_PROMPT,
});
```



Do not commit `.env`. The Hacker News API does not need a token; this key is only for the `summarize` step.

## 4. Start the dev server

Start the worker with `agnt5 dev`.

```bash
agnt5 dev
```

The dev server registers your components with the runtime and prints a Studio URL.



**Python:**

```text
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:**

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



Leave `agnt5 dev` running. It owns the local worker session that Studio calls.

## 5. Run the digest workflow

Open the Studio URL from the terminal in your browser. A **run** is one execution of a workflow, function, or agent.

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

The trace renders live as each step lands. Click a step to inspect its input, output, logs, prompt, response, and cost.

## 6. View the trace

The first run should show this shape:



**Python:**

```text
digest (workflow)
├─ fetch_top_ids
├─ fetch_story (x5 parallel)
├─ summarize (x5 parallel)
└─ assemble_digest
```





**TypeScript:**

```text
digest (workflow)
├─ fetchTopIds
├─ fetchStory (x5 parallel)
├─ summarize (x5 parallel)
└─ assembleDigest
```



Open the final `assemble_digest` or `assembleDigest` step to see the generated digest text. Each step is checkpointed, so a worker restart skips completed steps and continues from the missing work.

## Troubleshoot

<AccordionGroup>
  <Accordion title="agnt5 is not found after installation">
    Open a new terminal and run `agnt5 version`. If it still fails, add `~/.agnt5/bin` to your `PATH` manually and re-run the install command if the binary is missing.
  </Accordion>
  <Accordion title="agnt5 dev cannot call the model provider">
    Confirm `.env` exists in the project root and contains `ANTHROPIC_API_KEY="sk-ant-..."` or `OPENAI_API_KEY="sk-..."`. If you set an Anthropic key, confirm the summarizer model uses `anthropic/claude-3-5-haiku-20241022`. Restart `agnt5 dev` after changing `.env` or the model.
  </Accordion>
  <Accordion title="The TypeScript worker cannot start">
    Run `npm install` from `my-agnt5-quickstart` and then restart `agnt5 dev`. The TypeScript template expects dependencies to be installed before the worker starts.
  </Accordion>
  <Accordion title="The Studio URL opens but no digest workflow appears">
    Check the `agnt5 dev` terminal for registration errors. The expected components are listed in step 4. Fix the error, then restart `agnt5 dev`.
  </Accordion>
</AccordionGroup>

## Next steps



Now that the workflow runs, move it toward production use.

- [Follow the learning path](/docs/learning-path): Move through the recommended order from first run to build, deploy, operate, and improve.
- [Deploy the workflow](/docs/run/deploying): Set secrets, create an environment, deploy the worker, and trigger a run outside `agnt5 dev`.
- [Evaluate the output](/docs/improve/overview): Turn runs into datasets, add scorers, and compare prompt or model changes.
- [Integrate with your app](/docs/integrations/event-sources/overview): Connect external events or webhooks so your application starts workflow runs.


# run

---

## Deploying

_Source: https://agnt5.com/docs/run/deploying.md_

> Deploy your worker to a managed AGNT5 environment, then verify it and observe runs, traces, logs, and metrics from the CLI, API, and Studio.

Deploy your worker to a managed environment with a single command. The managed worker runs on AGNT5's infrastructure, your laptop is no longer in the loop.

---

## Prerequisites

- Authenticated: `agnt5 auth login`

---

## Set secrets and integrations

Set your secrets and integrations before deploying so the worker has everything it needs on first start.

### Secrets

**Via Studio:**

1. Open your project in Studio.
2. Go to **Settings** -> **Secrets**.
3. Add your secrets (e.g. `OPENAI_API_KEY`).

**Via the CLI:**

```bash
# Set a secret (prompted securely)
agnt5 secrets set --name OPENAI_API_KEY --type api_key

# Or pipe from stdin
echo "sk-..." | agnt5 secrets set --name OPENAI_API_KEY --type api_key --stdin

# List all secrets for the project
agnt5 secrets list
```

Run from within your project directory, no `--project` flag needed.

### Integrations

To connect an AI provider or an inbound webhook source:

1. Open your project in Studio.
2. Go to **Settings → Integrations**.
3. Click **Add Integration** and follow the setup steps.

See [AI providers](/docs/integrations/ai-providers.md) for provider-specific setup.

---

## Deploy

```bash
# Deploy to preview (default)
agnt5 deploy

# Deploy to staging
agnt5 deploy --env staging

# Deploy to production
agnt5 deploy --env production
```

Terminal output:

```
Warning: You are deploying to PRODUCTION
   Environment: production

Continue with production deployment? (y/N): y
Deploying to workspace: A5
ok Bundle (1.1s)
ok Deploy (3.1s)

https://app.agnt5.com/projects/a3e7af1d-c453-4124-be15-f72bd658889d/deployments/3547b7d0-f5cf-4648-a02c-516333305170
Logs: agnt5 logs 3547b7d0-f5cf-4648-a02c-516333305170
```

The deployment URL links directly to the deployment in Studio. Use the `agnt5 logs` command printed in the output to tail the worker logs.

---

## Verify

```bash
# Check deployments for an environment
agnt5 deployments --environment production

# Tail the worker logs
agnt5 logs <deployment-id> --follow
```

---

## Deployment logs

View logs for the entire deployment — all runs, worker startup, and system events.

### CLI

```bash
agnt5 logs <deployment-id>
agnt5 logs <deployment-id> --follow    # live stream
agnt5 logs <deployment-id> --tail 50  # last 50 lines
```

### API

```
GET https://api.agnt5.com/api/v1/deployments/<deployment_id>/logs
```

```bash
curl 'https://api.agnt5.com/api/v1/deployments/<deployment_id>/logs' \
  -H "X-API-KEY: <token>"
```

For a live stream (SSE):

```bash
curl -N 'https://api.agnt5.com/api/v1/deployments/<deployment_id>/logs/tail' \
  -H "X-API-KEY: <token>" \
  -H "Accept: text/event-stream"
```

---

## Testing after deployment

### Via Studio

Open your project in Studio and go to **Components**. Use the environment switcher at the top to select the environment you deployed to (Development, Staging, or Production). You can also pick a specific deployment from the list below.

Set the input and click **Run Workflow** to trigger a run against the deployed worker.

_[screenshot: Components page with environment switcher showing Development, Staging, Production]_

### Via the CLI

Use `--type` to select the component type and `--env` to target a deployed environment.

```bash
# Run a workflow
agnt5 run travel_booking_workflow \
  --type workflow \
  --input '{"message": "2 adults are traveling from Los Angeles (LAX) to New York (JFK), departing on June 28, 2026, and returning on June 30, 2026."}' \
  --env production

# Run a function (streams output as it runs)
agnt5 run summarize_itinerary \
  --type function \
  --input '{"trip_id": "abc123"}' \
  --env production

# Run a tool
agnt5 run search_flights \
  --type tool \
  --input '{"departure_id": "LAX", "arrival_id": "JFK", "outbound_date": "2026-06-28", "return_date": "2026-06-30", "adults": 2}' \
  --env production

# Run an agent — input must include a "message" field
agnt5 run travel_booking_agent \
  --type agent \
  --input '{"message": "Find me flights from LAX to JFK in late June for 2 adults"}' \
  --env production
```

**Component types and output behaviour:**

| `--type` | Default | Output |
|---|---|---|
| `function` | Yes | Streams as SSE — output prints to the terminal as it arrives |
| `workflow` | No | Returns final JSON output when the run completes |
| `tool` | No | Returns the tool result as JSON |
| `agent` | No | Returns the agent reply as JSON; input must include a `"message"` field |

**Auto type-detection:** if `--type` is omitted and the component is not a function, the gateway returns a 404 with the actual component type. The CLI automatically retries against the correct endpoint, so `agnt5 run my_workflow` works without `--type` in most cases.

**Capturing output:** all component types print JSON to stdout. Use shell redirection to save or pipe results:

```bash
agnt5 run travel_booking_workflow --type workflow \
  --input '{"message": "..."}' --env production > result.json

agnt5 run search_flights --type tool \
  --input '{"adults": 2}' --env production | jq '.flights[0]'
```

**Custom gateway URL:** by default the CLI routes through `https://api.agnt5.com`. Override with the `AGNT5_GATEWAY_URL` environment variable to point at a self-hosted or staging gateway:

```bash
AGNT5_GATEWAY_URL=https://gw.staging.example.com agnt5 run my_workflow \
  --type workflow --input '{}' --env staging
```

### Via the API

Copy the curl command directly from the component in Studio — it includes the correct workspace ID and deployment ID for the selected environment. Replace the `X-API-KEY` with your service key (see [Creating an X-API-KEY](/docs/build/local-development.md#creating-an-x-api-key)):

```bash
curl -X POST 'https://gw.agnt5.com/v1/workflows/travel_booking_workflow/run' \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: agnt5_sk_..." \
  -H "X-WORKSPACE-ID: d03e6b5f-da6a-43e6-9533-f492175f554a" \
  -H "X-DEPLOYMENT-ID: 9a0e18d6-c4a3-464d-b114-9d63f67fd8cd" \
  -d '{"message": "2 adults are traveling from Los Angeles (LAX) to New York (JFK), departing on June 28, 2026, and returning on June 30, 2026."}'
```

---

## Runs

A **run** is a single execution of a workflow, function, or agent. Every trigger — from Studio, the CLI, or the API — creates a run.

Each run records:

| Field | Description |
|---|---|
| Run ID | Unique identifier for the execution |
| Component | Name and type (workflow, function, agent) |
| Status | `pending`, `running`, `completed`, `failed` |
| Duration | Total wall-clock time |
| Queue time | Time the run spent waiting before execution started |
| Steps | Number of checkpointed steps completed |
| Retries | How many function retries were triggered |
| LLM calls | Number of model calls made |
| LLM cost | Estimated cost in USD |
| Error | Error type and category (on failure) |

### Listing runs from the CLI

```bash
agnt5 inspect runs ls
```

Output:

```
  RUN ID                                 COMPONENT                  TYPE       STATUS       DURATION   STARTED
  ────────────────────────────────────────────────────────────────────────────────────────────────────────────
  019e98f0-d4a1-76e1-9177-46d5c004ab6e   travel_booking_workflow    workflow   completed    27.8s      9 min ago

  1 run (1 completed)
```

**Flags:**

| Flag | Description |
|---|---|
| `--status <value>` | Filter by status: `completed`, `failed`, `running`, `pending` |
| `--component <name>` | Filter by component name |
| `--component-type <type>` | Filter by type: `COMPONENT_TYPE_WORKFLOW`, `COMPONENT_TYPE_FUNCTION`, `COMPONENT_TYPE_AGENT` |
| `--since <window>` | Limit to a time window, e.g. `1h`, `24h`, `7d` |
| `--limit <n>` | Maximum runs to show (default: 20) |
| `-w` | Watch mode — auto-refreshes every 2 seconds |
| `--output json` / `-o json` | Machine-readable output |

```bash
# Only failed runs in the last hour
agnt5 inspect runs ls --status failed --since 1h

# All runs for a specific workflow, live
agnt5 inspect runs ls --component travel_booking_workflow -w

# Pipe to jq
agnt5 inspect runs ls --output json | jq '.[].run_id'
```

### Listing runs via the API

```
GET https://api.agnt5.com/api/v1/analytics/runs
```

Requires `X-API-KEY: <token>`. See [Creating an X-API-KEY](/docs/build/local-development.md#creating-an-x-api-key) to generate one.

| Query parameter | Description |
|---|---|
| `project_id` | Your project UUID (required) |
| `status` | Filter: `completed`, `failed`, `running`, `pending` |
| `component_name` | Filter by component name |
| `component_type` | Filter by type |
| `since` | RFC 3339 timestamp — only runs after this time |
| `limit` | Max results |

```bash
curl 'https://api.agnt5.com/api/v1/analytics/runs?project_id=<project_id>&status=completed&limit=20' \
  -H "X-API-KEY: <token>"
```

### Describing a run from the CLI

```bash
agnt5 inspect runs describe <runId>
```

Output:

```
  Run: 019e98f0-d4a1-76e1-9177-46d5c004ab6e
  ──────────────────────────────────────────────────

  Component:   travel_booking_workflow (workflow)
  Status:      completed
  Duration:    27.8s
  Queue time:  7ms
  Enqueued:    9 min ago
  Started:     9 min ago
  Ended:       9 min ago
  Trace ID:    019e98f0d4a575d39c4a866f753cb8ab

  Next steps:
    agnt5 inspect logs -r 019e98f0..
    agnt5 inspect trace -r 019e98f0..
```

Pass `--output json` for machine-readable output.

### Getting a run via the API

```
GET https://api.agnt5.com/api/v1/analytics/runs/<run_id>?project_id=<project_id>
```

```bash
curl 'https://api.agnt5.com/api/v1/analytics/runs/<run_id>?project_id=<project_id>' \
  -H "X-API-KEY: <token>"
```

### Runs in Studio

Open your project in Studio and navigate to **Runs** in the left sidebar. The runs list shows all executions for the project. Click any row to open the run detail page, which shows status, timing, step count, LLM usage, and a link into the trace.

_[screenshot: Runs list page showing run ID, component, status, duration columns]_

_[screenshot: Run detail page showing status, timing, steps, LLM usage, and Trace link]_

---

## Traces

A **trace** is the full execution timeline for a run — a tree of spans showing what happened, in what order, and how long each part took.

Each span captures one unit of work: a workflow step, a function call, an agent iteration, an LLM request, or a tool call. Spans nest under their parent — a workflow span contains step spans, which contain function spans, and so on.

### Viewing a trace from the CLI

```bash
agnt5 inspect trace -r <runId>
```

Output (tree view):

```
  Trace: 019e98f0d4a575d39c4a866f753cb8ab  (27.9s)

  workflow.travel_booking_workflow      [27.9s]
  python_component_execution            [27.9s]
  agent.travel_booking_agent            [27.0s]
  chat openai/gpt-5-mini                [8.9s]
  tool.search_flights                   [197ms]
  tool.search_hotels                    [3.0s]
  chat openai/gpt-5-mini                [2.7s]
  tool.create_itinerary                 [61ms]
  chat openai/gpt-5-mini                [10.6s]
```

Error spans are highlighted in red.

**Flags:**

| Flag | Description |
|---|---|
| `-r <runId>` | Run ID to show the trace for (required) |
| `--flat` | Flat list sorted by start time instead of a tree |
| `--verbose` | Also print span attributes (inputs, outputs, model names, token counts) |
| `--output json` / `-o json` | Raw trace JSON |

```bash
# Flat list — useful for long traces
agnt5 inspect trace -r <runId> --flat

# Show span attributes (inputs/outputs, LLM params)
agnt5 inspect trace -r <runId> --verbose
```

### Getting a trace via the API

Use the `trace_id` from the run record. You can find it in the output of `agnt5 inspect runs describe <runId>` or the run detail API response.

```
GET https://api.agnt5.com/api/v1/traces/<trace_id>
```

```bash
curl 'https://api.agnt5.com/api/v1/traces/<trace_id>' \
  -H "X-API-KEY: <token>"
```

Returns an array of spans. Each span has `name`, `start_ns`, `end_ns`, `status_code`, and an `attrs` JSON string with inputs, outputs, model names, and token counts.

### Trace in Studio

Navigate to a run in Studio and click the **Trace** tab. The trace renders as an interactive tree — click any node to expand its inputs, outputs, and attributes. For agent runs, each reasoning iteration and tool call appears as a nested span. LLM spans show the model name, token counts, and cost.

The trace updates in real-time while a run is in progress.

_[screenshot: Trace tab showing the interactive span tree with a node expanded to reveal inputs, outputs, and LLM token counts]_

---

## Logs

Logs are structured output emitted during a run, scoped to the execution that produced them.

### Viewing logs from the CLI

```bash
agnt5 inspect logs -r <runId>
```

Output:

```
17:59:40.449 INFO  Executing component (stream)
17:59:40.453 INFO  Orchestrator: DISPATCH
17:59:40.993 INFO  Travel booking workflow - message: 2 adults are traveling...
17:59:50.379 INFO  Searching flights: LAX -> JFK on 2026-06-28
17:59:50.517 INFO  Found 3 flight options
17:59:50.746 INFO  Searching hotels in New York, NY: 2026-06-28 to 2026-06-30
17:59:53.639 INFO  Found 3 hotel options
17:59:56.918 INFO  Creating itinerary for New York, NY (2026-06-28 to 2026-06-30)
18:00:08.099 INFO  Travel booking agent completed
18:00:08.395 INFO  Released active dispatch on owning peer
```

**Flags:**

| Flag | Description |
|---|---|
| `-r <runId>` | Run ID to fetch logs for (required) |
| `--severity <level>` | Filter: `DEBUG`, `INFO`, `WARN`, `ERROR` |
| `-f` / `--follow` | Stream new log lines in real-time (polls every 2s) |
| `--tail <n>` | Show only the last N lines |
| `--output json` / `-o json` | Raw JSON log entries |

```bash
# Only errors
agnt5 inspect logs -r <runId> --severity ERROR

# Live streaming (useful while a run is in progress)
agnt5 inspect logs -r <runId> --follow
```

### Getting logs via the API

```
GET https://api.agnt5.com/api/v1/runs/<run_id>/logs
```

| Query parameter | Description |
|---|---|
| `limit` | Max log lines to return (default: 100) |

```bash
curl 'https://api.agnt5.com/api/v1/runs/<run_id>/logs?limit=50' \
  -H "X-API-KEY: <token>"
```

Returns `{ "items": [...], "count": N, "next_offset": N }`. Each item has `body` (the log message), `severity`, `ts_ns` (timestamp), `trace_id`, and `span_id`.

---

## Promote via Studio

After verifying and testing, open the deployment URL printed in the terminal. From the deployment page in Studio you can promote the deployment to staging or production without running any commands. You can also roll back to a previous deployment from the same page.

See [Environments](/docs/run/environments.md) for how promotion, rollback, scaling, and environment-scoped secrets work.

_[screenshot: deployment page showing promote to staging/production]_

---

## Metrics

Metrics aggregate run data across time to show trends. They are available in Studio under **Analytics** and **Metrics**.

### Analytics (Studio)

The **Analytics** page shows a high-level summary for the selected time window.

**Summary cards:**
- Total executions
- Success rate
- P95 latency
- Total LLM cost

**Charts:**
- Executions over time (area chart, broken down by status)
- Latency over time (P95)
- LLM usage by model
- Top errors by frequency

Use the time range picker to switch between preset windows (`1h`, `3h`, `24h`, `7d`, `30d`) or a custom date range.

_[screenshot: Analytics page showing summary cards (total executions, success rate, P95 latency, LLM cost) and charts below]_

### Metrics (Studio)

The **Metrics** page gives per-component breakdowns with finer control.

**Filters:**
- **Deployment** — scope to a specific deployment
- **Component** — scope to a specific function, workflow, or agent
- **Status** — filter runs included in the aggregates

**Controls:**
- **Granularity** — bucket size for charts: `auto`, `1m`, `5m`, `1h`, `1d`
- **Auto-refresh** — automatically reload at a set interval
- **UTC** — display timestamps in UTC instead of local time

_[screenshot: Metrics page showing deployment/component/status filters and per-component latency and execution charts]_

---

## Common workflows

**Find why a run failed:**

```bash
agnt5 inspect runs ls --status failed --since 1h
agnt5 inspect runs describe <runId>
agnt5 inspect logs -r <runId> --severity ERROR
agnt5 inspect trace -r <runId>
```

**Watch a workflow as it executes:**

```bash
# In one terminal: stream the logs
agnt5 inspect logs -r <runId> --follow

# Or watch the run list update
agnt5 inspect runs ls --component my_workflow -w
```

**Export a trace for offline analysis:**

```bash
agnt5 inspect trace -r <runId> --output json > trace.json
```

---

## Machine-readable output

All CLI commands support a global `--output` flag that controls whether output is human-readable text or structured JSON.

```bash
agnt5 inspect runs ls --output json
agnt5 inspect runs describe <runId> --output json
agnt5 secrets list --output json
agnt5 service-keys list --output json
agnt5 deployment status --output json
```

**Precedence order (highest to lowest):**

1. `--output text` or `--output json` (explicit flag, shorthand `-o`)
2. `--json` (deprecated alias — still works, emits a deprecation warning on stderr)
3. `AGNT5_OUTPUT` or `OUTPUT_FORMAT` environment variables
4. Auto-detection: **text** when stdout is an interactive terminal, **JSON** when piped or redirected

Auto-detection means you get structured output for free when scripting:

```bash
# These automatically produce JSON because stdout is not a TTY:
agnt5 inspect runs ls | jq '.[].run_id'
agnt5 inspect runs ls | cat
agnt5 secrets list > secrets.json
```

**JSON envelope shape:**

Every command wraps its payload in a stable top-level envelope:

```json
// Success
{ "data": { ... } }

// Success with pagination metadata
{ "data": [ ... ], "meta": { ... } }

// Error (written to stderr, non-zero exit)
{ "error": { "message": "...", "code": "...", "category": "...", "suggestions": [...] } }
```

If the upstream API response already contains a `"data"` field, the CLI hoists it to avoid double-nesting — so `{"data": {"data": [...]}}` never appears. Any `"meta"` or `"metadata"` field from the API is preserved under `"meta"`.

```bash
# Examples of the envelope in practice:
agnt5 deployment status --output json          # {"data": {...deployment...}}
agnt5 inspect runs ls --output json            # {"data": [...runs...]}
agnt5 secrets list --output json               # {"data": [...], "meta": {...}}
agnt5 service-keys list --output json          # {"data": [...], "meta": {...}}
```

> `--json` is a deprecated alias for `--output json`. It still works but prints a warning to stderr. Use `--output json` in new scripts.

---

## Environments

_Source: https://agnt5.com/docs/run/environments.md_

> Separate preview, staging, and production traffic, promote a verified deployment forward, roll back fast, and scope secrets per environment.

An **environment** is a named pointer to a deployment. Requests address an environment, such as preview, staging, or production, and AGNT5 resolves the pointer to the environment's current deployment at request time. Promoting or rolling back updates that pointer; the deployment image and record stay immutable, so the build you verified in staging is the same build that serves production.

---

## Deploy to an environment

Every project starts with default environments. Create additional environments from the **Deployments** page in Studio; each environment renders as its own tab. `agnt5 deploy` targets the **preview** environment by default. Name an environment to target it directly:

```bash
agnt5 deploy                     # preview (default)
agnt5 deploy --env staging
agnt5 deploy --env production    # asks for confirmation
```

Set replica bounds at deploy time:

```bash
agnt5 deploy --env staging --min-replicas 1 --max-replicas 4
```

> **Tip:** The usual flow is deploy to preview, verify the deployment, then promote the same deployment forward. Promotion updates the environment pointer; it does not rebuild or mutate the deployment.

---

## Promote a deployment

Promotion points a target environment at a deployment that already proved itself in a lower environment.

1. Open your project in Studio and go to **Deployments**.
2. Select the deployment you verified (for example in the **Staging** tab).
3. Choose **Promote**, pick the target environment, and optionally adjust min/max replicas for the target.
4. Confirm. The target environment's pointer moves to this deployment; you can scale the previously serving deployment to zero in the same step.

Every promotion is recorded in the environment's **promotion history**, which is what makes rollback precise.

Via the API:

```bash
curl -X POST 'https://api.agnt5.com/api/v1/deployments/promote' \
  -H "X-API-KEY: <token>" \
  -H "Content-Type: application/json" \
  -d '{"source_deployment_id": "<deployment-id>", "target_environment_id": "<environment-id>"}'
```

---

## Roll back

Rollback points the environment at the previously serving deployment from its promotion history. Because that deployment's image still exists, rollback is a pointer move, not a rebuild.

1. In Studio, open **Deployments** and select the environment's tab.
2. Choose **Rollback** and confirm the deployment to restore.

Via the API: `POST /api/v1/deployments/rollback`.

> **Warning:** Rollback changes which code serves traffic, but not your data or secrets. If the bad deploy also changed a secret or external state, revert those separately.

---

## Scale, stop, and resume

Each deployment manages its own replicas:

- **Scale**: adjust min/max replicas from the deployment's **Scale** action in Studio, or via `POST /api/v1/deployments/<id>/scale-up` and `/scale-down`.
- **Stop**: **Terminate** stops a deployment's workers; the deployment record and image remain, so it can serve again later.
- **Resume**: **Start** brings a terminated deployment back up.

Check what a deployment is doing right now:

```bash
agnt5 deployment status    # replicas, uptime, status of the latest deployment
agnt5 deployment errors    # scheduling failures, image pull errors
```

---

## Environment-scoped secrets

Secrets default to project scope — every deployment sees them. Scope a secret to one environment when staging and production need different values:

```bash
# Project-wide
agnt5 secrets set --name OPENAI_API_KEY --type api_key

# Production-only value
agnt5 secrets set --name OPENAI_API_KEY --type api_key --environment <environment-id>

# See which secrets an environment resolves
agnt5 secrets list --environment <environment-id>
```

An environment-scoped secret overrides the project-scoped secret of the same name for deployments serving that environment.


**Model**: environment = named pointer to a deployment, resolved at request ingress; deployments are immutable; promote/rollback move the pointer (`POST /api/v1/deployments/promote`, `POST /api/v1/deployments/rollback`); promotion history per environment at `GET /api/v1/environments/<env-id>/promotion-history`.
**Commands**: `agnt5 deploy --env <name> [--min-replicas N --max-replicas N]`, `agnt5 deployment {status,errors}`, `agnt5 secrets {set,list,get,delete} [--environment <env-id>]`
**Environment APIs**: `GET/POST /api/v1/environments`, `GET/PUT/DELETE /api/v1/environments/<id>`; deployment lifecycle: `POST /api/v1/deployments/<id>/{start,terminate,scale-up,scale-down}`.


## Next steps

* [Deploying](/docs/run/deploying.md): the full deploy-verify-observe loop that feeds promotion.
* [Experiments](/docs/improve/experiments.md): gate a promotion on eval results by running the candidate deployment against a dataset.
* [Local development](/docs/build/local-development.md): iterate with `agnt5 dev` before anything reaches a managed environment.

---

## Run with AGNT5

_Source: https://agnt5.com/docs/run/overview.md_

> Deploy workers, trigger production runs, inspect traces, stream logs, and watch runtime metrics.

Run covers the production lifecycle for deployed AGNT5 workers. You deploy a worker, trigger workflows or agents, and use recorded run data to debug and operate production behavior.

## What you'll do

- **[Deploying](/docs/run/deploying.md)**: package your worker, deploy it to a managed environment, and verify the deployment.
- **[Serverless endpoints](/docs/run/serverless-endpoints.md)**: run AGNT5 components on Cloudflare Workers, Vercel or Next.js route handlers, Deno, Hono, and generic Node.js HTTP servers.
- **Runs**: inspect each execution of a workflow, function, or agent from Studio or the CLI.
- **Traces**: follow the steps, retries, model calls, and timing for a run.
- **Logs**: stream worker logs for a deployment or fetch logs for a specific run.
- **Metrics**: monitor throughput, latency, errors, token usage, and cost.

Outcome: your workflows and agents run outside your laptop, and every execution is observable.

## Next steps

- [Deploying](/docs/run/deploying.md): deploy a worker and verify it.
- [Serverless endpoints](/docs/run/serverless-endpoints.md): deploy beta workerless components on a supported serverless host.
- [Build with AGNT5](/docs/build/overview.md): define the workflows and agents you want to run.
- [Improve with AGNT5](/docs/improve/overview.md): use production run data to measure behavior changes.

---

## Serverless endpoints

_Source: https://agnt5.com/docs/run/serverless-endpoints.md_

> Run AGNT5 components from Cloudflare Workers, Vercel or Next.js route handlers, Deno, Hono, and Node.js HTTP servers without running a persistent worker process.

A **serverless endpoint** is an HTTPS deployment that serves an AGNT5 manifest and accepts signed invoke requests. AGNT5 can dispatch functions, workflows, tools, and agents to that endpoint instead of routing them to a persistent worker.

Serverless endpoints are in beta for Cloudflare Workers, Vercel or Next.js route handlers, Deno, Hono, and generic Node.js HTTP servers. AWS Lambda and Google Cloud Run are planned after beta.

## Choose a host

| Host | Use when | SDK entrypoint |
| --- | --- | --- |
| Cloudflare Workers | You want a fetch-native worker with fast global startup. | `@agnt5/sdk/serverless` |
| Vercel or Next.js | You want route handlers deployed with a Next.js or Vercel app. | `@agnt5/sdk/serverless` |
| Deno | You want a fetch-native Deno server or Deno Deploy endpoint. | `@agnt5/sdk/serverless` |
| Hono | You want one Hono app that can run on Node, Cloudflare Workers, Deno, Bun, or another Hono adapter. | `@agnt5/sdk/serverless` |
| Generic Node.js | You want to mount AGNT5 on `node:http`, Express, Fastify, Koa, or a similar Node host. | `@agnt5/sdk/serverless/node` |

Use the same component definitions across hosts. The host adapter only changes how HTTP requests reach the AGNT5 serverless protocol handler.

## Expose the protocol routes

Each endpoint must expose two routes:

- `GET /.well-known/agnt5`: returns the manifest AGNT5 registers.
- `POST /agnt5/invoke`: receives signed invoke requests from AGNT5.

For fetch-native hosts, export the handler from `@agnt5/sdk/serverless`:

```ts
const hello = workflow("hello", async (_ctx, input: { name?: string }) => ({
  message: `hello ${input.name ?? "world"}`,
}));

export default serve({
  serviceName: "my-serverless-agent",
  serviceVersion: process.env.VERCEL_GIT_COMMIT_SHA ?? "local",
  signingSecret: () => process.env.AGNT5_SERVERLESS_SIGNING_SECRET,
  workflows: [hello],
});
```

For generic Node.js hosts, adapt incoming Node request and response objects:

```ts
const hello = workflow("hello", async (_ctx, input: { name?: string }) => ({
  message: `hello ${input.name ?? "world"}`,
}));

const agnt5 = serveNode({
  serviceName: "my-node-agent",
  serviceVersion: process.env.GIT_SHA ?? "local",
  signingSecret: () => process.env.AGNT5_SERVERLESS_SIGNING_SECRET,
  workflows: [hello],
});

http.createServer((request, response) => {
  void agnt5(request, response);
}).listen(8787);
```

## Sync the deployment

After the provider deploys your endpoint, sync it with AGNT5. Sync creates or reuses an immutable AGNT5 deployment, imports the manifest, stores the signing secret reference, and can activate the component routes for an environment.

```bash
( umask 077 && openssl rand -base64 32 > .agnt5-serverless-secret )
# Store "$(cat .agnt5-serverless-secret)" in the provider's
# AGNT5_SERVERLESS_SIGNING_SECRET environment variable, then deploy.
export AGNT5_SERVERLESS_SIGNING_SECRET="$(cat .agnt5-serverless-secret)"

agnt5 serverless sync https://<endpoint-host> \
  --provider cloudflare \
  --env production \
  --immutable-ref <provider-version-or-git-sha> \
  --signing-secret-env AGNT5_SERVERLESS_SIGNING_SECRET \
  --request-timeout-ms 30000 \
  --yield-before-timeout-ms 1000
```

Use `--provider vercel` for Vercel and `--provider node` for a generic Node.js, Deno, or Hono Node endpoint. Use `--provider cloudflare` when Hono runs on Cloudflare Workers. Pass `--activate=false` when you want to import the endpoint without changing active route ownership, and pass `--replace-route-owners` only when you intend the endpoint to take over matching component routes in that environment.

## Validate the endpoint

Check that the manifest route is reachable before syncing:

```bash
curl https://<endpoint-host>/.well-known/agnt5
```

AGNT5 release branches also include provider smokes for the beta hosts:

```bash
export AGNT5_SERVERLESS_SIGNING_SECRET="$(cat .agnt5-serverless-secret)"
export VERCEL_AUTOMATION_BYPASS_SECRET=<vercel-bypass-secret-if-protected>

just test-e2e-workerless-cloudflare-smoke https://<cloudflare-worker-host>
just test-e2e-workerless-vercel-smoke https://<vercel-host>
just test-e2e-workerless-node-smoke https://<node-host>
```

Use the Node smoke for Hono on Node. Use the Cloudflare or Vercel smoke when Hono runs on those providers. Deno does not have a dedicated smoke yet; validate `/.well-known/agnt5`, then run the synced AGNT5 workflow after deploy.

The deployed smokes expect `https://` endpoint URLs; `http://` is accepted only for local loopback targets such as `127.0.0.1`. They fail before network calls unless `AGNT5_SERVERLESS_SIGNING_SECRET`, `AGNT5_WORKERLESS_SIGNING_SECRET`, or `WORKERLESS_SIGNING_SECRET` is set, and their output includes `signing=enabled` when direct invoke requests are signed. Vercel Deployment Protection can additionally use `VERCEL_AUTOMATION_BYPASS_SECRET` or `VERCEL_PROTECTION_BYPASS_SECRET`. The Node smoke can also start a local `node:http` server with the SDK adapter when no endpoint URL is passed.

## Beta limits

Serverless endpoints currently support signed dispatch, manifest sync, encrypted signing secret references, component route ownership, durable step checkpoints, timeout suspension, retries, concurrency, throttle, rate-limit, latest-run-wins debounce, static priority, queue-mode singleton keys, and idempotency metadata.

Batch declarations are rejected for workerless beta until aggregate batching enforcement exists. Keep batch policies on persistent workers for now.

Shared beta environments also require AGNT5 operator enablement. Operators enable the workerless dispatch gates and global workerless gate before a shared environment sends traffic to serverless endpoints.

## Next steps

- [Deploying](/docs/run/deploying.md): deploy and verify a managed worker.
- [Environments](/docs/run/environments.md): promote and roll back deployment pointers.
- [Workflows](/docs/build/workflows.md): define the components your endpoint serves.
- [Integrations](/docs/integrations/overview.md): configure provider and secret connections.


# Cookbooks

---

## Run any AI agent framework on a durable workflow runtime

_Source: https://agnt5.com/cookbooks/bring-your-own-agent-framework.md_

> Wrap LangGraph, OpenAI Agents SDK, Vercel AI SDK, or plain Python in durable AGNT5 steps.

AGNT5 does not require you to throw away an existing agent framework. This
cookbook shows how to keep LangGraph, OpenAI Agents SDK, Vercel AI SDK, or a
plain Python tool loop while adding durable execution, replay, and traces
underneath.

## Scenario

Your team already has an agent that calls tools and returns a structured result.
It works locally, but production failures are hard to recover from. You want the
agent call to run inside a durable workflow without rewriting the agent.

## What you build

- A wrapper function around existing agent logic.
- A workflow that checkpoints the framework result.
- Trace metadata for model calls, tool calls, and outputs.
- A recovery path after worker or API failures.
- A migration path that keeps framework choice flexible.

## Wrap the existing agent

Treat the existing agent as a step implementation.

```python
@function
async def run_existing_agent(request: AgentRequest) -> AgentResult:
    result = await existing_agent.invoke(
        input=request.prompt,
        metadata={"customer_id": request.customer_id},
    )
    return AgentResult.model_validate(result)
```

Then orchestrate it with AGNT5.

```python
@workflow
async def durable_agent_run(ctx: WorkflowContext, request: AgentRequest) -> AgentResult:
    prepared = await ctx.step(prepare_request, request)
    result = await ctx.step(run_existing_agent, prepared)
    return await ctx.step(record_agent_result_once, request.request_id, result)
```

The agent framework remains inside `run_existing_agent`. AGNT5 owns the durable
step boundary around it.

## Trace integration

At minimum, include:

- framework name and version,
- model name,
- tool names,
- final structured output,
- external side-effect receipts.

If the framework exposes callback hooks, map those events into AGNT5 trace
metadata. If it does not, record the final input and output at the step
boundary.

## Recovery model

On replay, AGNT5 returns the journaled `AgentResult` instead of calling the
framework again. On retry after a failed attempt, the wrapper runs again with the
same input. Any side effects inside the framework still need idempotency keys.

## Production checks

- The framework call only runs inside a step.
- The step result is structured and serializable.
- Tool side effects use stable idempotency keys.
- The trace links framework events back to the AGNT5 run ID.
- Replay does not call the model again for completed steps.

## Next steps

- [Retry AI workflow steps without duplicate side effects](/cookbooks/retry-without-duplicate-side-effects.md)
- [Build a deep research agent](/cookbooks/deep-research-agent.md)
- [Debug AI workflows with traces, not scattered logs](/cookbooks/workflow-native-observability.md)

---

## Build a travel booking agent

_Source: https://agnt5.com/cookbooks/customer-support-agent.md_

> A single agent that searches real flights and hotels via SerpAPI, builds a day-by-day itinerary, and handles multi-turn conversations about a trip.

This cookbook builds a travel booking agent that searches live flight and hotel
data, builds a day-by-day itinerary, and handles a full multi-turn conversation
about a trip inside a single durable workflow run.

## What you build

- A `travel_booking_agent` with three tools: flight search, hotel search, and itinerary creation.
- A workflow that takes a user message and runs the agent to completion.
- Real-time data from SerpAPI Google Flights and Google Hotels.
- Conversation-aware responses that carry context across multiple turns.

## Workflow shape

```python
@workflow
async def travel_booking_workflow(ctx: WorkflowContext, message: str) -> dict:
    result = await travel_booking_agent.run(message, context=ctx)
    return {"status": "completed", "output": result.output}
```

The agent handles all the tool orchestration internally. The workflow is a single
durable step that checkpoints the agent's tool calls and model responses.

## Agent and tools

The agent decides when to call each tool based on the conversation:

```python
travel_booking_agent = Agent(
    name="travel_booking_agent",
    model="openai/gpt-4o-mini",
    instructions="...",  # see agents.py
    tools=[search_flights, search_hotels, create_itinerary],
)
```

| Tool | Data source | What it returns |
|---|---|---|
| `search_flights` | SerpAPI Google Flights | Top 3 options with price, airline, times, duration |
| `search_hotels` | SerpAPI Google Hotels | Top 3 options with price, rating, reviews, amenities |
| `create_itinerary` | Agent-generated | Day-by-day plan combining flight and hotel details |

For a trip-planning request, the agent always runs all three tools in sequence —
flights first, then hotels, then itinerary — without prompting the user between steps.

## Tool inputs

**search_flights**

```python
search_flights(
    departure_id="JFK",    # airport code, inferred from city name
    arrival_id="LHR",
    outbound_date="2025-12-15",
    return_date="2025-12-22",   # omit for one-way
    adults=1,
)
```

**search_hotels**

```python
search_hotels(
    location="London, UK",
    check_in_date="2025-12-15",
    check_out_date="2025-12-22",
    adults=1,
)
```

**create_itinerary**

```python
create_itinerary(
    destination="London",
    travel_dates="Dec 15–22 2025",
    preferences="Solo traveler, budget-conscious",
)
```

## Conversation awareness

The agent receives the full conversation history on every turn. The instructions
explicitly require it to check what the user already said before asking for more
details:

- It infers airport codes from city names (New York → JFK, Paris → CDG).
- It never re-asks for information already provided earlier in the thread.
- After presenting results it proactively offers the next step.

## Prerequisites

- An AGNT5 account. Sign up at [app.agnt5.com](https://app.agnt5.com).
- Python 3.11+ and [uv](https://docs.astral.sh/uv/getting-started/installation/).
- An [OpenAI API key](https://platform.openai.com/api-keys).
- A [SerpAPI key](https://serpapi.com/) for live flight and hotel data.

---

## Step 1: Install the CLI

Follow the [CLI install guide](/docs/install-cli.md) to install `agnt5` and authenticate. Come back when `agnt5 auth status` confirms you are signed in.

---

## Step 2: Create the project

```bash
agnt5 create --template python/travel_booking my-travel-bot
cd my-travel-bot
uv sync
```

---

## Step 3: Configure environment variables

```bash
cp .env.example .env
```

Open `.env` and set both keys:

```bash
OPENAI_API_KEY="sk-..."
SERPAPI_KEY="your-serpapi-key"
```

---

## Step 4: Deploy

```bash
agnt5 deploy
```

---

## Step 5: Run the agent

You can run the workflow directly from Studio. Open your deployment, select `travel_booking_workflow` from the Components list, and click **Run Workflow**. Pass a natural-language travel request as the `message` input.

The agent runs `search_flights`, `search_hotels`, and `create_itinerary` in one turn and returns a complete travel plan with specific flight options, hotel options, and a day-by-day itinerary.

<DocsImage
  src="/docs/integrations/Trace-dev-light.png"
  darkSrc="/docs/integrations/Trace-dev-dark.png"
  alt="Studio showing a completed travel_booking_workflow run with the agent trace expanded, displaying search_flights and search_hotels tool calls and the final itinerary output."
  caption="Studio traces every agent iteration, tool call, and model response. Click any step to inspect its input, output, tokens, and duration."
  width={1682}
  height={1060}
/>

Go to **Runs** to see the full execution history. Each agent iteration, tool call, and model response is recorded as a step in the trace.

<DocsImage
  src="/docs/integrations/Runs-light.png"
  darkSrc="/docs/integrations/Runs-dark.png"
  alt="Studio Runs list showing completed travel_booking_workflow runs with status, duration, and timestamp."
  caption="The Runs list shows every workflow execution. Click a run to open its trace."
  width={1746}
  height={954}
/>

---

## Production checklist

- **SerpAPI quota**: each tool call consumes one SerpAPI search credit. Monitor usage for high-volume deployments.
- **Airport code inference**: the agent infers codes from common cities. For uncommon airports, pass the IATA code directly in the message.
- **Itinerary detail**: `create_itinerary` returns a framework. The agent combines it with real flight and hotel data to produce the final response. The quality of the day-by-day plan depends on the model.
- **Secrets**: never commit `.env`. Inject `OPENAI_API_KEY` and `SERPAPI_KEY` as secrets in your deployment environment.

---

## Next steps

- [Build a deep research agent](/cookbooks/deep-research-agent.md): same agent-plus-tools pattern with Wikipedia and web search.
- [Build a durable human-approval AI workflow](/cookbooks/durable-human-approval-ai-workflow.md): add an approval gate before the agent acts on a booking.
- [Debug AI workflows with traces, not scattered logs](/cookbooks/workflow-native-observability.md): inspect every tool call and model response in the trace.

---

## Build a data extraction workflow

_Source: https://agnt5.com/cookbooks/data-extraction.md_

> Call tools, force JSON outputs, recover from malformed responses, and inspect every extraction step.

This cookbook builds a structured extraction workflow for AI outputs that must
be parsed, validated, retried, and explained.

## Scenario

An analyst submits free-form notes. The workflow extracts accounts, contacts,
dates, and next actions as JSON, validates the result, and stores the structured
record.

## What you build

- A structured-output prompt.
- A schema validator.
- A repair step for malformed JSON.
- A retry policy for transient model failures.
- A trace that shows raw and parsed outputs.

## Workflow shape

```python
@workflow
async def extract_account_update(ctx: WorkflowContext, note_id: str) -> ExtractionResult:
    note = await ctx.step(load_note, note_id)
    raw = await ctx.step(call_extraction_agent, note.text)
    parsed = await ctx.step(parse_and_validate_update, raw)
    receipt = await ctx.step(store_update_once, note.id, parsed)
    return ExtractionResult(update_id=receipt.id)
```

Separating model call and parse step makes malformed output easy to inspect.

## Schema-first extraction

Define the expected output before writing the prompt.

```python
class AccountUpdate(BaseModel):
    account_name: str
    contacts: list[str]
    next_action: str
    due_date: date | None
    confidence: float
```

The validator should reject missing required fields and values that do not match
business rules.

## Malformed output recovery

If parsing fails, run a bounded repair step and keep both versions in the trace.

```python
@function
async def parse_and_validate_update(raw: str) -> AccountUpdate:
    try:
        return AccountUpdate.model_validate_json(raw)
    except ValidationError:
        repaired = await repair_json(raw)
        return AccountUpdate.model_validate_json(repaired)
```

## Production checks

- Raw model output and parsed output are both trace-visible.
- Repair attempts are bounded.
- Invalid data fails before the storage step.
- The storage step is idempotent.
- Failed extractions can be converted into eval cases.

## Next steps

- [Build a document processing pipeline](/cookbooks/document-processing.md)
- [Debug and replay a failed AI workflow](/cookbooks/debug-production-run.md)
- [Debug AI workflows with traces, not scattered logs](/cookbooks/workflow-native-observability.md)

---

## Debug and replay a failed AI workflow

_Source: https://agnt5.com/cookbooks/debug-production-run.md_

> Build a support workflow that fails on malformed LLM output, inspect the trace, patch the step, and recover without repeating completed work.

This cookbook builds one production-shaped failure from start to finish: a
customer-support workflow calls an LLM, gets malformed structured output, fails
before any external side effect happens, and then gets debugged from the trace.

By the end, you should be able to answer the questions that matter during an AI
workflow incident:

- Which step failed?
- What input, prompt, model output, and parsed state led to the failure?
- Which steps are already checkpointed?
- Is it safe to fix the code and let the workflow continue?
- How do we turn this failure into a regression case later?

## What you build

A support reply workflow with five steps:

1. Load the ticket.
2. Load the customer profile.
3. Classify the ticket.
4. Draft a structured reply with an agent.
5. Create an internal note after the draft validates.

The failure is deliberately placed in step 4. The model returns JSON without a
required `confidence` field, so validation fails before `create_internal_note`
can run. That gives you a clean incident to debug: earlier reads are
checkpointed, later side effects have not happened.

## Prerequisites

- The AGNT5 CLI is installed and authenticated.
- Python 3.12 or newer.
- An OpenAI API key in your project environment.
- A local AGNT5 dev session.

Start from a support-style project:

```bash
agnt5 create support-debug --template python/support-triage
cd support-debug
```

Run the dev session in one terminal:

```bash
agnt5 dev
```

## Add the failing workflow

Create a small workflow dedicated to this incident. The important design choice
is the step boundary: each external read, model call, and side effect is a
separate `ctx.step(...)`.

```python
from typing import Literal

from agnt5 import WorkflowContext, function, workflow
from pydantic import BaseModel, Field, ValidationError


class Ticket(BaseModel):
    ticket_id: str
    customer_id: str
    subject: str
    body: str


class CustomerProfile(BaseModel):
    customer_id: str
    plan: str
    refund_eligible: bool


class Classification(BaseModel):
    category: Literal["billing", "technical", "account"]
    priority: Literal["low", "normal", "high"]


class DraftReply(BaseModel):
    body: str
    confidence: float = Field(ge=0, le=1)


class InternalNote(BaseModel):
    note_id: str
    ticket_id: str


@function
async def load_ticket(ticket_id: str) -> Ticket:
    return Ticket(
        ticket_id=ticket_id,
        customer_id="cus_123",
        subject="Need a refund",
        body="I upgraded by mistake and would like my money back.",
    )


@function
async def load_customer_profile(customer_id: str) -> CustomerProfile:
    return CustomerProfile(
        customer_id=customer_id,
        plan="pro",
        refund_eligible=True,
    )


@function
async def classify_ticket(ticket: Ticket, profile: CustomerProfile) -> Classification:
    return Classification(category="billing", priority="high")


@function
async def draft_structured_reply(
    ticket: Ticket,
    profile: CustomerProfile,
    classification: Classification,
) -> DraftReply:
    # In a real project this is an Agent or model call. The malformed payload
    # simulates the incident: `confidence` is missing.
    model_output = """
    {
      "body": "You're eligible for a refund. I can start that process now."
    }
    """

    return DraftReply.model_validate_json(model_output)


@function
async def create_internal_note(ticket: Ticket, draft: DraftReply) -> InternalNote:
    # This is the side effect we do not want to run until the draft validates.
    return InternalNote(note_id=f"note_{ticket.ticket_id}", ticket_id=ticket.ticket_id)


@workflow
async def support_reply_debug(ctx: WorkflowContext, ticket_id: str) -> dict:
    ticket = await ctx.step(load_ticket, ticket_id)
    profile = await ctx.step(load_customer_profile, ticket.customer_id)
    classification = await ctx.step(classify_ticket, ticket, profile)
    draft = await ctx.step(draft_structured_reply, ticket, profile, classification)
    note = await ctx.step(create_internal_note, ticket, draft)

    return {
        "ticket_id": ticket.ticket_id,
        "note_id": note.note_id,
        "draft": draft.model_dump(),
    }
```

Import this module from `app.py` or your project package so the workflow is
registered when the worker starts.

## Run the failure

Trigger the workflow from another terminal:

```bash
agnt5 run support_reply_debug --input '{"ticket_id":"TCK-1001"}'
```

The run should fail in `draft_structured_reply`. List recent runs:

```bash
agnt5 inspect runs ls --status failed --limit 5
```

Then inspect the failed run:

```bash
agnt5 inspect runs describe <run-id>
agnt5 inspect trace -r <run-id> --verbose
```

In the trace, confirm the incident shape:

- `load_ticket` completed.
- `load_customer_profile` completed.
- `classify_ticket` completed.
- `draft_structured_reply` failed with a validation error.
- `create_internal_note` did not run.

That last point is the recovery line. A user-visible side effect has not
happened yet, so it is safe to patch the draft step and retry from the failed
boundary.

## Patch the failed step

Now make the draft step production-ready. Keep the raw model output visible,
attempt one bounded repair, then validate again.

```python
def repair_draft_payload(raw: str) -> str:
    # Keep this deliberately conservative. In production, make the repair
    # explicit and trace-visible rather than silently accepting bad data.
    if '"confidence"' not in raw:
        return raw.rstrip().rstrip("}") + ', "confidence": 0.62 }'
    return raw


@function
async def draft_structured_reply(
    ticket: Ticket,
    profile: CustomerProfile,
    classification: Classification,
) -> DraftReply:
    model_output = """
    {
      "body": "You're eligible for a refund. I can start that process now."
    }
    """

    try:
        return DraftReply.model_validate_json(model_output)
    except ValidationError:
        repaired = repair_draft_payload(model_output)
        return DraftReply.model_validate_json(repaired)
```

Restart the worker so the new function code is registered.

## Re-run and compare traces

Run the same input again:

```bash
agnt5 run support_reply_debug --input '{"ticket_id":"TCK-1001"}'
```

Inspect the new trace:

```bash
agnt5 inspect runs ls --limit 5
agnt5 inspect trace -r <new-run-id> --verbose
```

Compare it with the failed trace. The first three steps should have the same
inputs. The draft step should now return a valid `DraftReply`, and the
`create_internal_note` side effect should run once after validation succeeds.

## What replay proves

AGNT5 replay is what makes the trace trustworthy:

- Completed step results are journaled.
- Workflow body code can be re-entered after a crash or restart.
- Replay walks the same `ctx.step(...)` sequence.
- Completed steps return their recorded outputs instead of calling external
  systems again.
- The first step without a successful journal entry is where work resumes.

In this incident, replay tells you the failed run had not crossed the side
effect boundary. That is why the fix is safe.

## Turn the failure into a regression case

After patching the incident, keep the bad model output as an eval case. The eval
should fail if a future prompt, model, or parser change allows a draft without
`confidence` to pass validation.

At minimum, save:

- workflow input,
- raw model output,
- validation error,
- expected repaired output,
- expected side-effect behavior.

That eval case is the difference between "we fixed the incident" and "this
incident stays fixed."

## Production checklist

- Every external read, model call, and side effect is inside `ctx.step(...)`.
- The trace shows step input, output, error, and retry attempts.
- The failed step is before the first user-visible side effect.
- The patch changes the failing step only.
- The fixed trace proves the side effect runs once after validation.
- The malformed output is added to an eval dataset.

## Next steps

- [Retry AI workflow steps without duplicate side effects](/cookbooks/retry-without-duplicate-side-effects.md)
- [Turn a failed production AI run into an eval](/cookbooks/production-run-to-eval.md)
- [Debug AI workflows with traces, not scattered logs](/cookbooks/workflow-native-observability.md)

---

## Build a deep research agent

_Source: https://agnt5.com/cookbooks/deep-research-agent.md_

> Run long research jobs with search tools, streamed progress, trace inspection, and completion notices.

This cookbook builds a deep research agent for long-running jobs where progress,
durability, and traceability matter more than a single chat response.

## Scenario

A user asks for a competitive brief. The agent plans the work, searches the web,
reads selected sources, extracts notes, synthesizes a report, and sends a
completion notification.

## What you build

- A planner step.
- Search and fetch tools.
- Parallel source reading.
- Progress events for the UI.
- A final report artifact.
- A completion notification that is sent once.

## Workflow shape

```python
@workflow
async def deep_research(ctx: WorkflowContext, topic: str) -> ResearchResult:
    plan = await ctx.step(plan_research, topic)
    sources = await ctx.step(search_sources, plan.queries)
    notes = await ctx.step(read_sources, sources)
    report = await ctx.step(write_research_report, topic, notes)
    notification = await ctx.step(send_completion_once, report.artifact_id)
    return ResearchResult(report_id=report.artifact_id, notification_id=notification.id)
```

Each long call is isolated. If source reading fails halfway through, completed
work can be replayed from the journal.

## Progress model

Emit progress from step boundaries rather than from unstructured logs.

```json
{
  "phase": "reading_sources",
  "completed": 8,
  "total": 12,
  "run_id": "run_01JRESEARCH"
}
```

The UI can stream these updates while the trace remains the durable record.

## Production checks

- Search and fetch outputs are traceable.
- The report stores source citations or artifact IDs.
- Worker restarts do not lose progress.
- Completion notifications are idempotent.
- Failed source reads can be retried without restarting the whole report.

## Next steps

- [Build a durable research agent with approval and recovery](/cookbooks/durable-research-agent-approval-recovery.md)
- [Run any AI agent framework on a durable workflow runtime](/cookbooks/bring-your-own-agent-framework.md)
- [Debug AI workflows with traces, not scattered logs](/cookbooks/workflow-native-observability.md)

---

## Build a document processing pipeline

_Source: https://agnt5.com/cookbooks/document-processing.md_

> Extract structured fields, validate them, pause for review, and retry failed document steps safely.

Document workflows fail in predictable ways: bad scans, missing fields,
malformed model output, and partial external writes. This cookbook builds a
pipeline that makes each failure inspectable and recoverable.

## Scenario

An operations team uploads invoices. The workflow extracts fields, validates the
result, pauses for review when confidence is low, and stores approved data in a
system of record.

## What you build

- A document ingestion workflow.
- OCR or text extraction.
- Structured field extraction.
- Validation and confidence checks.
- Human review for exceptions.
- An idempotent write to the destination system.

## Workflow shape

```python
@workflow
async def process_invoice(ctx: WorkflowContext, document_id: str) -> InvoiceOutcome:
    document = await ctx.step(load_document, document_id)
    text = await ctx.step(extract_text, document)
    invoice = await ctx.step(extract_invoice_fields, text)
    validation = await ctx.step(validate_invoice, invoice)

    if validation.needs_review:
        decision = await ctx.wait_for_signal(
            "invoice_review",
            timeout="10d",
            metadata={"document_id": document_id, "issues": validation.issues},
        )
        invoice = decision.corrected_invoice

    receipt = await ctx.step(store_invoice_once, document_id, invoice)
    return InvoiceOutcome(status="stored", receipt_id=receipt.id)
```

The review path is part of the workflow, not an out-of-band spreadsheet.

## Validation rules

Use deterministic validation before asking another model to judge the output.

- Required fields are present.
- Totals add up.
- Currency is supported.
- Vendor is recognized.
- Confidence passes the threshold.

## Production checks

- Raw document, extracted text, structured output, and validation errors are in
  the trace.
- Low-confidence extractions pause for review.
- The store step uses a stable idempotency key.
- Reprocessing a document does not duplicate destination records.
- Corrected review output can become an eval case.

## Next steps

- [Build a data extraction workflow](/cookbooks/data-extraction.md)
- [Retry AI workflow steps without duplicate side effects](/cookbooks/retry-without-duplicate-side-effects.md)
- [Turn a failed production AI run into an eval](/cookbooks/production-run-to-eval.md)

---

## Build a durable human-approval AI workflow

_Source: https://agnt5.com/cookbooks/durable-human-approval-ai-workflow.md_

> Pause for approval, survive worker restarts, and execute the final side effect exactly once.

Human approval is the clearest demo of durable execution. The workflow starts,
does useful AI work, waits for a person, survives for hours or days, and resumes
when an approval signal arrives.

## Scenario

A support agent drafts a refund response and prepares a refund request. The
business rule is simple: the AI can draft and recommend, but a human must
approve before money moves.

## What you build

- A workflow that drafts an action with an agent.
- A durable approval pause.
- A signal that records approve, reject, or request-changes.
- A final side effect that executes once.
- A trace that shows the full decision path.

## Workflow shape

The workflow separates recommendation from execution.

```python
@workflow
async def refund_review(ctx: WorkflowContext, ticket_id: str) -> RefundOutcome:
    ticket = await ctx.step(load_ticket, ticket_id)
    customer = await ctx.step(load_customer, ticket.customer_id)
    recommendation = await ctx.step(draft_refund_recommendation, ticket, customer)

    decision = await ctx.wait_for_signal(
        "refund_decision",
        timeout="7d",
        metadata={"ticket_id": ticket.id, "amount": recommendation.amount},
    )

    if decision.status != "approved":
        return RefundOutcome(status="not_approved", reason=decision.reason)

    receipt = await ctx.step(issue_refund_once, ticket.id, recommendation.amount)
    return RefundOutcome(status="refunded", receipt_id=receipt.id)
```

The pause is workflow state, not process memory. The worker can restart while
the workflow is waiting.

## Approval payload

Keep the approval signal explicit. Do not pass free-form text as the only
decision record.

```json
{
  "status": "approved",
  "reviewer_id": "user_123",
  "reason": "Customer is inside the refund window.",
  "approved_amount": 4900
}
```

The trace should preserve the recommendation, the reviewer, the decision, and
the final side effect receipt.

## Side-effect guard

The final step should be idempotent. Use a key derived from the workflow run and
the business object.

```python
@function
async def issue_refund_once(ticket_id: str, amount: int) -> RefundReceipt:
    idempotency_key = f"refund:{ticket_id}:{amount}"
    return await stripe.refunds.create(
        payment_intent=lookup_payment(ticket_id),
        amount=amount,
        idempotency_key=idempotency_key,
    )
```

## Production checks

- Restart the worker while the workflow is waiting.
- Send the approval after the restart.
- Confirm the workflow resumes from the waiting point.
- Confirm duplicate approval signals do not create duplicate refunds.
- Confirm rejected decisions stop before the side-effect step.

## Next steps

- [Retry AI workflow steps without duplicate side effects](/cookbooks/retry-without-duplicate-side-effects.md)
- [Build a customer support agent](/cookbooks/customer-support-agent.md)
- [Build a durable research agent with approval and recovery](/cookbooks/durable-research-agent-approval-recovery.md)

---

## Build a durable research agent with approval and recovery

_Source: https://agnt5.com/cookbooks/durable-research-agent-approval-recovery.md_

> Checkpoint search, extraction, artifacts, and final human approval across a long-running report workflow.

Research agents are useful when they survive real work: slow searches, document
downloads, extraction failures, intermediate artifacts, and human approval
before the final report is sent.

## Scenario

A research agent investigates a vendor, gathers sources, extracts notes, drafts
a report, waits for approval, and then publishes the report to a workspace.

## What you build

- A multi-step research workflow.
- Checkpoints after search, fetch, extraction, synthesis, and approval.
- Artifact records for downloaded files and notes.
- A recovery path after a failed source fetch.
- Human approval before final publication.

## Workflow shape

The workflow is long-running, but each unit of work is small.

```python
@workflow
async def vendor_research(ctx: WorkflowContext, vendor: str) -> ResearchReport:
    plan = await ctx.step(plan_research, vendor)
    sources = await ctx.step(search_sources, plan)
    documents = await ctx.step(fetch_documents, sources)
    notes = await ctx.step(extract_notes, documents)
    draft = await ctx.step(write_report, vendor, notes)

    decision = await ctx.wait_for_signal(
        "report_approval",
        timeout="5d",
        metadata={"vendor": vendor, "draft_artifact_id": draft.artifact_id},
    )

    if decision.status != "approved":
        return ResearchReport(status="needs_changes", draft_id=draft.artifact_id)

    published = await ctx.step(publish_report_once, draft.artifact_id)
    return ResearchReport(status="published", url=published.url)
```

If the worker stops after fetching documents, replay resumes from the journaled
documents and continues at extraction.

## Artifact checkpoints

Store artifact references in the journal instead of large blobs.

```python
class ResearchArtifact(BaseModel):
    artifact_id: str
    kind: Literal["source", "notes", "draft", "report"]
    uri: str
    checksum: str
```

The trace should let a reviewer open the source list, extracted notes, and draft
without rerunning the agent.

## Recovery drill

Before shipping, force one source download to fail.

```bash
agnt5 runs replay --run-id run_01JRESEARCH --local
agnt5 runs resume run_01JRESEARCH
```

The recovered run should not repeat successful downloads, and the final report
should include a trace back to the notes and sources used.

## Production checks

- Every long external call is inside a step.
- Artifacts have stable IDs and checksums.
- A worker restart during approval does not lose the draft.
- The publish step is idempotent.
- Reviewers can inspect sources before approving.

## Next steps

- [Build a deep research agent](/cookbooks/deep-research-agent.md)
- [Build a durable human-approval AI workflow](/cookbooks/durable-human-approval-ai-workflow.md)
- [Debug and replay a failed AI workflow](/cookbooks/debug-production-run.md)

---

## Build a model comparison workflow

_Source: https://agnt5.com/cookbooks/model-comparison.md_

> Run the same case through multiple models, score outputs, and promote the release candidate.

Model changes are production changes. This cookbook builds a workflow for
comparing model candidates against the same inputs, scoring outputs, and
promoting a winner only when it clears the eval gate.

## Scenario

You want to move a classification workflow to a cheaper or stronger model. The
team needs evidence that quality does not regress on real production cases.

## What you build

- A candidate list of models.
- A replayable eval dataset.
- A comparison workflow that runs each case through each model.
- Deterministic and judge-based scorers.
- A release gate for promotion.

## Workflow shape

```python
@workflow
async def compare_models(ctx: WorkflowContext, case_id: str, models: list[str]) -> ModelComparison:
    case = await ctx.step(load_eval_case, case_id)
    outputs = []
    for model in models:
        output = await ctx.step(run_case_with_model, case, model)
        score = await ctx.step(score_model_output, case.expected, output)
        outputs.append(ModelOutput(model=model, output=output, score=score))
    return ModelComparison(case_id=case_id, outputs=outputs)
```

For larger datasets, fan out by case and aggregate scores in a separate step.

## Scoring strategy

Use deterministic scorers when the expected output is structured:

- exact class match,
- required fields present,
- forbidden terms absent,
- citation coverage.

Use an LLM judge for subjective dimensions, but keep the judge prompt versioned
and trace-visible.

## Promotion checks

- Candidate model beats or matches baseline on critical cases.
- Cost and latency stay inside thresholds.
- Failures link to traces for inspection.
- Known production failures are included in the dataset.
- CI blocks the release when score drops below the threshold.

## Next steps

- [Turn a failed production AI run into an eval](/cookbooks/production-run-to-eval.md)
- [Build a data extraction workflow](/cookbooks/data-extraction.md)
- [Debug and replay a failed AI workflow](/cookbooks/debug-production-run.md)

---

## Turn a failed production AI run into an eval

_Source: https://agnt5.com/cookbooks/production-run-to-eval.md_

> Capture a bad production run, convert it into an eval case, and compare fixed prompts before release.

The most useful eval cases often start as production failures. This cookbook
shows how to capture a bad run, preserve its prompt, tools, state, and output,
then replay it against a fixed prompt or model before promoting the change.

## Scenario

A workflow classifies enterprise support tickets. A customer reports that a
security-sensitive ticket was routed to the wrong queue. The run exists in
production with the original input, tool results, and model output.

## What you build

- A production failure review flow.
- An eval case derived from the failed run.
- A scorer that captures the expected behavior.
- A replay comparison between current and candidate workflow versions.
- A promotion gate based on the fixed case.

## Capture the run

Start from the production run, not from a handwritten reproduction.

```bash
agnt5 runs describe run_01JSECURITY
agnt5 eval cases create --from-run run_01JSECURITY --dataset support-routing-regressions
```

The generated case should include:

- workflow input,
- relevant tool results,
- the model output,
- the expected routing outcome,
- metadata linking back to the production run.

## Write the scorer

Use a deterministic scorer for routing when possible.

```python
@scorer(name="routes_security_ticket")
def routes_security_ticket(ctx: EvalContext) -> ScorerResultPy:
    output = SupportRoute.model_validate(ctx.output)
    passed = output.queue == "security" and output.severity in {"high", "critical"}
    return ScorerResultPy(score=1.0 if passed else 0.0, passed=passed)
```

The scorer turns the production failure into a guardrail that runs on every
future prompt, model, or tool change.

## Replay the candidate

Change the routing prompt, model, or tool policy in a candidate workflow
version. Replay the captured case before promoting.

```bash
agnt5 eval run support-routing-regressions --workflow-version candidate
agnt5 eval compare --baseline production --candidate candidate
```

The comparison should show the failed case passing without regressing the rest
of the dataset.

## Production checks

- The eval case links back to the original run.
- The case contains enough state to reproduce the failure offline.
- The scorer fails on the production version.
- The scorer passes on the candidate version.
- CI or a release checklist blocks promotion if this case regresses.

## Next steps

- [Build a model comparison workflow](/cookbooks/model-comparison.md)
- [Debug and replay a failed AI workflow](/cookbooks/debug-production-run.md)
- [Build a customer support agent](/cookbooks/customer-support-agent.md)

---

## Build a RAG chatbot with memory

_Source: https://agnt5.com/cookbooks/rag-chatbot-memory.md_

> Retrieve knowledge, preserve user context, isolate tenants, and trace each answer back to evidence.

This cookbook builds a RAG chatbot that behaves like a production workflow:
tenant-aware retrieval, durable memory updates, traceable evidence, and
recoverable answer generation.

## Scenario

A SaaS user asks a product question. The chatbot retrieves relevant docs,
combines them with user memory, generates an answer, and records useful context
for the next turn.

## What you build

- Tenant-scoped retrieval.
- Session memory lookup.
- Evidence-grounded answer generation.
- A memory update step.
- Trace evidence for every answer.

## Workflow shape

```python
@workflow
async def answer_chat_turn(ctx: WorkflowContext, request: ChatRequest) -> ChatAnswer:
    memory = await ctx.step(load_session_memory, request.session_id)
    passages = await ctx.step(retrieve_docs, request.tenant_id, request.message)
    answer = await ctx.step(generate_grounded_answer, request.message, memory, passages)
    await ctx.step(update_memory_once, request.session_id, request.message, answer)
    return answer
```

The retrieval step must receive the tenant ID. Do not rely on global vector
indexes without tenant filters.

## Evidence model

Return citations as structured data.

```python
class ChatAnswer(BaseModel):
    answer: str
    citations: list[DocumentCitation]
    memory_updates: list[str]
```

This lets the UI show citations and lets the trace explain the answer.

## Production checks

- Direct HTTP calls include `X-TENANT-ID` and `X-DEPLOYMENT-ID`.
- Retrieval filters by tenant.
- The answer stores citations.
- Memory updates are idempotent per turn.
- A bad answer can be replayed with the same retrieved passages.

## Next steps

- [Build a customer support agent](/cookbooks/customer-support-agent.md)
- [Build a data extraction workflow](/cookbooks/data-extraction.md)
- [Turn a failed production AI run into an eval](/cookbooks/production-run-to-eval.md)

---

## Retry AI workflow steps without duplicate side effects

_Source: https://agnt5.com/cookbooks/retry-without-duplicate-side-effects.md_

> Use idempotency keys and journaled receipts so retries do not duplicate emails, tickets, or payments.

Retries are necessary in production AI workflows. They are also dangerous when a
step talks to Stripe, sends email, creates a ticket, or fires a webhook. This
cookbook shows the pattern for retrying safely after a side effect may already
have happened.

## Scenario

An AI workflow classifies a support request and creates a ticket in a CRM. The
CRM request succeeds, but the network connection drops before your worker sees
the response. The runtime retries the step.

Without an idempotency pattern, the customer gets two tickets. With the pattern,
the retry returns the original receipt.

## What you build

- A workflow with retryable external side effects.
- Stable idempotency keys for each side-effect step.
- A receipt that is stored in the AGNT5 journal.
- Retry behavior that returns the original external object.
- Trace checks that prove only one side effect happened.

## Workflow shape

Keep side effects small and named.

```python
@workflow
async def triage_and_create_ticket(ctx: WorkflowContext, inbound: InboundRequest) -> TicketResult:
    classification = await ctx.step(classify_request, inbound)
    ticket = await ctx.step(create_crm_ticket_once, inbound.request_id, classification)
    email = await ctx.step(send_ack_email_once, inbound.request_id, ticket.id)
    return TicketResult(ticket_id=ticket.id, email_id=email.id)
```

`create_crm_ticket_once` and `send_ack_email_once` are the only steps that touch
external systems.

## Idempotency key

Base the key on the business object, not on the retry attempt.

```python
def crm_idempotency_key(request_id: str) -> str:
    return f"crm-ticket:{request_id}"


@function
async def create_crm_ticket_once(
    request_id: str,
    classification: Classification,
) -> CrmTicket:
    return await crm.create_ticket(
        subject=classification.subject,
        priority=classification.priority,
        idempotency_key=crm_idempotency_key(request_id),
    )
```

If the CRM supports idempotency keys, use its native support. If it does not,
store a receipt in your own database keyed by the same value before returning.

## Journaled receipt

The step should return the external receipt, not just `true`.

```python
class CrmTicket(BaseModel):
    id: str
    idempotency_key: str
    created_at: datetime
```

On replay, AGNT5 reads this receipt from the journal. The workflow can continue
without creating the ticket again.

## Production checks

- Inject a timeout after the CRM creates the ticket.
- Confirm the retry uses the same idempotency key.
- Confirm only one CRM ticket exists.
- Confirm the AGNT5 trace shows the failed attempt and the successful retry.
- Confirm replay returns the journaled ticket receipt.

## Next steps

- [Build a webhook triage agent](/cookbooks/webhook-triage-agent.md)
- [Build a durable human-approval AI workflow](/cookbooks/durable-human-approval-ai-workflow.md)
- [Debug and replay a failed AI workflow](/cookbooks/debug-production-run.md)

---

## Build a Slack deep research agent

_Source: https://agnt5.com/cookbooks/slack-deep-research-agent.md_

> Trigger a fully automated multi-step research pipeline from a Slack message and post the findings back to the channel, no human approval required.

Mention your bot in Slack with a topic and it runs a full research pipeline and replies with a report — no approval, no polling.

<Mermaid title="How the bot works" code={`flowchart TD
    A["Slack mention: ResearchBot quantum computing breakthroughs 2025"]
    A --> B["AGNT5 starts a workflow run"]
    B --> C["ScopingAgent plans 3 to 6 subtopics"]
    C --> D["ResearchAgent fetches Wikipedia and web pages"]
    D --> E["WritingAgent writes a Slack summary"]
    E --> F["Bot posts the report as a threaded reply"]`} />

---

## What you will learn

- How to trigger a durable multi-step workflow from a Slack event.
- How to use three specialised agents in a sequential pipeline.
- How to post results back to a Slack thread from a workflow step.
- How checkpointing lets the pipeline resume after a worker restart.

## What you build

- A Slack App connected to AGNT5 via the Studio integration.
- A three-agent research pipeline (scoping, research, writing) triggered by `app_mention` and `message` events.
- A step that posts the finished report back to the originating channel thread.

---

## Prerequisites

- An AGNT5 account. Sign up at [app.agnt5.com](https://app.agnt5.com).
- Python 3.11+ and [uv](https://docs.astral.sh/uv/getting-started/installation/).
- An [OpenAI API key](https://platform.openai.com/api-keys) (the template uses `gpt-4o-mini`).
- A Slack workspace where you can create and install apps.

---

## Step 1: Install the CLI

Follow the [CLI install guide](/docs/install-cli.md) to install `agnt5` and authenticate. Come back here when `agnt5 auth status` confirms you are signed in.

---

## Step 2: Create the project

```bash
agnt5 create --template python/slack_deep_research my-research-bot
cd my-research-bot
uv sync
```

---

## Step 3: Configure environment variables

```bash
cp .env.example .env
```

Open `.env` and set your OpenAI key:

```bash
OPENAI_API_KEY="sk-..."
```

---

## Step 4: Set up the Slack App and Studio integration

Follow the [Slack integration guide](/docs/integrations/event-sources/slack.md) to create your Slack app and connect it to AGNT5 in Studio. When configuring the app, make sure to:

- Add bot scopes: `app_mentions:read`, `channels:history`, and `chat:write` (needed to post the report back).
- Subscribe to bot events: `app_mention` and `message.channels`.

Come back here once Studio shows the integration as active.

---

## Step 5: Deploy

```bash
agnt5 deploy
```

The CLI builds the container image, pushes it to the registry, and creates the deployment. Once it completes, your workflow is live and listening for Slack events.

---

## Step 6: Test the bot in Slack

Invite the bot to a channel, then mention it with a research topic:

```
/invite @Research Bot

@Research Bot quantum computing breakthroughs 2025
```

The research pipeline starts immediately. When it finishes (typically 30 to 90 seconds) the report arrives as a threaded reply.

Open Studio and go to **Runs** to inspect the execution. You will see the full Slack envelope, each step (`plan_research`, `conduct_research`, `write_report`) with its input and output, and the Slack post result (`posted: true`).

---

## How it works

### End-to-end flow

<Mermaid title="End-to-end flow" code={`flowchart TD
    A["Slack event: app_mention or message"]
    A --> B["AGNT5 verifies signature and starts a run"]
    B --> C["slack_deep_research workflow starts"]
    C --> D["Parse envelope: text, channel, user, thread_ts"]
    D --> E{should process}
    E -- "bot or empty" --> F["skip: workflow exits"]
    E -- "valid user message" --> G["Extract topic, strip mention prefix"]
    G --> H["plan_research: ScopingAgent"]
    H --> I["conduct_research: ResearchAgent"]
    I --> J["write_report: WritingAgent"]
    J --> K["chat.postMessage: threaded reply"]`} />

Each `ctx.step` is checkpointed in the durable journal. A worker restart at any point replays from the last completed step — the research already gathered is not re-run.

### The three-stage pipeline

| Stage | Agent | What it does |
|---|---|---|
| Plan | `ScopingAgent` | Breaks the topic into 3 to 6 subtopics with a research strategy |
| Research | `ResearchAgent` | Searches Wikipedia and fetches web pages for each subtopic |
| Write | `WritingAgent` | Synthesises findings into a Slack-formatted summary under 2000 characters |

### Bot loop guard

The workflow checks the envelope before starting the pipeline. Messages from bots or with unsupported subtypes are skipped to prevent the bot from replying to itself:

```python
def _should_process(message: dict) -> tuple[bool, str]:
    if message.get("bot_id"):
        return False, "bot message"
    if message.get("subtype"):
        return False, f"unsupported subtype: {message['subtype']}"
    if not (message.get("message") or "").strip():
        return False, "empty message"
    return True, ""
```

### Posting back to Slack

The report is posted with `chat.postMessage`. Passing `thread_ts` threads the reply under the original message so the conversation stays organised:

```python
payload = {"channel": channel, "text": report}
if thread_ts:
    payload["thread_ts"] = thread_ts
```

---

## Extend it

- **Add more sources**: give `ResearchAgent` a web search tool alongside Wikipedia for broader coverage.
- **Multi-turn conversation**: store `run_id` keyed by `thread_ts` and use `ctx.state` to carry context across follow-up mentions in the same thread.
- **Longer reports**: increase `WritingAgent`'s `max_tokens` and split the output across multiple Slack messages if it exceeds 4000 characters.
- **Different trigger**: swap `slack.app_mention` for `slack.reaction_added` to kick off research when a user reacts to a message with a specific emoji.

---

## Production checklist

- **Idempotency**: Slack retries failed deliveries. Use `event.client_msg_id` from the envelope body as an idempotency key to avoid duplicate research jobs.
- **Bot loop guard**: the `bot_id` check in `_should_process` prevents the bot from replying to its own posts. Verify it is in place before going live.
- **Rate limits**: the research agent retries Wikipedia 429s with exponential back-off. Monitor OpenAI rate limits for high-volume deployments.
- **Secrets**: never commit `.env`. Inject secrets in your deployment environment.

---

## Next steps

- [Slack integration reference](/docs/integrations/event-sources/slack.md): envelope structure, all event types, signature verification, and delivery semantics.
- [Build a deep research agent](/cookbooks/deep-research-agent.md): the same pipeline without the Slack trigger.
- [Build a durable research agent with approval and recovery](/cookbooks/durable-research-agent-approval-recovery.md): add a human approval gate before the report is posted.
- [Debug AI workflows with traces, not scattered logs](/cookbooks/workflow-native-observability.md): inspect step-level inputs, outputs, and model calls.

---

## Build a Slack deep research bot (in-depth)

_Source: https://agnt5.com/cookbooks/slack-deep-research-agent-v2.md_

> A deep dive into building a durable multi-agent research pipeline triggered by Slack mentions, covering fire-and-forget webhooks, checkpointed steps, three-agent decomposition, and live debugging in Studio.

Slack gives you 3 seconds to respond to a webhook before it retries. A research pipeline (scoping subtopics, querying Wikipedia, synthesising a report) takes 30–90 seconds. Handling both in the same request handler guarantees timeouts and duplicate runs.

AGNT5 solves this with a **fire-and-forget** model. The webhook handler records the incoming event and replies `200 OK` in under a second. A durable workflow run starts in the background, executes each research stage as a checkpointed step, and calls `chat.postMessage` when the report is ready. If the worker is restarted mid-pipeline, the run replays from the last completed checkpoint with no repeated LLM calls and no lost work.

This cookbook walks through the complete implementation using the `python/slack_deep_research` template. You will understand every moving part: how the Slack envelope is parsed, why three agents produce better results than one monolithic prompt, what "durable" actually means when a worker crashes, and how to use Studio's Events view to debug the bot without adding any logging infrastructure.

<DocsImage
  src="/docs/integrations/slack-cookbook-2.png"
  alt="End-to-end flow diagram: user mentions @ResearchBot in Slack, Slack sends an app_mention webhook, AGNT5 records the event and returns 200 OK in under 1 second. The Deep Research Workflow starts slack_deep_research, parses the request, checks validity — invalid messages exit early, valid messages extract the topic and remove the @mention prefix. The Research Pipeline then runs ScopingAgent, ResearchAgent, and WritingAgent in sequence, finishing with chat.postMessage posting a threaded reply in Slack."
  caption="The fire-and-forget pattern: AGNT5 acknowledges the Slack webhook immediately, then runs the full research pipeline asynchronously and posts the report back as a threaded reply."
  width={1344}
  height={1316}
/>

---

## What you will learn

- How the **fire-and-forget webhook pattern** decouples Slack's 3-second timeout from a 30–90-second pipeline.
- How `ctx.step()` **checkpoints** each stage so a worker restart never re-runs completed work.
- Why a **three-agent pipeline** (scope → research → write) produces more reliable, testable results than a single monolithic prompt.
- How the **bot loop guard** prevents the bot from replying to its own posts and triggering infinite runs.
- How to use **Studio Events** to see every incoming Slack event, inspect its raw payload, and trace it through to the workflow run and individual step outputs.

## What you build

- A Slack App connected to AGNT5 via the Studio integration.
- Three specialised [agents](/docs/build/agents.md): `ScopingAgent`, `ResearchAgent`, `WritingAgent`.
- A durable [workflow](/docs/build/workflows.md) triggered by `slack.app_mention` and `slack.message` events that posts a threaded research report back to Slack.

---

## Core concepts

### Durable workflows and checkpointing

Every call to `ctx.step()` in AGNT5 is a checkpoint. Before executing the step function, AGNT5 writes an intent record to the durable journal. After the function returns, it writes the output alongside it. If the worker process is killed or restarted at any point, the workflow replays. Completed steps return their stored output immediately. Only the pending steps execute again.

For a research pipeline this matters significantly. Suppose the worker restarts after `conduct_research` completes but before `write_report` starts:

```
Without checkpointing:
  All three stages re-run → repeated Wikipedia requests + LLM calls → extra cost and latency

With checkpointing (what AGNT5 does):
  plan_research     → journal hit, return stored output instantly
  conduct_research  → journal hit, return stored output instantly
  write_report      → not in journal yet, execute normally
```

Design around step boundaries: put meaningful work inside `ctx.step()` calls, not between them.

### Multi-agent decomposition

A single "research and summarise this topic for Slack" prompt has to plan, search, and write inside one context window. It cannot be evaluated in isolation, and when the output is poor it is hard to determine whether the planning, the research, or the writing was the weak link.

Breaking the task into three agents with distinct responsibilities solves all three problems:

| Agent | Responsibility | Why it is isolated |
|---|---|---|
| `ScopingAgent` | Plan 3–6 subtopics with a research strategy | Tuned and evaluated without touching research logic |
| `ResearchAgent` | Fetch Wikipedia and web pages for each subtopic | Has access to [tools](/docs/build/tools.md). The other agents do not. |
| `WritingAgent` | Synthesise findings into a Slack-safe report | Enforces format constraints independently of research quality |

Each agent also has its own context window. `ResearchAgent` receives the research plan and nothing else. It does not carry the writing instructions, which would waste tokens and add noise.

### The fire-and-forget webhook pattern

When Slack delivers an event, AGNT5 parses the incoming HTTP request, records the event to the journal, and returns `200 OK` before the workflow function executes a single line. Slack sees a fast response and stops retrying. The workflow runs asynchronously with no connection to the original HTTP request. When the pipeline finishes it posts back to Slack itself.

This means:
- **No Slack timeouts.** The 3-second acknowledgement window is irrelevant to the pipeline duration.
- **No polling or job queues.** The durable journal is the queue.
- **Retry-safe.** AGNT5 uses the event's unique ID to deduplicate retried Slack deliveries.

---

## Prerequisites

- An AGNT5 account. Sign up at [app.agnt5.com](https://app.agnt5.com).
- Python 3.11+ and [uv](https://docs.astral.sh/uv/getting-started/installation/).
- An [OpenAI API key](https://platform.openai.com/api-keys): the template uses `gpt-4o-mini` for all three agents.
- A Slack workspace where you can create and install apps.

---

## Step 1: Install the CLI

```bash
agnt5 auth login
agnt5 auth status   # confirms: Signed in as <your-email>
```

Follow the [CLI install guide](/docs/install-cli.md) if you do not have `agnt5` installed yet.

**Why this step matters:** The CLI authenticates your local machine and gives `agnt5 deploy` the credentials it needs to push your container image to the AGNT5 registry and register the deployment.

---

## Step 2: Create the project

```bash
agnt5 create --template python/slack_deep_research my-research-bot
cd my-research-bot
uv sync
```

**Why this step matters:** The template scaffolds the complete project: `app.py` (worker entry point), `src/slack_deep_research/` ([agents](/docs/build/agents.md), [functions](/docs/build/functions.md), [tools](/docs/build/tools.md), [workflows](/docs/build/workflows.md)). You can deploy immediately without writing boilerplate. The `agnt5.yaml` at the root defines the entry command and language version for reproducible builds.

The project structure you get:

```
my-research-bot/
├── app.py                          # Worker entry point — registers all components
├── agnt5.yaml                      # Deployment config (entry command, language version)
├── pyproject.toml
├── .env.example                    # Environment variable template — copy to .env
└── src/slack_deep_research/
    ├── agents.py                   # ScopingAgent, ResearchAgent, WritingAgent
    ├── functions.py                # plan_research, conduct_research, write_report
    ├── tools.py                    # wikipedia_search_tool, fetch_webpage_tool
    └── workflows.py                # slack_deep_research workflow + envelope helpers
```

---

## Step 3: Configure environment variables

```bash
cp .env.example .env
```

Open `.env` and add your OpenAI key:

```bash
OPENAI_API_KEY="sk-..."
```

**Why this step matters:** All three agents call `openai/gpt-4o-mini`. One key covers the entire pipeline. `SLACK_BOT_TOKEN` is injected at runtime by the AGNT5 Slack integration. You do not add it here.

---

## Step 4: Set up the Slack App and Studio integration

Follow the [Slack integration guide](/docs/integrations/event-sources/slack.md) to create your Slack app and connect it to AGNT5 in Studio. When configuring the app:

- **Bot token scopes:** `app_mentions:read`, `channels:history`, `chat:write`
- **Event subscriptions:** `app_mention` and `message.channels`

When adding the integration in Studio, you will be prompted to choose three things: the **deployment** that receives the events, the **event type** (app mention or message), and the **target** workflow to trigger. Select the deployment you created, the event types your bot should respond to, and `slack_deep_research` as the target workflow.

<DocsImage
  src="/docs/integrations/slack-integration-target-light.png"
  darkSrc="/docs/integrations/slack-integration-target-dark.png"
  alt="Studio Slack integration configuration panel showing deployment selector, event type selector, and target workflow selector set to slack_deep_research."
  caption="Select the deployment, event type, and target workflow in the Studio integration panel. AGNT5 routes every matching Slack event to the chosen workflow automatically."
  width={1600}
  height={900}
/>

**Why this step matters:** `app_mentions:read` and `message.channels` instruct Slack to deliver events to AGNT5. `chat:write` is the scope `chat.postMessage` uses to post the finished report. The Studio integration handles Slack signature verification automatically. You do not implement that yourself.

Come back here once Studio shows the integration as **Active**.

---

## Step 5: Deploy

```bash
agnt5 deploy
```

The CLI builds a container image from your project directory, pushes it to the AGNT5 registry, and creates a live deployment. Your workflow is now listening for Slack events.

**Why this step matters:** AGNT5 runs your worker as a managed container it can restart, scale, and recover automatically. Deploying is what connects your local code to the Studio integration that receives Slack events.

---

## Step 6: Test the bot

Invite the bot to a channel, then mention it with a research topic:

```
/invite @ResearchBot

@ResearchBot evolution of AI
```

The pipeline starts immediately. A threaded reply arrives in 30–90 seconds depending on how many subtopics the scoping agent generates and how quickly Wikipedia responds.

<DocsImage
  src="/docs/integrations/slack-research.png"
  alt="Slack channel showing the deep-research-bot replying in a thread to 'evolution of AI' with an Executive Summary, Key Findings, and Sources sections."
  caption="The bot posts a structured research report as a threaded reply. The report includes an Executive Summary, Key Findings, and cited Wikipedia sources."
  width={1400}
  height={857}
/>

Open **Studio → Events** to see the incoming event record, and **Studio → Runs** to watch each `ctx.step()` execute in real time.

---

## How it works

### Parsing the Slack envelope

Every Slack event arrives as a nested JSON envelope. The workflow receives it as `**envelope` and passes it through a chain of helpers to extract the fields the pipeline needs:

```python
# workflows.py
def _extract_slack_message(envelope: dict[str, Any]) -> dict[str, str]:
    body = _parse_webhook_body(envelope)
    slack_event = _nested_dict(body, "event")

    # Text lives in different locations for app_mention vs message events
    text = (
        _first_string(slack_event, "text")
        or _first_string(body, "text")
        or _first_string(envelope, "text")
    )

    return {
        "event_type": ...,
        "message":   text,
        "channel":   _first_string(slack_event, "channel") or _first_string(body, "channel"),
        "user":      _first_string(slack_event, "user", "username", "bot_id") or ...,
        "subtype":   _first_string(slack_event, "subtype"),
        "bot_id":    _first_string(slack_event, "bot_id"),
        "thread_ts": _first_string(slack_event, "thread_ts", "ts"),
    }
```

The fallback chain (`slack_event → body → envelope`) exists because the envelope shape differs slightly between `app_mention` and `message` event types. `thread_ts`, the timestamp of the original message, is what makes `chat.postMessage` attach the reply as a thread rather than a new top-level message in the channel.

### The bot loop guard

Before starting the pipeline the workflow checks whether the event should be processed:

```python
# workflows.py
def _should_process(message: dict[str, str]) -> tuple[bool, str]:
    if message.get("bot_id"):
        return False, "bot message"
    if message.get("subtype"):
        return False, f"unsupported subtype: {message['subtype']}"
    if not (message.get("message") or "").strip():
        return False, "empty message"
    return True, ""
```

Without this guard the bot would receive its own `chat.postMessage` delivery as an event, start a new research run on the report text, post another reply, and loop indefinitely. The `bot_id` field is set by Slack on every message sent via a bot token. Checking it is the reliable way to break the cycle.

Events that fail this check return `{"status": "skipped", "reason": "..."}` and appear in Studio → Events with a **Skipped** badge.

### Extracting the research topic

`app_mention` events include the `<@UXXXXXXX>` mention token prepended to the message text. The `_extract_topic` function strips it before passing the topic to the pipeline so agents see clean input:

```python
# workflows.py
def _extract_topic(message: dict[str, str]) -> str:
    text = (message.get("message") or "").strip()
    # Strip <@U12345> prefix that Slack adds to app_mention events
    text = re.sub(r"^<@[A-Z0-9]+>\s*", "", text).strip()
    # Remove an optional leading "research" keyword
    topic = re.sub(r"^research\s+", "", text, flags=re.IGNORECASE).strip()
    return topic or text
```

`"@ResearchBot evolution of AI"` becomes `"quantum computing breakthroughs 2025"` before it reaches `ScopingAgent`.

### The three-stage pipeline

The workflow runs three `ctx.step()` calls in sequence. Each call is a durable checkpoint. Its output is stored in the journal before the next step begins:

```python
# workflows.py
research_plan     = await ctx.step(_plan_research,     topic)
research_findings = await ctx.step(_conduct_research,  topic, research_plan)
report            = await ctx.step(_write_report,      topic, research_plan, research_findings)
```

**Stage 1: ScopingAgent (`plan_research`)**

`ScopingAgent` receives only the raw topic and produces a structured plan with 3–6 subtopics. Its system prompt requires every response to start with `PLAN:`, a structured output contract the function strips before passing downstream:

```python
# functions.py
@function(name="plan_research")
async def _plan_research(ctx: FunctionContext, topic: str) -> str:
    current_date = datetime.now(timezone.utc).strftime("%Y-%m-%d")
    prompt = f"""Today's date is {current_date}.

Research topic: {topic}

Create a structured research plan for this topic:
1. Break it into 3-6 manageable subtopics
2. Define the research strategy for each subtopic
3. Make reasonable assumptions if the topic is vague or ambiguous
4. Start your response with "PLAN:" followed by the structured plan"""

    result = await scoping_agent.run(prompt, context=ctx)
    plan = result.output
    if plan.strip().startswith("PLAN:"):
        plan = plan.replace("PLAN:", "", 1).strip()
    return plan
```

Why plan first? Without an explicit plan, `ResearchAgent` decides what to search for at generation time while simultaneously running tool calls. This leads to uneven subtopic coverage. An upfront plan commits a complete research strategy before any searching begins, and it is stored as a checkpoint so you can inspect it in Studio even if later stages fail.

The agent definition enforces the output format via its system prompt:

```python
# agents.py
scoping_agent = Agent(
    name="ScopingAgent",
    model="openai/gpt-4o-mini",
    instructions="""You are a research scoping specialist who structures research requests into actionable plans.

Your responsibilities:
1. Analyze the research topic and make reasonable assumptions if anything is ambiguous
2. Create a structured research plan with 3-6 subtopics that comprehensively covers the topic
3. If the topic mentions acronyms or specialized terms, include them as subtopics to research

Guidelines for research planning:
- Break complex topics into 3-6 manageable subtopics
- For vague topics, interpret them broadly and cover the most relevant aspects
- Define a clear research strategy for each subtopic
- Prioritize reliable sources (Wikipedia, academic content, official documentation)
- Make reasonable assumptions rather than asking for clarification

Output format:
PLAN:
[Structured research plan with subtopics and strategy]

Always start your response with "PLAN:" followed by the research plan.""",
    max_tokens=8192,
)
```

**Stage 2: ResearchAgent (`conduct_research`)**

`ResearchAgent` receives the topic and the research plan. It has two tools, `wikipedia_search_tool` and `fetch_webpage_tool`, and uses them to gather evidence for each planned subtopic:

```python
# agents.py
research_agent = Agent(
    name="ResearchAgent",
    model="openai/gpt-4o-mini",
    instructions="""You are a systematic research specialist who gathers comprehensive information.

Your responsibilities:
1. Execute research according to the provided research plan
2. Use Wikipedia as the primary source for reliable information
3. Supplement with web searches for additional context when needed
4. Organize findings in a clear, structured format

Research guidelines:
- Start with Wikipedia searches for each subtopic
- Verify information across multiple sources when possible
- Focus on factual information, data, and verifiable details
- Cite sources clearly (include URLs and titles)
- Organize findings by subtopic for easy reference

Output format:
For each subtopic, provide:
## [Subtopic Name]

**Sources:**
- [Source 1: Title and URL]

**Key Findings:**
- [Finding 1]
- [Finding 2]

---
Continue this format for all subtopics.""",
    tools=[wikipedia_search_tool, fetch_webpage_tool],
    max_tokens=8192,
)
```

`wikipedia_search_tool` queries the Wikipedia Search API and handles rate limits with exponential back-off:

```python
# tools.py
@tool(auto_schema=True)
async def wikipedia_search_tool(ctx: Context, query: str, max_results: int = 3) -> str:
    """Search Wikipedia for articles related to the research query.

    Queries the Wikipedia Search API and returns formatted results with
    titles, article URLs, and snippet previews.
    """
    max_retries = 3
    for attempt in range(max_retries):
        response = requests.get(base_url, params=params, headers=headers, timeout=30)

        if response.status_code == 429:
            wait = 2 ** attempt * 3   # 3s → 6s → 12s
            ctx.logger.warning(
                f"Wikipedia rate-limited (429), retrying in {wait}s (attempt {attempt + 1}/{max_retries})"
            )
            await asyncio.sleep(wait)
            continue

        response.raise_for_status()
        # parse and return formatted results ...
```

`fetch_webpage_tool` strips scripts, ads, and navigation elements from HTML using BeautifulSoup, then returns up to 8 000 characters of main content:

```python
# tools.py
@tool(auto_schema=True)
async def fetch_webpage_tool(ctx: Context, url: str) -> str:
    """Fetch and extract text content from a webpage for research purposes.

    Retrieves the HTML page at the given URL, strips non-content elements,
    and returns clean text truncated to 8 000 chars.
    """
    for element in soup(["script", "style", "nav", "footer", "header", "aside", "noscript", "iframe"]):
        element.decompose()

    # Prefer <main> or <article> over the full body
    main_content = (
        soup.find("main")
        or soup.find("article")
        or soup.find(attrs={"class": ["content", "main-content", "article-content"]})
        or soup.find("div", attrs={"id": ["content", "main", "article"]})
        or soup.find("body")
    )

    max_chars = 8000
    if len(text) > max_chars:
        truncated = text[:max_chars]
        last_sentence = truncated.rfind(".")
        if last_sentence > max_chars * 0.8:
            text = truncated[:last_sentence + 1] + " ... [truncated]"
        else:
            text = truncated + " ... [truncated]"
```

8 000 characters is enough for an agent to extract key facts per subtopic without overflowing the context window when multiple pages are fetched across 3–6 subtopics.

**Stage 3: WritingAgent (`write_report`)**

`WritingAgent` receives the topic, plan, and full research findings. Its system prompt enforces Slack's `mrkdwn` formatting dialect because Slack does not render standard CommonMark:

```python
# agents.py
writing_agent = Agent(
    name="WritingAgent",
    model="openai/gpt-4o-mini",
    instructions="""You are a writing specialist who synthesizes research into clear, concise summaries.

Your responsibilities:
1. Transform research findings into a well-structured summary suitable for Slack
2. Keep the report concise — the executive summary and key takeaways are most important
3. Use plain text formatting that renders well in Slack (avoid HTML, use * for bold, use - for bullets)

Report structure:
*[Research Topic]*

*Executive Summary*
[2-3 sentences overview]

*Key Findings*
- [Finding 1]
- [Finding 2]
(up to 5 most important findings)

*Sources*
- [Source Name]: [URL]
(top 3-5 sources)

Keep the total response under 2000 characters so it fits cleanly in a Slack message.
Do NOT use markdown headers (##), HTML, or tables — plain text only.""",
    max_tokens=4096,
)
```

The 2 000-character limit is deliberate: Slack truncates messages at 4 000 characters and renders better when messages are concise. The agent is instructed to use `*bold*` (Slack `mrkdwn`) not `**bold**` (CommonMark) and `-` for bullets rather than `*` to avoid ambiguity with bold markers.

### Posting back to Slack

The report is posted with `chat.postMessage`. Passing `thread_ts` threads the reply under the original mention:

```python
# workflows.py
async def _post_to_slack(
    ctx: WorkflowContext,
    channel: str,
    text: str,
    thread_ts: str | None,
    bot_token: str,
) -> dict[str, Any]:
    payload: dict[str, Any] = {"channel": channel, "text": text}
    if thread_ts:
        payload["thread_ts"] = thread_ts   # attaches as a thread reply

    try:
        async with httpx.AsyncClient(timeout=15) as client:
            response = await client.post(
                "https://slack.com/api/chat.postMessage",
                headers={
                    "Authorization": f"Bearer {bot_token}",
                    "Content-Type": "application/json; charset=utf-8",
                },
                json=payload,
            )
    except httpx.HTTPError as exc:
        ctx.logger.warning(f"Slack post failed: {exc}")
        return {"posted": False, "reason": exc.__class__.__name__}

    try:
        data = response.json()
    except ValueError:
        data = {"ok": False, "error": response.text[:200]}

    if response.status_code >= 400 or not data.get("ok"):
        reason = str(data.get("error") or response.status_code)
        ctx.logger.warning(f"Slack post failed: {reason}")
        return {"posted": False, "reason": reason}

    return {"posted": True, "ts": data.get("ts", "")}
```

`thread_ts` is the `ts` of the original message. If it is absent (e.g., the event came from a DM with no prior message) the reply is posted as a new top-level message. The step returns `{"posted": true, "ts": "..."}` on success, visible in the Studio run output so you can confirm delivery without opening Slack.

### Checkpointing in practice

What happens if the worker pod is restarted after `conduct_research` completes but before `write_report` starts?

```
Journal state at restart:
  plan_research     ✓  output stored
  conduct_research  ✓  output stored
  write_report      ✗  not yet recorded

Workflow replay:
  plan_research     → journal hit → return stored plan   (< 1ms, no LLM call)
  conduct_research  → journal hit → return stored findings (< 1ms, no Wikipedia requests)
  write_report      → not in journal → execute normally
```

- No Wikipedia requests are retried.
- No scoping or research LLM calls are repeated.
- The run resumes exactly where it left off.
- You can verify this in Studio → Runs: replayed steps show near-zero duration, while the re-executed step shows real latency.

---

## Debug in Studio

### Viewing incoming events

Open **Studio → Events**. Every Slack webhook delivery appears as a row with a timestamp, event name (`slack.app_mention`, `slack.message`), and a status badge.

Two badge states to know:

- **Processing:** `_should_process` returned `True`. A workflow run was started.
- **Skipped:** `_should_process` returned `False` (bot message, empty text, or unsupported subtype). The workflow exited without running the pipeline.

<DocsImage
  src="/docs/integrations/slack-events-light.png"
  darkSrc="/docs/integrations/slack-events-dark.png"
  alt="Studio Events view showing a list of incoming Slack webhook deliveries with timestamps, event names, and Processing or Skipped status badges."
  caption="Studio → Events lists every Slack webhook delivery. Click any row to inspect the raw payload and follow the link to the triggered workflow run."
  width={1600}
  height={900}
/>

If you mention the bot and no Slack reply arrives, start here. A **Skipped** badge means the event was received but filtered before the pipeline could start. Open the payload pane to see which condition was triggered.

### Inspecting the event payload

Click any event row to open the detail pane. The fields map directly to what your workflow code receives as `**envelope`:

| Pane field | Where it comes from | What your code does with it |
|---|---|---|
| `source` | Slack integration config | Identifies the event origin as Slack vs HTTP or another source |
| `event` | `body.event.type` | Determines which trigger fired (`slack.app_mention` or `slack.message`) |
| `environment_ref` | Deployment environment | Confirms which deployment handled this event |
| `workflow` | Matched trigger rule | The workflow that started (or was skipped) for this event |
| `channel` | `body.event.channel` | Passed to `chat.postMessage` as the reply destination |
| `thread_ts` | `body.event.ts` | Passed to `chat.postMessage` to attach the reply as a thread |
| `bot_id` | `body.event.bot_id` | If non-empty, `_should_process` returns `False` (bot loop guard) |
| `text` | `body.event.text` | The raw message text including the `<@UXXXXXXX>` mention prefix |

The raw payload is exactly what `_extract_slack_message(envelope)` receives. If the extracted `channel` or `thread_ts` looks wrong in a run's output, compare against the payload pane. That is the authoritative source.

### Tracing event → run → steps

<DocsImage
  src="/docs/integrations/slack-runs-light.png"
  darkSrc="/docs/integrations/slack-runs-dark.png"
  alt="Studio Runs view showing the slack_deep_research workflow run with plan_research, conduct_research, and write_report steps, each displaying input, output, and duration."
  caption="Studio → Runs shows each ctx.step() checkpoint with its input, stored output, and execution duration — no extra logging needed."
  width={1600}
  height={900}
/>

Click a **Processing** event and follow the link to the Run. In the run view you see each `ctx.step()` with:

- **Input:** the arguments passed to the step function (topic string, plan text, research findings)
- **Output:** the return value stored in the journal (plan, findings, formatted report)
- **Duration:** how long each step took, including tool calls inside agent runs

This is the full observability loop: Slack message → event (Events view) → run (Runs view) → step-by-step trace (step outputs). No logging infrastructure required. AGNT5 captures all of it automatically from `ctx.step()` calls.

### Common debugging scenarios

| What you see in Studio | What it means | Where to look next |
|---|---|---|
| Event badge: **Skipped** | `_should_process` returned `False` | Payload pane: check `bot_id`, `subtype`, or empty `text` field |
| Event badge: **Processing**, no Slack reply | Workflow ran but `chat.postMessage` failed | Run view, final step output: check `slack_post.posted` and `slack_post.reason` |
| No event appears at all | Slack is not delivering to AGNT5 | Studio Integrations: verify the event subscription URL and confirm the app is installed in the target channel |
| `conduct_research` step shows sparse findings | Wikipedia returned few results for a subtopic | Check `plan_research` output. Subtopics may be too narrow or phrased as questions rather than search terms |
| `write_report` output is cut short | `WritingAgent` hit the 2 000-character limit | Expected. See "Extend it" below for splitting the report across multiple messages |
| Replayed step shows near-zero duration | That step was already checkpointed before restart | Normal. This confirms checkpointing is working. The result came from the journal |

---

## Running environments

The bot works across three environments: local, staging, and production. Each is covered in the docs:

- [Local development](/docs/build/local-development.md): use `agnt5 dev` to run the worker locally with file-watch reload. Trigger the workflow from Studio or the CLI without a real Slack event.
- [Environments](/docs/run/environments.md): deploy to preview, staging, or production with `agnt5 deploy --env <name>`. Promote a verified deployment forward rather than rebuilding, and scope `SLACK_BOT_TOKEN` per environment so staging posts to a test channel and production posts to the real one.
- [Deploying](/docs/run/deploying.md): covers the full deploy-verify-observe loop, including deployment logs, run listing, trace inspection, and promoting to production from Studio.

---

## Extend it

### Add web search alongside Wikipedia

`ResearchAgent` currently searches Wikipedia only. Add a web search tool for broader coverage:

```python
# tools.py
import httpx
from agnt5 import Context, tool

@tool(auto_schema=True)
async def web_search_tool(ctx: Context, query: str) -> str:
    """Search the web using a search API for broader coverage beyond Wikipedia."""
    async with httpx.AsyncClient(timeout=15) as client:
        response = await client.get(
            "https://api.yoursearchprovider.com/search",
            params={"q": query, "key": os.getenv("SEARCH_API_KEY")},
        )
    results = response.json().get("items", [])
    return "\n---\n".join(
        f"Title: {r['title']}\nURL: {r['link']}\nSnippet: {r['snippet']}"
        for r in results[:5]
    )
```

Register it on `ResearchAgent` and the `Worker`:

```python
# agents.py
research_agent = Agent(
    ...
    tools=[wikipedia_search_tool, fetch_webpage_tool, web_search_tool],
)

# app.py
worker = Worker(
    ...
    tools=[fetch_webpage_tool, wikipedia_search_tool, web_search_tool],
)
```

### Multi-turn conversation across thread replies

By default each mention starts a fresh pipeline with no memory of prior exchanges. To carry context across follow-up messages in the same Slack thread, store the report keyed by `thread_ts` in workflow state:

```python
# workflows.py — inside slack_deep_research
thread_ts = message.get("thread_ts")

# Load any prior research context for this thread
prior_context = await ctx.state.get(f"thread:{thread_ts}") or ""

research_plan = await ctx.step(_plan_research, topic, prior_context)
# ... rest of pipeline ...

# Persist the new report for the next message in this thread
await ctx.state.set(f"thread:{thread_ts}", report)
```

Update `_plan_research` to accept and include the prior context:

```python
# functions.py
@function(name="plan_research")
async def _plan_research(ctx: FunctionContext, topic: str, prior_context: str = "") -> str:
    context_block = (
        f"\nPrior research from this Slack thread:\n{prior_context}\n"
        if prior_context else ""
    )
    prompt = f"""Today's date is {current_date}.{context_block}

Research topic: {topic}
..."""
```

### Post longer reports as multiple messages

If the synthesised report exceeds Slack's rendering limit, split it across messages in the same thread:

```python
# workflows.py
MAX_CHARS = 3800   # leave headroom for Slack's internal overhead

async def _post_report_in_chunks(ctx, channel, report, thread_ts, bot_token):
    chunks = [report[i : i + MAX_CHARS] for i in range(0, len(report), MAX_CHARS)]
    for i, chunk in enumerate(chunks):
        label = f"*(Part {i + 1}/{len(chunks)})*\n" if len(chunks) > 1 else ""
        await _post_to_slack(ctx, channel, label + chunk, thread_ts, bot_token)
```

---

## What you learned

- **Fire-and-forget webhooks:** acknowledging the Slack event immediately and running the pipeline asynchronously is what makes slow AI tasks viable in Slack bots. This pattern applies any time you have a fast inbound trigger and a slow outbound result.
- **`ctx.step()` as a reliability primitive:** every step is a checkpoint. Worker restarts, container evictions, and redeployments do not lose in-progress work. Think of step boundaries as your pipeline's save points.
- **Multi-agent decomposition:** splitting scope / research / write into three agents gives you separate context windows, independent testability, and clean tool isolation. The same pattern applies to any pipeline that requires distinct reasoning modes in sequence.
- **Studio Events as a first-class debugging tool:** incoming event payloads, processing status, and step-level traces are all visible in Studio with no extra instrumentation. Most bot issues (wrong events, skipped messages, failed posts) can be diagnosed there before touching a log file.

---

## Next steps

- [Slack integration reference](/docs/integrations/event-sources/slack.md): full envelope structure, all event types, signature verification, and delivery semantics.
- [Build a deep research agent](/cookbooks/deep-research-agent.md): the same three-agent pipeline without the Slack trigger, useful as a standalone reference.
- [Build a durable research agent with approval and recovery](/cookbooks/durable-research-agent-approval-recovery.md): add a human approval gate before the report is posted.
- [Debug AI workflows with traces, not scattered logs](/cookbooks/workflow-native-observability.md): a deeper look at step-level inputs, outputs, durations, and model calls in the Studio trace view.

---

## Build a webhook triage agent

_Source: https://agnt5.com/cookbooks/webhook-triage-agent.md_

> Receive events, deduplicate delivery attempts, run async triage, and expose a trace per webhook.

Webhook delivery is noisy: providers retry, events arrive late, and downstream
systems fail. This cookbook builds a triage agent that deduplicates events and
runs async work under a trace.

## Scenario

A product receives incident webhooks. The workflow deduplicates events, asks an
agent to classify urgency, opens a ticket when needed, and records the result.

## What you build

- A webhook entry point.
- Event deduplication.
- Async triage with an agent.
- Idempotent ticket creation.
- A trace link returned to the webhook caller or dashboard.

## Workflow shape

```python
@workflow
async def triage_webhook(ctx: WorkflowContext, event: WebhookEvent) -> WebhookOutcome:
    deduped = await ctx.step(record_event_once, event.provider_event_id, event)
    if deduped.already_seen:
        return WebhookOutcome(status="duplicate", original_run_id=deduped.run_id)

    classification = await ctx.step(classify_incident_event, event)
    if classification.priority == "ignore":
        return WebhookOutcome(status="ignored")

    ticket = await ctx.step(create_incident_ticket_once, event.provider_event_id, classification)
    return WebhookOutcome(status="ticket_created", ticket_id=ticket.id)
```

The provider event ID is the key. It protects both dedupe and ticket creation.

## Webhook response

Return quickly with a run ID when the provider requires a fast response.

```json
{
  "accepted": true,
  "run_id": "run_01JWEBHOOK",
  "trace_url": "https://app.agnt5.com/runs/run_01JWEBHOOK"
}
```

The trace becomes the operational record for the asynchronous work.

## Production checks

- Duplicate provider deliveries return the original run or receipt.
- Ticket creation uses the provider event ID as an idempotency key.
- The trace includes raw event payload, classification, and side-effect receipt.
- Late events are processed according to explicit business rules.
- Failed events can be replayed locally.

## Next steps

- [Retry AI workflow steps without duplicate side effects](/cookbooks/retry-without-duplicate-side-effects.md)
- [Debug and replay a failed AI workflow](/cookbooks/debug-production-run.md)
- [Debug AI workflows with traces, not scattered logs](/cookbooks/workflow-native-observability.md)

---

## Debug AI workflows with traces, not scattered logs

_Source: https://agnt5.com/cookbooks/workflow-native-observability.md_

> Compare log-only debugging with workflow-native traces that preserve inputs, outputs, retries, and state.

Logs are still useful, but they rarely preserve the full execution context of an
AI workflow. This cookbook shows the same failure debugged with scattered logs
and then with AGNT5 workflow-native traces.

## Scenario

A lead-enrichment workflow returns the wrong company summary. The log line says
the LLM call succeeded. The support team needs to know which source documents,
tool outputs, prompts, retries, and state produced the answer.

## What you build

- A workflow with step-level trace capture.
- Minimal logs for infrastructure symptoms.
- Trace inspection for inputs, outputs, state, retries, and parent-child calls.
- A root-cause review flow that ends in a reproducible case.

## Workflow shape

Use steps to make the execution graph explicit.

```python
@workflow
async def enrich_lead(ctx: WorkflowContext, lead_id: str) -> LeadBrief:
    lead = await ctx.step(load_lead, lead_id)
    search_results = await ctx.step(search_company_sources, lead.company)
    facts = await ctx.step(extract_company_facts, search_results)
    brief = await ctx.step(write_lead_brief, lead, facts)
    return await ctx.step(save_brief_once, lead.id, brief)
```

Each step boundary becomes a trace boundary. The trace is the system of record
for what the workflow did.

## Log-only debugging

With logs alone, you usually see symptoms:

```text
INFO write_lead_brief completed model=gpt-4.1 latency_ms=1821
WARN user_reported_bad_summary lead_id=lead_123
```

This does not answer which source was wrong, whether a retry changed the output,
or whether the save step used the intended brief.

## Trace debugging

With the AGNT5 trace, inspect:

- `search_company_sources` input and source list,
- `extract_company_facts` output and confidence,
- `write_lead_brief` prompt, model output, and token usage,
- retry attempts and final selected result,
- the saved brief receipt.

The trace points to the root cause: an outdated source was ranked first and
passed through extraction.

## Production checks

- Every user-visible result links to a run ID.
- The trace has enough data to explain the output.
- Logs link to run IDs instead of duplicating trace payloads.
- Failed traces can be replayed or turned into eval cases.
- Sensitive fields are redacted before trace storage where required.

## Next steps

- [Turn a failed production AI run into an eval](/cookbooks/production-run-to-eval.md)
- [Debug and replay a failed AI workflow](/cookbooks/debug-production-run.md)
- [Build a data extraction workflow](/cookbooks/data-extraction.md)


# API Reference

---

## Create a contact — `POST /v1/contacts`

_Source: https://agnt5.com/api-reference/create-contact.md_

> Add a new contact to your contact list in Protocol. You must provide their Protocol username and phone number.

**Endpoint**: `POST /v1/contacts`
**Auth**: `Authorization: Bearer <api_key>` (required)
**Content-Type**: `application/json`
**Error envelope**: 4xx/5xx return `{"error": {"code": string, "message": string}}`


<ApiEndpoint
  method="POST"
  endpoint="/v1/contacts"
  description="This endpoint allows you to add a new contact to your contact list in Protocol. To add a contact, you must provide their Protocol username and phone number."
>
    <section>
      ## Required attributes

      <ApiAttribute
        name="username"
        type="string"
        description="The username for the contact."
        required={true}
      />

      <ApiAttribute
        name="phone_number"
        type="string"
        description="The phone number for the contact."
        required={true}
      />

      ## Optional attributes

      <ApiAttribute
        name="avatar_url"
        type="string"
        description="The avatar image URL for the contact."
        required={false}
      />

      <ApiAttribute
        name="display_name"
        type="string"
        description="The contact display name in the contact list. By default, this is just the username."
        required={false}
      />
    </section>

    <section>
      ## Request example

<MultiLanguageCodeBlock
  languages={["javascript", "bash"]}
  value={[
    { language: "javascript", code: "const val = 1" },
    { language: "bash", code: "wew sdsh" },
  ]}
/>

## Response

<MultiLanguageCodeBlock
  languages={["json"]}
  value={[
    {
      language: "json",
      code: `{
  "text": "Imagine the wildest idea that you've ever had, and you're curious about how it might scale to something that's a 100, a 1,000 times bigger. This is a place where you can get to do that."
}`,
    },
  ]}
/>
</section>

</ApiEndpoint>

---

## Delete a contact — `DELETE /v1/contacts/{id}`

_Source: https://agnt5.com/api-reference/delete-contact.md_

> Delete a contact from your Protocol contact list. Once deleted, it cannot be recovered.

**Endpoint**: `DELETE /v1/contacts/{id}`
**Auth**: `Authorization: Bearer <api_key>` (required)
**Path parameters**: `id` — the contact id to delete
**Idempotency**: deleting a missing contact returns 404 (not idempotent); deletion is irreversible
**Error envelope**: 4xx/5xx return `{"error": {"code": string, "message": string}}`


<ApiEndpoint
  method="DELETE"
  endpoint="/v1/contacts/{id}"
  description="This endpoint allows you to delete a contact from your Protocol contact list. Once a contact is deleted, it cannot be recovered."
>
    <section>
      ## Path parameters

      <ApiAttribute
        name="id"
        type="string"
        description="The unique identifier of the contact to delete."
        required={true}
      />
    </section>

    <section>
      ## Request example

      <MultiLanguageCodeBlock
        languages={["javascript", "bash"]}
        value={[
          {
            language: 'javascript',
            code: `fetch('https://api.protocol.chat/v1/contacts/WAz8eIbvDR60rouK', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer {token}'
  }
})`
          },
          {
            language: 'bash',
            code: `curl -X DELETE https://api.protocol.chat/v1/contacts/WAz8eIbvDR60rouK \\
  -H "Authorization: Bearer {token}"`
          }
        ]}
      />

      ```json {{ title: 'Response' }}
      {
        "success": true,
        "message": "Contact successfully deleted"
      }
      ```
    </section>
</ApiEndpoint>

---

## Get contacts — `GET /v1/contacts`

_Source: https://agnt5.com/api-reference/get-contacts.md_

> Retrieve your contacts list from Protocol. You can optionally filter and paginate the results.

**Endpoint**: `GET /v1/contacts`
**Auth**: `Authorization: Bearer <api_key>` (required)
**Query parameters**: see "Optional query parameters" below for filter and pagination keys
**Error envelope**: 4xx/5xx return `{"error": {"code": string, "message": string}}`


<ApiEndpoint
  method="GET"
  endpoint="/v1/contacts"
  description="This endpoint allows you to retrieve your contacts list from Protocol. You can optionally filter and paginate the results."
>
    <section>
      ## Optional query parameters

      <ApiAttribute
        name="page"
        type="integer"
        description="The page number for pagination. Defaults to 1."
        required={false}
      />

      <ApiAttribute
        name="per_page"
        type="integer"
        description="Number of contacts per page. Defaults to 20, maximum is 100."
        required={false}
      />

      <ApiAttribute
        name="username"
        type="string"
        description="Filter contacts by username."
        required={false}
      />
    </section>

    <section>
      ## Request example

      <MultiLanguageCodeBlock
        languages={["javascript", "bash"]}
        value={[
          {
            language: 'javascript',
            code: `fetch('https://api.protocol.chat/v1/contacts', {
  headers: {
    'Authorization': 'Bearer {token}'
  }
})`
          },
          {
            language: 'bash',
            code: `curl https://api.protocol.chat/v1/contacts \\
  -H "Authorization: Bearer {token}"`
          }
        ]}
      />

      ```json {{ title: 'Response' }}
      {
        "data": [
          {
            "id": "WAz8eIbvDR60rouK",
            "username": "johndoe",
            "phone_number": "+1 (555) 123-4567",
            "avatar_url": "https://assets.protocol.chat/avatars/johndoe.jpg",
            "display_name": "John Doe",
            "created_at": 692233200
          },
          {
            "id": "hSIhXBhNe8X1d8Et"
            // ... more contacts
          }
        ],
        "pagination": {
          "total": 35,
          "per_page": 20,
          "current_page": 1,
          "total_pages": 2
        }
      }
      ```
    </section>
</ApiEndpoint>

---

## Update a contact — `PATCH /v1/contacts/{id}`

_Source: https://agnt5.com/api-reference/update-contact.md_

> Update an existing contact in your Protocol contact list. You can update any of the contact's attributes.

**Endpoint**: `PATCH /v1/contacts/{id}`
**Auth**: `Authorization: Bearer <api_key>` (required)
**Content-Type**: `application/json`
**Path parameters**: `id` — the contact id to update
**Error envelope**: 4xx/5xx return `{"error": {"code": string, "message": string}}`


<ApiEndpoint
  method="PATCH"
  endpoint="/v1/contacts/{id}"
  description="This endpoint allows you to update an existing contact in your Protocol contact list. You can update any of the contact's attributes."
>
    <section>
      ## Optional attributes

      <ApiAttribute
        name="username"
        type="string"
        description="The new username for the contact."
        required={false}
      />

      <ApiAttribute
        name="phone_number"
        type="string"
        description="The new phone number for the contact."
        required={false}
      />

      <ApiAttribute
        name="avatar_url"
        type="string"
        description="The new avatar image URL for the contact."
        required={false}
      />

      <ApiAttribute
        name="display_name"
        type="string"
        description="The new display name for the contact."
        required={false}
      />
    </section>

    <section>
      ## Request example

      <MultiLanguageCodeBlock
        languages={["javascript", "bash"]}
        value={[
          {
            language: 'javascript',
            code: `fetch('https://api.protocol.chat/v1/contacts/WAz8eIbvDR60rouK', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer {token}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    display_name: 'John Smith',
    phone_number: '+1 (555) 987-6543'
  })
})`
          },
          {
            language: 'bash',
            code: `curl -X PATCH https://api.protocol.chat/v1/contacts/WAz8eIbvDR60rouK \\
  -H "Authorization: Bearer {token}" \\
  -H "Content-Type: application/json" \\
  -d '{
    "display_name": "John Smith",
    "phone_number": "+1 (555) 987-6543"
  }'`
          }
        ]}
      />

      ```json {{ title: 'Response' }}
      {
        "id": "WAz8eIbvDR60rouK",
        "username": "johndoe",
        "phone_number": "+1 (555) 987-6543",
        "avatar_url": "https://assets.protocol.chat/avatars/johndoe.jpg",
        "display_name": "John Smith",
        "updated_at": 692233200
      }
      ```
    </section>
</ApiEndpoint>


# SDK Reference

---

## SDK Overview

_Source: https://agnt5.com/sdk/index_

> Client SDKs for Python, TypeScript, and Go to integrate AGNT5 into your applications

# AGNT5 SDKs

Build AI workflows with your favorite language using high-level APIs that scale from simple functions to complex multi-agent systems.

## Available SDKs

AGNT5 provides native SDKs for the most popular programming languages:

### Python SDK
The most full-featured SDK with async/await support, type hints, and Pydantic models.

- **Type hints & Pydantic models** - Full type safety and data validation
- **Async/await support** - Modern Python async patterns
- **Rich debugging tools** - Comprehensive logging and error handling

[Get started with Python →](/sdk/python.md)

### TypeScript SDK
Full TypeScript support with comprehensive type definitions and excellent IDE integration.

- **Full TypeScript support** - Complete type definitions
- **Promise-based API** - Modern async JavaScript patterns
- **Node.js & browser compatible** - Works everywhere JavaScript runs

[Get started with TypeScript →](/sdk/typescript.md)

### Go SDK
Lightweight and performant with full concurrency support, perfect for high-throughput applications.

- **Goroutine-based concurrency** - Native Go concurrency patterns
- **Comprehensive error handling** - Robust error management
- **Zero external dependencies** - Minimal, self-contained library

[Get started with Go →](/sdk/go.md)

## Quick Start

1. **Install the SDK** for your preferred language
2. **Configure authentication** with your API keys
3. **Create your first workflow** with the SDK

[View installation guide →](/sdk/installation.md)

---

## AGNT5 Python SDK

_Source: https://agnt5.com/sdk/python_

> Build AI agents and durable workflows with the AGNT5 Python SDK

Build AI agents and reliable workflows with automatic recovery. AGNT5 combines agent orchestration and fault-tolerant execution in one lightweight framework.

## Primitives comparison

| **Attribute** | **Function** | **Entity** | **Workflow** | **Agent** | **Tool** |
|---|---|---|---|---|---|
| **What** | Stateless operation with retries | Stateful component with unique key | Multi-step orchestrated process | LLM with instructions and tools | Python function LLMs can call |
| **State** | None | Isolated per entity key | Isolated per workflow instance | Conversation history via Entity | None |
| **Durability** | Automatic retries, checkpointing | Persistent state across runs | Checkpointed steps, resume on failure | Context preserved in Entity | Runs within agent context |
| **Best For** | Document analysis, embeddings generation, LLM API calls | AI chat sessions, agent memory, conversation history | RAG pipelines, content generation with review, AI evals | Customer support, research assistants, code review | Vector search, knowledge base queries, API integrations |

## Key Features

- **Automatic recovery** from failures with configurable retry policies
- **Checkpointing** resumes from exact failure point
- **Multi-agent coordination** via handoffs and composition
- **Python-native** - decorators, async/await, type hints
- **Multi-provider** - OpenAI, Anthropic, Groq, Azure, Bedrock, OpenRouter
- **Built-in tracing** for debugging and monitoring


## Installation

```bash
pip install agnt5
```

## Quick example

```python
from agnt5 import Agent, workflow, tool, Context, WorkflowContext

# Define a tool for the agent
@tool(auto_schema=True)
async def search_docs(ctx: Context, query: str) -> str:
    """Search documentation for answers."""
    # Your search logic here
    return f"Found documentation about: {query}"

# Create an AI agent with tools
agent = Agent(
    name="assistant",
    model="openai/gpt-4o-mini",
    instructions="You are a helpful assistant. Search docs when needed.",
    tools=[search_docs]
)

# Create a durable workflow that orchestrates the agent
@workflow
async def process_question(ctx: WorkflowContext, question: str) -> dict:
    """Durable workflow for processing questions."""

    # Step 1: Get answer from agent (checkpointed)
    answer = await ctx.step("get_answer", agent.run(question))

    # Step 2: Store result (checkpointed)
    await ctx.step("store", save_answer(question, answer))

    return {"question": question, "answer": answer}

# If this crashes after step 1, it resumes from step 2 on restart
```

**Note**: Set your `OPENAI_API_KEY` environment variable before running.

## Next Steps

### Getting Started
- **[Quickstart](getting-started)** - Installation, first worker, and local development setup
- **[Worker Runtime](worker)** - Configure and deploy workers

### Core Primitives
- **[Functions](functions)** - Stateless operations with retries
- **[Entities](entity)** - Stateful components with unique keys
- **[Workflows](workflows)** - Multi-step orchestration patterns
- **[Context API](context)** - Orchestration, state, AI, and observability APIs

### Agent Development Kit (ADK)
- **[Agents](agent)** - Autonomous LLM-driven systems
- **[Sessions](session)** - Conversation containers and multi-agent coordination
- **[Tools](tool)** - Callable capabilities that extend agent abilities
- **[Memory](memory)** - Long-term knowledge storage with semantic search

### Examples
- **[Examples](examples/basic-worker)** - Practical usage examples

---

## Agents

_Source: https://agnt5.com/sdk/python/agent_

> Autonomous LLM-driven systems with tool orchestration and reasoning

Agents are autonomous LLM-driven systems that reason, plan, and execute tasks using tools. They orchestrate complex multi-step workflows by breaking down problems, selecting appropriate tools, and iterating until complete.

## Key Characteristics

- **LLM-Powered** - Driven by language models for reasoning and decision-making
- **Tool Orchestration** - Automatically selects and executes appropriate tools
- **Memory Integration** - Maintains long-term knowledge across conversations
- **Session Aware** - Uses sessions for conversation context
- **Streaming Support** - Real-time event streaming for responsive UX
- **Durable** - Built on AGNT5 primitives for automatic fault tolerance

## Basic Usage

### Simple Agent

```python
from agnt5 import Agent, LanguageModel

lm = LanguageModel()

agent = Agent(
    name="assistant",
    model=lm,
    instructions="You are a helpful coding assistant."
)

# Run agent
result = await agent.run("Explain recursion")
print(result.output)
```

### Agent with Tools

```python
from agnt5 import Agent, tool, LanguageModel

@tool.function(auto_schema=True)
def search_docs(query: str, language: str = "python") -> List[Dict]:
    """Search programming language documentation."""
    # Implementation
    return search_results

@tool.function(auto_schema=True)
def run_code(code: str, language: str = "python") -> Dict[str, str]:
    """Execute code and return output."""
    # Implementation
    return {"output": result}

lm = LanguageModel()
agent = Agent(
    name="coding_assistant",
    model=lm,
    instructions="""You are a coding assistant.
    Use search_docs to find API references.
    Use run_code to test code examples.""",
    tools=[search_docs, run_code]
)

result = await agent.run("How do I read a file in Python? Show me an example.")
```

### Agent with Session and Memory

```python
from agnt5 import Agent, Session, Memory, LanguageModel

# Create session
session = Session(
    id="tutoring-session-789",
    user_id="student-123",
    metadata={"subject": "mathematics"}
)

# Create memory
memory = Memory(service=VectorMemoryService())
await memory.store("student_level", "Advanced calculus")

# Create agent
lm = LanguageModel()
agent = Agent(
    name="math_tutor",
    model=lm,
    instructions="You are a patient math tutor. Adapt to student's level.",
    tools=[solve_equation_tool, plot_function_tool],
    session=session,
    memory=memory
)

result = await agent.run("Help me understand limits")
```

## Agent Configuration

### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `name` | `str` | Unique agent name |
| `model` | `LanguageModel` | LLM to use for reasoning |
| `instructions` | `str` | System prompt and guidelines |
| `tools` | `List[Tool]` | Tools available to agent |
| `session` | `Session \| None` | Session for conversation context |
| `memory` | `Memory \| None` | Long-term knowledge storage |
| `max_iterations` | `int` | Max reasoning loops (default: 10) |

### Instructions

Write clear, actionable instructions:


  

  
    ```python
    agent = Agent(
        name="code_reviewer",
        model=lm,
        instructions="""You are an expert code reviewer specializing in Python.

        Review process:
        1. Analyze code for complexity, duplication, style
        2. Check for security vulnerabilities
        3. Suggest improvements with code examples
        4. Prioritize: security > correctness > performance > style

        Be constructive and explain your reasoning."""
    )
    ```
  

  
    ```python
    agent = Agent(
        name="helper",
        model=lm,
        instructions="Help the user with stuff."  # Too vague
    )
    ```
  


## Streaming Agents

Stream events in real-time:

```python
async for event in agent.stream("Analyze this dataset", session=session):
    match event.type:
        case "thinking":
            print(f"🤔 {event.content}")
        case "tool_call":
            print(f"🔧 Calling {event.tool_name}({event.arguments})")
        case "tool_result":
            print(f"✓ Result: {event.result}")
        case "response":
            print(f"💬 {event.content}")
        case "error":
            print(f"❌ Error: {event.error}")
```

## Agent Planning

Preview execution plan before running:

```python
# Get plan without executing
plan = agent.plan("Analyze competitor pricing strategies")

print(f"Estimated steps: {len(plan.steps)}")
for step in plan.steps:
    print(f"- {step.type}: {step.description}")
    if step.tool:
        print(f"  Tool: {step.tool.name}")

# Review and execute if approved
if user_approves(plan):
    result = await agent.run("Analyze competitor pricing strategies")
```

## Common Patterns

### Research Agent

```python
from agnt5 import Agent, Session, Memory, tool

@tool.function(auto_schema=True)
def search_academic(query: str, year_from: int = 2020) -> List[Dict]:
    """Search academic papers."""
    pass

@tool.function(auto_schema=True)
def extract_insights(paper_text: str) -> Dict[str, List[str]]:
    """Extract key insights from paper."""
    pass

# Create research agent
session = Session(id="research-ai-safety-001", user_id="researcher-123")
memory = Memory(service=VectorMemoryService())

lm = LanguageModel()
research_agent = Agent(
    name="research_agent",
    model=lm,
    instructions="""You are a research assistant specializing in AI safety.

    Research process:
    1. Search for relevant recent papers
    2. Extract key insights from each paper
    3. Identify common themes and gaps
    4. Synthesize findings into comprehensive summary""",
    tools=[search_academic, extract_insights],
    session=session,
    memory=memory
)

result = await research_agent.run(
    "Survey the current state of AI alignment research"
)

# Store findings in memory
await memory.ingest_from_session(session, strategy="smart")
```

### Multi-Agent Workflow

```python
# Shared session for coordination
session = Session(id="product-launch-001", user_id="pm-456")

# Specialized agents
market_researcher = Agent(
    name="market_analyst",
    model=lm,
    tools=[market_data_tool, competitor_analysis_tool],
    session=session,
    instructions="Analyze market opportunities and competitive landscape."
)

product_designer = Agent(
    name="designer",
    model=lm,
    tools=[design_tool, user_research_tool],
    session=session,
    instructions="Design products based on market research and user needs."
)

technical_lead = Agent(
    name="tech_lead",
    model=lm,
    tools=[architecture_tool, feasibility_tool],
    session=session,
    instructions="Assess technical feasibility and propose architecture."
)

# Sequential execution with shared context
market_analysis = await market_researcher.run(
    "Analyze market for AI-powered code review tools"
)

product_specs = await product_designer.run(
    "Design product based on market analysis"
)

tech_assessment = await technical_lead.run(
    "Evaluate technical feasibility of proposed product"
)
```

### Agent Handoff

```python
from agnt5.tools import AgentTool

# Create specialized agents
billing_agent = Agent(
    name="billing_specialist",
    model=lm,
    tools=[payment_tool, invoice_tool, refund_tool],
    instructions="Handle billing, payments, and refunds."
)

technical_agent = Agent(
    name="tech_support",
    model=lm,
    tools=[diagnostic_tool, fix_tool],
    instructions="Diagnose and fix technical issues."
)

# Coordinator with handoff capability
coordinator = Agent(
    name="coordinator",
    model=lm,
    tools=[
        classify_request_tool,
        AgentTool(target_agent=billing_agent),
        AgentTool(target_agent=technical_agent)
    ],
    instructions="""You are a support coordinator.
    Classify requests and hand off to appropriate specialist.

    Hand off to:
    - billing_specialist: payment, invoice, refund questions
    - tech_support: technical issues, bugs, troubleshooting"""
)

session = Session(id="support-ticket-789", user_id="customer-123")
result = await coordinator.run(
    "I was charged twice for my subscription",
    session=session
)
```

### Human-in-the-Loop Agent

```python
@tool.function(auto_schema=True, confirmation=True)
def deploy_to_production(version: str) -> Dict[str, str]:
    """Deploy application to production.

    Warning: Requires human approval.
    """
    pass

deployment_agent = Agent(
    name="deployer",
    model=lm,
    tools=[run_tests_tool, deploy_to_production],
    instructions="""Run all tests before deploying.
    Always request human approval for production deployments."""
)

result = await deployment_agent.run("Deploy version 2.0 to production")
# Agent runs tests, then waits for human approval before deploying
```

### Iterative Problem Solving

```python
debugging_agent = Agent(
    name="debugger",
    model=lm,
    tools=[
        analyze_logs_tool,
        run_diagnostic_tool,
        apply_fix_tool,
        verify_fix_tool
    ],
    instructions="""You are a debugging assistant.

    Process:
    1. Analyze error logs to identify root cause
    2. Run diagnostics to confirm hypothesis
    3. Apply potential fix
    4. Verify fix works
    5. If not fixed, iterate (max 3 attempts)

    Always verify fixes before considering issue resolved."""
)

result = await debugging_agent.run(
    "Users are experiencing 500 errors on the checkout page"
)
```

## Best Practices

### 1. Write Clear Instructions

Provide specific, actionable guidance:

```python
# ✓ Good - Specific process
agent = Agent(
    name="analyst",
    instructions="""Analyze data systematically:
    1. Identify data patterns and anomalies
    2. Calculate key statistics
    3. Generate visualizations
    4. Provide actionable insights"""
)

# ✗ Bad - Too vague
agent = Agent(
    name="helper",
    instructions="Help with analysis"
)
```

### 2. Use Sessions for Coordination

Share context across agents:

```python
# Create shared session
session = Session(id="project-workflow-123", user_id="user-456")

# Set shared context
session.set_state("project_name", "ai-safety-research")
session.set_state("deadline", "2024-12-31")

# All agents access shared context
agent1 = Agent(name="agent1", session=session, ...)
agent2 = Agent(name="agent2", session=session, ...)
```

### 3. Leverage Memory

Use memory for persistent knowledge:

```python
# Store user preferences
await memory.store("user_expertise", "Expert in React and TypeScript")
await memory.store("coding_style", "Prefers functional programming")

# Agent recalls automatically
agent = Agent(
    name="assistant",
    model=lm,
    tools=[code_gen_tool],
    memory=memory
)

result = await agent.run("Help me build a component")
# Agent uses stored preferences
```

### 4. Limit Iterations

Prevent infinite loops:

```python
agent = Agent(
    name="bounded_agent",
    model=lm,
    max_iterations=5,  # Stop after 5 reasoning loops
    instructions="Solve problems efficiently."
)
```

## Agent Architecture

Agents orchestrate AGNT5 primitives:

1. **LLM Core** - Language model for reasoning
2. **Tool Execution** - Tools built on Function primitive
3. **State Management** - Sessions use Entity for state
4. **Long-Term Storage** - Memory uses Entity for persistence
5. **Orchestration** - Workflow patterns for multi-step tasks
6. **Streaming** - Real-time event emission

```
Agent
├── LanguageModel (reasoning)
├── Tools (actions via Function)
├── Session (context via Entity)
├── Memory (knowledge via Entity)
└── Planner (orchestration)
```

## Comparison with Primitives

| Aspect | Function | Workflow | Agent |
| --- | --- | --- | --- |
| Autonomy | None | Scripted | Autonomous |
| Decision Making | Pre-programmed | Control flow | LLM-driven |
| Tool Use | N/A | Explicit calls | Dynamic selection |
| Adaptability | Fixed | Fixed steps | Adaptive reasoning |
| Use Case | Single operation | Multi-step process | Complex tasks |

**When to use Function:**
- Single, deterministic operation
- No decision-making needed

**When to use Workflow:**
- Pre-defined multi-step process
- Explicit control flow

**When to use Agent:**
- Complex, open-ended tasks
- Requires reasoning and adaptation
- Dynamic tool selection needed

## Next Steps

- [Session](session) - Agent conversation context
- [Tool](tool) - Agent capabilities
- [Memory](memory) - Agent long-term knowledge
- [Workflows](workflows) - Orchestration patterns
- [Context API](context) - Agent execution context

---

## Decorators API

_Source: https://agnt5.com/sdk/python/api/decorators_

> Complete API reference for AGNT5 Python SDK decorators

Complete API reference for decorator-based component registration in the AGNT5 Python SDK.

## `@function`

Register a Python callable as an invokable component.

### Signature

```python
def function(name: str | None = None) -> Callable[[Callable[..., Any]], Callable[..., Any]]
```

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | `str \| None` | Override the registered function name. Defaults to the original function name. |

### Returns

Decorated function with AGNT5 metadata annotations.

### Examples

```python
from agnt5 import function

# Basic function registration
@function()
def greet(name: str) -> str:
    return f"Hello, {name}!"

# Custom function name
@function("math.add")
def add_numbers(a: int, b: int) -> int:
    return a + b

# Function with context
@function()
def context_handler(ctx: ExecutionContext, data: dict) -> dict:
    return {
        "invocation_id": ctx.invocation_id,
        "data": data
    }
```

### Function Annotations

The decorator adds these attributes to the decorated function:

| Attribute | Type | Description |
|-----------|------|-------------|
| `_agnt5_handler_name` | `str` | Registered handler name |
| `_agnt5_is_function` | `bool` | Always `True` for functions |

## `@handler`

Alias for `@function` decorator.

```python
from agnt5 import handler

@handler()
def my_handler(data: str) -> str:
    return data.upper()
```

## `@workflow`

Register a workflow definition factory.

### Signature

```python
def workflow(name: str | None = None) -> Callable[[Callable[[], FlowDefinition]], Callable[[], FlowDefinition]]
```

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | `str \| None` | Override the registered workflow name. Defaults to the factory function name. |

### Returns

Decorated workflow factory function.

### Examples

```python
from agnt5 import workflow, task_step
from agnt5.workflows import FlowDefinition

@workflow()
def data_pipeline() -> FlowDefinition:
    return FlowDefinition([
        task_step("extract", service_name="etl", handler_name="extract_data"),
        task_step("transform", service_name="etl", handler_name="transform_data",
                 dependencies=["extract"])
    ])

@workflow("custom_name")
def workflow_factory() -> FlowDefinition:
    return FlowDefinition([...])
```

## Registry Functions

### `get_registered_functions`

Get all registered function handlers.

```python
def get_registered_functions() -> Dict[str, Callable]
```

#### Returns

Dictionary mapping handler names to callable functions.

#### Example

```python
from agnt5.decorators import get_registered_functions

@function()
def test_handler(data: str) -> str:
    return data

functions = get_registered_functions()
print(functions)  # {'test_handler': <function test_handler at 0x...>}
```

### `get_function_metadata`

Inspect metadata for a decorated function.

```python
def get_function_metadata(func: Callable) -> dict | None
```

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `func` | `Callable` | Decorated function to inspect |

#### Returns

Metadata dictionary or `None` for non-decorated functions.

#### Metadata Structure

```python
{
    "name": "function_name",
    "type": "function",
    "parameters": [
        {
            "name": "param_name",
            "type": "str",
            "required": True,
            "default": None  # or default value
        }
    ],
    "return_type": "str"
}
```

#### Example

```python
from agnt5.decorators import get_function_metadata

@function()
def sample_function(name: str, age: int = 25) -> dict:
    return {"name": name, "age": age}

metadata = get_function_metadata(sample_function)
print(metadata)
# {
#     "name": "sample_function",
#     "type": "function",
#     "parameters": [
#         {"name": "name", "type": "str", "required": True},
#         {"name": "age", "type": "int", "required": False, "default": 25}
#     ],
#     "return_type": "dict"
# }
```

### `clear_registry`

Clear the function registry (primarily for testing).

```python
def clear_registry() -> None
```

#### Example

```python
from agnt5.decorators import clear_registry, get_registered_functions

# Clear all registered functions
clear_registry()

# Verify registry is empty
functions = get_registered_functions()
assert len(functions) == 0
```

## Execution Functions

### `execute_component`

Execute a registered component directly (low-level interface).

```python
def execute_component(
    handler_name: str,
    input_data: bytes,
    context: Any | None = None
) -> bytes
```

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `handler_name` | `str` | Name of registered handler |
| `input_data` | `bytes` | JSON-encoded input data |
| `context` | `Any \| None` | Execution context (optional) |

#### Returns

JSON-encoded result as bytes.

#### Behavior

1. Resolves handler by name (raises `ValueError` if not found)
2. Decodes `input_data` from JSON
3. Invokes handler with or without context based on signature
4. Serializes result to JSON bytes
5. Wraps exceptions in `RuntimeError` with detailed logging

#### Example

```python
from agnt5.decorators import execute_component
import json

@function()
def test_handler(data: str) -> str:
    return data.upper()

# Execute directly
input_data = json.dumps("hello").encode()
result = execute_component("test_handler", input_data)

# Parse result
output = json.loads(result.decode())
print(output)  # "HELLO"
```

## Error Handling

### Function Registration Errors

```python
# Duplicate names raise ValueError during registration
@function("duplicate")
def handler1(data: str) -> str:
    return data

@function("duplicate")  # Raises ValueError
def handler2(data: str) -> str:
    return data
```

### Execution Errors

```python
# Handler not found
try:
    execute_component("nonexistent", b'{}')
except ValueError as e:
    print(f"Handler error: {e}")

# Runtime errors are wrapped
@function()
def failing_handler(data: dict) -> dict:
    raise ValueError("Processing failed")

try:
    execute_component("failing_handler", b'{}')
except RuntimeError as e:
    print(f"Execution error: {e}")
```

## Type Support

### Supported Handler Signatures

```python
# No context parameter
@function()
def simple_handler(data: str) -> str:
    return data

# With context parameter
@function()
def context_handler(ctx: ExecutionContext, data: str) -> str:
    return f"{ctx.invocation_id}: {data}"

# Async handlers
@function()
async def async_handler(data: str) -> str:
    return data.upper()

# Streaming handlers
@function(streaming=True)
async def streaming_handler(data: str):
    for char in data:
        yield char
```

### Parameter Detection

The decorator automatically detects context parameters:

- If first parameter is named `ctx`, `context`, or has type annotation `ExecutionContext`, it's treated as a context parameter
- Context parameters are omitted from metadata parameter lists
- Handler invocation includes context only when expected

## Testing Support

### Mock Registry

```python
from unittest.mock import patch
from agnt5.decorators import get_registered_functions

def test_with_clean_registry():
    with patch('agnt5.decorators._function_registry', {}):
        # Test with isolated registry
        @function()
        def test_func(data: str) -> str:
            return data

        functions = get_registered_functions()
        assert "test_func" in functions
```

### Direct Testing

```python
import pytest
from agnt5.decorators import execute_component
from agnt5.components import ExecutionContext, ComponentType

def test_function_execution():
    @function()
    def test_handler(data: str) -> str:
        return data.upper()

    # Test with execute_component
    import json
    input_data = json.dumps("hello").encode()
    result = execute_component("test_handler", input_data)

    assert json.loads(result.decode()) == "HELLO"

def test_context_function():
    @function()
    def context_handler(ctx: ExecutionContext, data: str) -> dict:
        return {
            "invocation_id": ctx.invocation_id,
            "data": data
        }

    # Create mock context
    from unittest.mock import Mock
    ctx = Mock(spec=ExecutionContext)
    ctx.invocation_id = "test-123"

    result = context_handler(ctx, "test")
    assert result["invocation_id"] == "test-123"
```

## Best Practices

### Naming Conventions

```python
# Good: Descriptive names
@function("user.create")
def create_user(user_data: dict) -> dict:
    return create_user_record(user_data)

# Good: Service-scoped names
@function("email.send_notification")
def send_email(recipient: str, message: str) -> bool:
    return send_email_message(recipient, message)

# Avoid: Generic names
@function("process")  # Too generic
def process_data(data: dict) -> dict:
    return data
```

### Error Handling

```python
@function()
def robust_handler(data: dict) -> dict:
    try:
        # Validate input
        if not isinstance(data, dict):
            return {"error": "Input must be a dictionary"}

        # Process data
        result = process_business_logic(data)
        return {"success": True, "result": result}

    except ValueError as e:
        return {"error": f"Validation error: {e}"}
    except Exception as e:
        # Log error for debugging
        logger.error(f"Unexpected error: {e}")
        return {"error": "Internal error"}
```

### Type Annotations

```python
from typing import Dict, List, Optional, Union

@function()
def typed_handler(
    items: List[str],
    metadata: Optional[Dict[str, Union[str, int]]] = None
) -> Dict[str, Union[List[str], bool]]:
    return {
        "processed_items": [item.upper() for item in items],
        "has_metadata": metadata is not None
    }
```

## Next Steps

- [Components API](components) - Component classes and execution context
- [Worker API](worker) - Worker runtime and configuration
- [Workflows API](workflows) - Workflow definition and step utilities

---

## Context API

_Source: https://agnt5.com/sdk/python/context_

> Execution context with APIs for orchestration, state, AI, and observability

The **Context** (`ctx`) is the execution environment provided to all AGNT5 components. It provides APIs for orchestration, state management, LLM interactions, coordination, and observability.

## Core Capabilities

- **Orchestration** - Execute tasks, spawn functions, parallel execution
- **State Management** - Get/set/delete state for entities
- **Coordination** - Signals, timers, human approvals
- **AI Integration** - LLM calls, tool registration
- **Observability** - Logging, metrics, tracing

## Orchestration APIs

### Task Execution

Execute functions and wait for results (workflows only):

```python
@workflow
async def process_workflow(ctx):
    # Execute a task
    result = await ctx.task(
        service_name="analytics",
        handler_name="process_data",
        input={"dataset": "users"}
    )

    return result
```

### Parallel Execution

Run multiple tasks concurrently:


  

  
    ```python
    # Returns list of results in order
    results = await ctx.parallel(
        ctx.task("service1", "handler1"),
        ctx.task("service2", "handler2"),
        ctx.task("service3", "handler3")
    )

    # Access results by index
    result1 = results[0]
    result2 = results[1]
    ```
  

  
    ```python
    # Returns dict with named results
    results = await ctx.gather(
        db=ctx.task("analytics", "analyze_db"),
        api=ctx.task("analytics", "analyze_api"),
        cache=ctx.task("analytics", "analyze_cache")
    )

    # Access results by name
    db_result = results["db"]
    api_result = results["api"]
    ```
  


### Async Invocation

Spawn child functions without waiting:

```python
@function
async def batch_processor(ctx, items: list):
    # Spawn child invocations
    handles = []
    for item in items:
        handle = ctx.spawn(process_item, item, key=f"item-{item['id']}")
        handles.append(handle)

    # Continue other work...

    # Wait for results later if needed
    results = [await h.result() for h in handles]
    return {"processed": len(results)}
```

### Checkpointing

Checkpoint expensive operations (functions only):

```python
@function
async def process_pipeline(ctx, data_id: str):
    # Each step is checkpointed
    raw = await ctx.step("extract", lambda: extract_data(data_id))
    cleaned = await ctx.step("clean", lambda: clean_data(raw))
    result = await ctx.step("analyze", lambda: analyze(cleaned))

    # If crash occurs, resumes from last completed step
    return result
```

## State Management (Entities)

### Get, Set, Delete

Manage entity state:

```python
@entity.write
async def update_profile(ctx, name: str, age: int):
    # Get with default
    profile = await ctx.get("profile", {})

    # Update profile
    profile.update({"name": name, "age": age})

    # Set state
    ctx.set("profile", profile)
    ctx.set("last_updated", datetime.now().isoformat())

    # Delete temporary data
    ctx.delete("temp_cache")

    return {"status": "updated"}
```

### Entity Method Calls

Call entity methods from functions:

```python
@function
async def chat(ctx, conversation_id: str, message: str):
    # Call entity method
    response = await ctx.entity(
        "ChatAgent",
        conversation_id
    ).send_message(message)

    return response
```

## Coordination APIs

### Signals

Wait for external events:


  

  
    ```python
    @workflow
    async def approval_workflow(ctx, document_id: str):
        # Submit for review
        await ctx.task("docs", "submit_review", input={"id": document_id})

        # Wait for approval signal (24 hours timeout)
        approval = await ctx.signal(
            "manager_approved",
            timeout_ms=86400000,
            default={"approved": False}
        )

        if approval["approved"]:
            await ctx.task("docs", "publish", input={"id": document_id})
            return {"status": "published"}
        else:
            return {"status": "rejected"}
    ```
  

  
    ```python
    @function
    async def approve_document(ctx, workflow_id: str):
        # Send approval signal to waiting workflow
        await ctx.signal.emit(
            "manager_approved",
            target_workflow_id=workflow_id,
            payload={"approved": True, "approver": "manager@example.com"}
        )

        return {"status": "signal_sent"}
    ```
  


### Timers & Sleep

Add delays and scheduled execution:

```python
@workflow
async def scheduled_job(ctx):
    # Wait 5 seconds
    await ctx.timer(delay_ms=5000)

    # Or use sleep (alternative syntax)
    await ctx.sleep(30)  # 30 seconds

    # Wait until specific time (cron)
    await ctx.timer(cron="0 0 * * *")  # Daily at midnight

    return {"status": "completed"}
```

### Human-in-the-Loop

Request human approval:

```python
@workflow
async def deployment_workflow(ctx, version: str):
    # Run tests
    test_results = await ctx.task("ci", "run_tests", input={"version": version})

    if test_results["passed"]:
        # Request human approval for production
        approval = await ctx.human.approval(
            "deploy_production",
            payload={"version": version, "tests": test_results},
            timeout=timedelta(minutes=30),
            required_roles=["admin", "devops"]
        )

        if approval.decision == "approved":
            await ctx.task("deploy", "to_production", input={"version": version})
            return {"status": "deployed"}

    return {"status": "cancelled"}
```

## AI Integration

### LLM Generation

Generate text or structured responses:


  

  
    ```python
    @function
    async def summarize(ctx, text: str):
        response = await ctx.llm.generate(
            prompt=f"Summarize this text: {text}",
            model="gpt-4o-mini"
        )

        return {"summary": response.text}
    ```
  

  
    ```python
    @function
    async def chat_response(ctx, messages: list):
        response = await ctx.llm.generate(
            prompt=[
                {"role": "system", "content": "You are a helpful assistant"},
                *messages
            ],
            model="gpt-4"
        )

        return {"response": response.text}
    ```
  

  
    ```python
    @function
    async def extract_info(ctx, text: str):
        # JSON Schema-constrained output
        response = await ctx.llm.generate(
            prompt=f"Extract information: {text}",
            schema={
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "email": {"type": "string"}
                },
                "required": ["name"]
            },
            model="gpt-4o-mini"
        )

        return response.object  # Parsed JSON
    ```
  


### Streaming

Stream responses for real-time output:

```python
@function
async def stream_story(ctx, topic: str):
    # Stream text generation
    async for chunk in await ctx.llm.stream(
        prompt=f"Write a story about {topic}",
        model="gpt-4o"
    ):
        if chunk.text:
            yield chunk.text  # Stream to client
```

### Tool Registration

Register tools for LLM use:

```python
@function
async def agent_with_tools(ctx, query: str):
    # Register search tool
    search_tool = ctx.tools.register(
        "web_search",
        handler=perform_search,
        description="Search the web for information",
        schema={
            "type": "object",
            "properties": {
                "query": {"type": "string"},
                "max_results": {"type": "integer"}
            }
        }
    )

    # Generate with tool
    response = await ctx.llm.generate(
        prompt=query,
        tools=[search_tool],
        model="gpt-4o"
    )

    return response
```

## Observability

### Logging

Structured logging with context:

```python
@function
async def tracked_operation(ctx, data: dict):
    logger = ctx.log()

    logger.info("Processing started", extra={"data_size": len(data)})

    try:
        result = process(data)
        logger.info("Processing completed", extra={"result_size": len(result)})
        return result
    except Exception as e:
        logger.error("Processing failed", exc_info=True)
        raise
```

### Metrics

Record custom metrics:

```python
@function
async def monitored_function(ctx, request: dict):
    metrics = ctx.metrics()

    # Increment counter
    metrics.increment("requests.count", service="api")

    # Record timing
    start = time.time()
    result = await process_request(request)
    duration = (time.time() - start) * 1000

    metrics.observe("latency.ms", duration, endpoint="/api/process")

    return result
```

### Distributed Tracing

Create spans for tracing:

```python
@function
async def traced_operation(ctx, data: dict):
    # Create span for external API call
    with ctx.trace_span().start("external_api_call", service="payments"):
        result = await call_payment_api(data)

    # Create span for database operation
    with ctx.trace_span().start("database_query", service="postgres"):
        await save_to_db(result)

    return result
```

## Configuration & Secrets

### Secrets

Access secrets securely:

```python
@function
async def api_call(ctx, endpoint: str):
    # Get API key from secrets
    api_key = ctx.secrets().get("openai_api_key")
    db_password = ctx.secrets().get("database_password")

    # Use secrets in API calls
    response = await make_request(endpoint, api_key=api_key)
    return response
```

### Configuration

Feature flags and config:

```python
@function
async def feature_gated_handler(ctx, data: dict):
    config = ctx.config()

    # Check feature flag
    if config.get("new_feature_enabled", default=False):
        return await new_implementation(data)
    else:
        return await legacy_implementation(data)

    # A/B testing variant
    variant = config.variant("experiment_group", default="control")
    if variant == "treatment":
        return await experimental_flow(data)
```

### Request Headers

Access incoming headers:

```python
@function
async def header_aware(ctx, data: dict):
    headers = ctx.headers()

    user_agent = headers.get("user-agent", "unknown")
    correlation_id = headers.get("x-correlation-id")

    logger = ctx.log()
    logger.info(f"Request from {user_agent}", extra={"correlation_id": correlation_id})

    return {"processed": True}
```

## Context Properties

Access execution metadata:

```python
@function
async def introspective(ctx, data: dict):
    return {
        "run_id": ctx.run_id,              # Workflow/run identifier
        "step_id": ctx.step_id,            # Current step identifier
        "attempt": ctx.attempt,            # Retry attempt number
        "component_type": ctx.component_type,  # "function", "entity", "workflow"
        "object_id": ctx.object_id,        # Entity key (for entities)
        "method_name": ctx.method_name,    # Entity method name (for entities)
        "processed": data
    }
```

## API Reference

### Orchestration

| API | Description |
| --- | --- |
| `ctx.task(service, handler, input)` | Execute function (workflows only) |
| `ctx.parallel(*tasks)` | Run tasks in parallel |
| `ctx.gather(**tasks)` | Parallel with named results |
| `ctx.spawn(fn, *args, key)` | Async child invocation |
| `ctx.step(name, fn)` | Checkpoint operation (functions) |

### State (Entities)

| API | Description |
| --- | --- |
| `await ctx.get(key, default)` | Get state value |
| `ctx.set(key, value)` | Set state value |
| `ctx.delete(key)` | Delete state key |
| `await ctx.entity(type, key).method()` | Call entity method |

### Coordination

| API | Description |
| --- | --- |
| `await ctx.signal(name, timeout_ms, default)` | Wait for signal |
| `await ctx.signal.emit(name, payload)` | Send signal |
| `await ctx.timer(delay_ms)` | Wait with delay |
| `await ctx.timer(cron)` | Wait until cron time |
| `await ctx.sleep(seconds)` | Durable sleep |
| `await ctx.human.approval(...)` | Request approval |

### AI Integration

| API | Description |
| --- | --- |
| `await ctx.llm.generate(prompt, model)` | Generate text/JSON |
| `await ctx.llm.stream(prompt, model)` | Stream generation |
| `ctx.tools.register(name, handler, schema)` | Register tool |

### Observability

| API | Description |
| --- | --- |
| `ctx.log()` | Get logger |
| `ctx.metrics()` | Get metrics recorder |
| `ctx.trace_span().start(name, service)` | Create trace span |

### Configuration

| API | Description |
| --- | --- |
| `ctx.secrets().get(key)` | Get secret |
| `ctx.config().get(key, default)` | Get config value |
| `ctx.config().variant(key, default)` | Get A/B variant |
| `ctx.headers()` | Get request headers |

## Common Patterns

### Parallel with Error Handling

```python
@workflow
async def robust_workflow(ctx):
    results = await ctx.gather(
        task1=ctx.task("svc", "task1"),
        task2=ctx.task("svc", "task2")
    )

    if results["task1"] and results["task2"]:
        return {"status": "success", "results": results}
    else:
        return {"status": "partial_failure"}
```

### Conditional Signal Waiting

```python
@workflow
async def conditional_approval(ctx, needs_approval: bool):
    if needs_approval:
        approval = await ctx.signal("approval_signal", timeout_ms=60000)
        if not approval.get("approved"):
            return {"status": "rejected"}

    # Proceed with operation
    result = await ctx.task("service", "operation")
    return {"status": "completed", "result": result}
```

### LLM with Tool Execution

```python
@function
async def agent_handler(ctx, query: str):
    # Register tools
    search = ctx.tools.register("search", handler=search_web, ...)
    calc = ctx.tools.register("calculator", handler=calculate, ...)

    # Generate with tools
    response = await ctx.llm.generate(
        prompt=query,
        tools=[search, calc],
        model="gpt-4o"
    )

    # Execute tool calls if needed
    if response.tool_calls:
        for tool_call in response.tool_calls:
            handler = ctx.tools.handler(tool_call.name)
            await handler(**tool_call.arguments)

    return response
```

## Next Steps

- [Functions](functions) - Using context in functions
- [Entity](entity) - Using context in entities
- [Workflows](workflows) - Using context in workflows
- [Agent](agent) - AI integration with context

---

## Entities

_Source: https://agnt5.com/sdk/python/entity_

> Stateful components with unique keys and single-writer consistency

Entities are stateful components identified by unique keys. Use entities to model AI agents with conversation history, workflow orchestrators, or any business object that maintains state across interactions.

## Key Characteristics

- **Unique Key** - Each instance identified by a unique key (e.g., `agent-conv-123`)
- **Private State** - Built-in key-value storage per instance
- **Single-Writer** - Automatic consistency - only one write operation per key at a time
- **Durable** - State survives crashes and restarts
- **Scalable** - Different keys execute in parallel

<Callout type="info">
**Implementation Status**

Entities are being implemented in Phase 2 of AGNT5 (Target: Q1 2025). The API shown represents the planned design. Check current SDK status for availability.
</Callout>

## Basic Usage

### Creating an Entity

```python
from agnt5 import entity

# Create entity type
agent = entity("ConversationAgent")

# Write method (exclusive access per key)
@agent.write
async def send_message(ctx, message: str) -> dict:
    history = await ctx.get("history", [])
    history.append({"role": "user", "content": message})

    response = await call_llm(history)
    history.append({"role": "assistant", "content": response})

    ctx.set("history", history)
    return {"response": response}

# Shared method (read-only, concurrent)
@agent.shared
async def get_history(ctx) -> list:
    return await ctx.get("history", [])
```

### Calling Entities

Call entity methods from functions:

```python
from agnt5 import function

@function
async def chat(ctx, conv_id: str, msg: str):
    # Call entity method with unique key
    return await ctx.entity("ConversationAgent", conv_id).send_message(msg)
```

## Entity API

### Core Methods

| API | Description |
| --- | --- |
| `entity("name")` | Create entity type |
| `@entity.write` | Write method (exclusive per key) |
| `@entity.shared` | Shared method (read-only, concurrent) |
| `ctx.get(key, default)` | Get state value |
| `ctx.set(key, value)` | Set state value |
| `ctx.delete(key)` | Delete state key |
| `ctx.entity(type, key).method()` | Call entity from function |

### State Operations


  

  
    ```python
    @agent.write
    async def process(ctx, data: dict) -> dict:
        # Get with default
        history = await ctx.get("history", [])
        count = await ctx.get("count", 0)

        return {"history": history, "count": count}
    ```
  

  
    ```python
    @agent.write
    async def update_state(ctx, new_data: dict) -> dict:
        # Set values
        ctx.set("last_update", datetime.now().isoformat())
        ctx.set("data", new_data)
        ctx.set("version", 2)

        return {"status": "updated"}
    ```
  

  
    ```python
    @agent.write
    async def clear_cache(ctx) -> dict:
        # Delete keys
        ctx.delete("cached_results")
        ctx.delete("temporary_data")

        return {"status": "cleared"}
    ```
  


## Common Patterns

### Conversational AI Agent

```python
agent = entity("ChatAgent")

@agent.write
async def send_message(ctx, message: str) -> dict:
    """Handle conversational turns with LLM."""
    history = await ctx.get("history", [])
    history.append({"role": "user", "content": message})

    # Generate response
    response = await ctx.llm.generate(
        prompt=history,
        model="gpt-4"
    )
    history.append({"role": "assistant", "content": response.text})

    # Keep last 20 messages
    if len(history) > 20:
        history = history[-20:]

    ctx.set("history", history)
    return {"response": response.text}

@agent.shared
async def get_history(ctx) -> list:
    """Get conversation history (read-only)."""
    return await ctx.get("history", [])

@agent.shared
async def get_message_count(ctx) -> int:
    """Get total message count."""
    history = await ctx.get("history", [])
    return len(history)
```

Usage:

```python
@function
async def chat_endpoint(ctx, conversation_id: str, message: str):
    # Call entity with unique conversation ID
    return await ctx.entity("ChatAgent", conversation_id).send_message(message)
```

### Research Agent

```python
research_agent = entity("ResearchAgent")

@research_agent.write
async def start_research(ctx, topic: str) -> dict:
    """Initialize research task."""
    ctx.set("topic", topic)
    ctx.set("findings", [])
    ctx.set("status", "in_progress")
    return {"status": "started", "topic": topic}

@research_agent.write
async def add_finding(ctx, finding: str, source: str) -> dict:
    """Add research finding."""
    findings = await ctx.get("findings", [])
    findings.append({
        "content": finding,
        "source": source,
        "timestamp": datetime.now().isoformat()
    })
    ctx.set("findings", findings)
    return {"count": len(findings)}

@research_agent.write
async def synthesize(ctx) -> dict:
    """Generate summary from findings."""
    findings = await ctx.get("findings", [])
    topic = await ctx.get("topic")

    # Use LLM to synthesize
    summary = await ctx.llm.generate(
        prompt=f"Synthesize these findings about {topic}: {findings}",
        model="gpt-4"
    )

    ctx.set("summary", summary.text)
    ctx.set("status", "completed")
    return {"summary": summary.text}

@research_agent.shared
async def get_progress(ctx) -> dict:
    """Check research progress."""
    return {
        "status": await ctx.get("status"),
        "topic": await ctx.get("topic"),
        "findings_count": len(await ctx.get("findings", []))
    }
```

### Workflow Orchestrator

```python
workflow = entity("WorkflowOrchestrator")

@workflow.write
async def start(ctx, steps: list) -> dict:
    """Start workflow execution."""
    ctx.set("steps", steps)
    ctx.set("current_step", 0)
    ctx.set("results", [])
    ctx.set("status", "running")
    return {"status": "started", "total_steps": len(steps)}

@workflow.write
async def complete_step(ctx, result: dict) -> dict:
    """Mark step as complete and store result."""
    results = await ctx.get("results", [])
    results.append(result)
    ctx.set("results", results)

    current = len(results)
    ctx.set("current_step", current)

    # Check if workflow is done
    steps = await ctx.get("steps", [])
    if current >= len(steps):
        ctx.set("status", "completed")

    return {"completed": current, "total": len(steps)}

@workflow.shared
async def get_progress(ctx) -> dict:
    """Get workflow progress."""
    return {
        "current_step": await ctx.get("current_step", 0),
        "total_steps": len(await ctx.get("steps", [])),
        "status": await ctx.get("status", "unknown")
    }
```

## Consistency & Concurrency

### Single-Writer Per Key

Only one write operation per entity key executes at a time:

```python
# Same key = serial execution (consistency guaranteed)
await ctx.entity("agent", "conv-1").send_message("msg1")  # Runs first
await ctx.entity("agent", "conv-1").send_message("msg2")  # Runs second

# No race conditions, no lost updates
```

### Parallel Execution Across Keys

Different entity keys execute in parallel:

```python
# Different keys = parallel execution (scales horizontally)
await ctx.entity("agent", "conv-1").send_message(msg)  # Parallel
await ctx.entity("agent", "conv-2").send_message(msg)  # Parallel
await ctx.entity("agent", "conv-3").send_message(msg)  # Parallel
```

### Shared Methods for Reads

Use `@entity.shared` for read-only operations that can run concurrently:

```python
# Multiple shared calls can run in parallel for same key
@agent.shared
async def get_history(ctx) -> list:
    return await ctx.get("history", [])

# These execute concurrently
await ctx.entity("agent", "conv-1").get_history()  # Concurrent
await ctx.entity("agent", "conv-1").get_history()  # Concurrent
```

## Best Practices

### 1. Choose Stable, Meaningful Keys

Use unique, stable identifiers for entity keys:


  

  
    ```python
    # Descriptive and stable
    "agent-conv-{conversation_id}"
    "workflow-{run_id}"
    "user-{user_id}"
    "research-{task_id}"
    ```
  

  
    ```python
    # Not descriptive
    "abc123"

    # Changes every time
    "user-{timestamp}"

    # Too generic
    "agent-1"
    ```
  


### 2. Design for Concurrency

Choose key granularity for optimal parallelism:

```python
# ✓ Good - One entity per conversation
await ctx.entity("ChatAgent", f"conv-{conv_id}").send_message(msg)

# ✗ Bad - Single global entity (serializes everything)
await ctx.entity("ChatAgent", "global").send_message(msg)
```

### 3. Use Shared for Read Operations

Enable concurrent reads with `@entity.shared`:

```python
# Write methods - exclusive access
@agent.write
async def update_state(ctx, data: dict):
    ctx.set("state", data)

# Read methods - concurrent access
@agent.shared
async def get_state(ctx) -> dict:
    return await ctx.get("state", {})
```

### 4. Keep State Minimal

Store only what you need:

```python
# ✓ Good - Essential state only
ctx.set("history", recent_messages[-20:])
ctx.set("summary", summary_text)

# ✗ Avoid - Excessive state
ctx.set("full_transcript", all_messages)  # Could be huge
ctx.set("raw_responses", all_llm_responses)  # Redundant
```

## Entity Use Cases

| Use Case | Entity Key | State Stored |
| --- | --- | --- |
| AI Chat Agent | `agent-conv-{id}` | Conversation history, context |
| Research Task | `research-{task_id}` | Findings, sources, summary |
| Workflow Orchestrator | `workflow-{run_id}` | Step progress, results |
| User Context | `user-{user_id}` | Preferences, personalization |
| Shopping Cart | `cart-{session_id}` | Items, totals, discounts |
| Game Session | `game-{session_id}` | Player state, score, progress |

## Functions vs Entities

| Aspect | Functions | Entities |
| --- | --- | --- |
| State | Stateless | Stateful (KV store) |
| Identity | No identity | Unique key per instance |
| Concurrency | Parallel by default | Serial per key, parallel across keys |
| Consistency | No consistency needed | Single-writer guarantee |
| Use Case | Transformations, API calls | Stateful AI agents, workflows |

**When to use Functions:**
- Stateless operations
- Independent requests
- Data transformations
- API integrations

**When to use Entities:**
- Stateful AI agents with memory
- Workflow orchestration
- User sessions and context
- Any state that needs consistency

## Next Steps

- [Context API](context) - Entity state operations and APIs
- [Functions](functions) - Stateless operations
- [Workflows](workflows) - Multi-step orchestration
- [Agent Component](agent) - AI agents built on entities

---

## Basic Worker

_Source: https://agnt5.com/sdk/python/examples/basic-worker_

> Simple standalone worker with function handlers

A minimal AGNT5 worker demonstrating function registration and execution.

## Complete Example

```python title="worker.py"
import asyncio
import logging
from agnt5 import Worker, function

# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

@function()
def greet(name: str) -> str:
    """Greet a user by name."""
    logger.info(f"Greeting user: {name}")
    return f"Hello, {name}!"

@function("math.add")
def add_numbers(a: int, b: int) -> int:
    """Add two numbers together."""
    logger.info(f"Adding {a} + {b}")
    return a + b

@function()
def process_data(data: dict) -> dict:
    """Process a data dictionary."""
    logger.info(f"Processing data with {len(data)} keys")

    # Simulate processing
    processed_data = {
        key: str(value).upper() if isinstance(value, str) else value
        for key, value in data.items()
    }

    return {
        "original": data,
        "processed": processed_data,
        "status": "completed"
    }

async def main():
    """Main worker entry point."""
    logger.info("Starting AGNT5 worker...")

    worker = Worker(
        service_name="basic-worker",
        service_version="1.0.0"
    )

    try:
        await worker.run()
    except KeyboardInterrupt:
        logger.info("Worker stopped by user")
    except Exception as e:
        logger.error(f"Worker error: {e}")
        raise

if __name__ == "__main__":
    asyncio.run(main())
```

## Running the Worker

### Deploy to AGNT5

```bash
# Authenticate and deploy
agnt5 auth login
agnt5 deploy
```

### Run the Worker Locally

```bash
# Run the worker
python worker.py
```

Expected output:

```
INFO:__main__:Starting AGNT5 worker...
INFO:agnt5.worker:Starting worker for service: basic-worker
INFO:agnt5.worker:Registered function: greet
INFO:agnt5.worker:Registered function: math.add
INFO:agnt5.worker:Registered function: process_data
INFO:agnt5.worker:Worker running, waiting for tasks...
```

## Testing Functions

### Using HTTP API

Test functions via the AGNT5 Gateway:

```bash
# Test greet function
curl -X POST http://localhost:8080/call \
  -H "Content-Type: application/json" \
  -d '{
    "serviceName": "basic-worker",
    "handlerName": "greet",
    "inputData": "QWxpY2U="
  }'

# Test math function
curl -X POST http://localhost:8080/call \
  -H "Content-Type: application/json" \
  -d '{
    "serviceName": "basic-worker",
    "handlerName": "math.add",
    "inputData": "eyJhIjogNSwgImIiOiAzfQ=="
  }'
```

<Callout type="info">
**Input Data Encoding**: The `inputData` field expects base64-encoded JSON. Use tools like `echo '{"a": 5, "b": 3}' | base64` to encode data.
</Callout>

### Using Python Client

```python title="test_client.py"
import asyncio
import json
import base64
from agnt5 import Client

async def test_functions():
    """Test all worker functions."""
    client = Client("http://localhost:8080")

    # Test greet function
    name_data = base64.b64encode(json.dumps("Alice").encode()).decode()
    result = await client.call(
        service_name="basic-worker",
        handler_name="greet",
        input_data=name_data
    )
    print(f"Greet result: {result}")

    # Test math function
    math_data = base64.b64encode(json.dumps({"a": 10, "b": 5}).encode()).decode()
    result = await client.call(
        service_name="basic-worker",
        handler_name="math.add",
        input_data=math_data
    )
    print(f"Math result: {result}")

    # Test data processing
    process_data = base64.b64encode(json.dumps({
        "name": "john doe",
        "status": "active",
        "count": 42
    }).encode()).decode()

    result = await client.call(
        service_name="basic-worker",
        handler_name="process_data",
        input_data=process_data
    )
    print(f"Process result: {result}")

if __name__ == "__main__":
    asyncio.run(test_functions())
```

## Error Handling

Add error handling to make functions more robust:

```python title="robust_worker.py"
import asyncio
import logging
from agnt5 import Worker, function

logger = logging.getLogger(__name__)

@function()
def safe_divide(a: float, b: float) -> dict:
    """Safely divide two numbers with error handling."""
    try:
        if b == 0:
            return {
                "error": "Division by zero",
                "result": None
            }

        result = a / b
        logger.info(f"Division successful: {a} / {b} = {result}")

        return {
            "result": result,
            "error": None
        }

    except Exception as e:
        logger.error(f"Unexpected error: {e}")
        return {
            "error": str(e),
            "result": None
        }

@function()
def validate_email(email: str) -> dict:
    """Validate email address format."""
    import re

    try:
        # Basic email validation
        pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
        is_valid = bool(re.match(pattern, email))

        return {
            "email": email,
            "valid": is_valid,
            "message": "Valid email" if is_valid else "Invalid email format"
        }

    except Exception as e:
        logger.error(f"Email validation error: {e}")
        return {
            "email": email,
            "valid": False,
            "message": f"Validation error: {e}"
        }

async def main():
    worker = Worker("robust-worker")
    await worker.run()

if __name__ == "__main__":
    asyncio.run(main())
```

## Configuration

### Environment Variables

```bash
# Service configuration
export AGNT5_SERVICE_NAME=basic-worker
export AGNT5_SERVICE_VERSION=1.0.0

# Coordinator endpoint
export AGNT5_COORDINATOR_ENDPOINT=http://localhost:9091

# Logging
export AGNT5_LOG_LEVEL=DEBUG

python worker.py
```

### Configuration File

```python title="config_worker.py"
import os
import asyncio
import logging
from agnt5 import Worker, function
from agnt5.logging import install_opentelemetry_logging

# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

# Install telemetry
install_opentelemetry_logging(logger=logger, level=logging.INFO)

@function()
def configured_handler(data: dict) -> dict:
    """Handler with access to configuration."""
    return {
        "service_name": os.getenv("AGNT5_SERVICE_NAME", "unknown"),
        "service_version": os.getenv("AGNT5_SERVICE_VERSION", "1.0.0"),
        "data": data
    }

async def main():
    # Worker with configuration
    worker = Worker(
        service_name=os.getenv("AGNT5_SERVICE_NAME", "configured-worker"),
        service_version=os.getenv("AGNT5_SERVICE_VERSION", "1.0.0"),
        coordinator_endpoint=os.getenv("AGNT5_COORDINATOR_ENDPOINT", "http://localhost:9091")
    )

    await worker.run()

if __name__ == "__main__":
    asyncio.run(main())
```

## Production Deployment

### Dockerfile

```dockerfile title="Dockerfile"
FROM python:3.11-slim

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application
COPY worker.py .

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:8000/health || exit 1

# Run worker
CMD ["python", "worker.py"]
```

### Docker Compose

```yaml title="docker-compose.yml"
version: '3.8'

services:
  worker:
    build: .
    environment:
      - AGNT5_SERVICE_NAME=basic-worker
      - AGNT5_SERVICE_VERSION=1.0.0
      - AGNT5_COORDINATOR_ENDPOINT=http://coordinator:9091
      - AGNT5_LOG_LEVEL=INFO
    restart: unless-stopped
    depends_on:
      - coordinator
    networks:
      - agnt5

  coordinator:
    image: agnt5/coordinator:latest
    ports:
      - "9091:9091"
    networks:
      - agnt5

networks:
  agnt5:
    driver: bridge
```

## Next Steps

- [ASGI Server Example](asgi-server) - Web application integration
- [Workflow Example](workflow-example) - Multi-step orchestration
- [Error Handling Patterns](error-handling) - Comprehensive error handling

---

## Functions

_Source: https://agnt5.com/sdk/python/functions_

> Handler decorators and function execution in the AGNT5 Python SDK

Functions are the core building blocks of AGNT5 applications. Use the `@function` decorator to register Python callables as invokable components that can be discovered and executed by the platform.

## Basic Usage

### Simple Function

```python
from agnt5 import function

@function()
def greet_user(name: str) -> str:
    """Greet a user by name."""
    return f"Hello, {name}!"
```

### Named Function

Override the registered name:

```python
@function("math.add")
def add_numbers(a: int, b: int) -> int:
    """Add two numbers together."""
    return a + b
```

### Function with Context

Access execution metadata through the context parameter:

```python
from agnt5 import function
from agnt5.components import ExecutionContext

@function()
def context_aware(ctx: ExecutionContext, data: dict) -> dict:
    """Process data with execution context."""
    return {
        "invocation_id": ctx.invocation_id,
        "service_name": ctx.metadata.get("service_name"),
        "processed_data": data,
        "component_type": ctx.component_type.value
    }
```

## Decorator Parameters

### `function(name=None)`

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | `str \| None` | Override the registered function name. Defaults to the original function name. |

```python
# Uses function name "process_data"
@function()
def process_data(data: dict) -> dict:
    return data

# Uses custom name "data_processor"
@function("data_processor")
def process_data(data: dict) -> dict:
    return data
```

## Handler Signatures

AGNT5 supports flexible function signatures to accommodate different use cases.

### Without Context

For simple stateless functions:

```python
@function()
def calculate_tax(amount: float, rate: float) -> float:
    return amount * rate

@function()
def format_message(template: str, **kwargs) -> str:
    return template.format(**kwargs)
```

### With Context

When you need access to invocation metadata:

```python
@function()
def audit_handler(ctx: ExecutionContext, action: str, data: dict) -> dict:
    """Handler that logs audit information."""
    import logging

    logger = logging.getLogger(__name__)
    logger.info(f"Audit: {action} from {ctx.invocation_id}")

    return {
        "action": action,
        "invocation_id": ctx.invocation_id,
        "data": data,
        "timestamp": time.time()
    }
```

## Async Functions

AGNT5 supports both synchronous and asynchronous functions:

### Async Handler

```python
import asyncio
from agnt5 import function

@function()
async def async_processor(data: dict) -> dict:
    """Async processing with I/O operations."""
    # Simulate async I/O
    await asyncio.sleep(0.1)

    # Async HTTP request example
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://api.example.com/process",
            json=data
        )
        external_result = response.json()

    return {
        "original": data,
        "external": external_result,
        "processed_at": datetime.utcnow().isoformat()
    }
```

### Async with Context

```python
@function()
async def async_context_handler(ctx: ExecutionContext, query: str) -> dict:
    """Async handler with context access."""

    # Use context for correlation
    correlation_id = ctx.metadata.get("correlation_id", ctx.invocation_id)

    # Async database query
    result = await database.execute(
        "SELECT * FROM items WHERE name LIKE %s",
        f"%{query}%"
    )

    return {
        "correlation_id": correlation_id,
        "query": query,
        "results": [dict(row) for row in result]
    }
```

## Streaming Functions

For functions that need to return multiple responses over time:

### Basic Streaming

```python
from agnt5 import function

@function(streaming=True)
async def stream_data(count: int):
    """Stream multiple data chunks."""
    for i in range(count):
        yield {
            "chunk": i,
            "data": f"Data chunk {i}",
            "timestamp": time.time()
        }
        await asyncio.sleep(0.1)  # Simulate processing time
```

### Streaming with Context

```python
@function(streaming=True)
async def stream_with_context(ctx: ExecutionContext, query: str):
    """Stream search results progressively."""
    search_id = ctx.invocation_id

    # Stream results as they're found
    async for result in search_engine.stream_search(query):
        yield {
            "search_id": search_id,
            "result": result,
            "timestamp": time.time()
        }
```

## Function Metadata

The SDK automatically captures and provides metadata about registered functions:

### Inspecting Functions

```python
from agnt5.decorators import get_registered_functions, get_function_metadata

# Get all registered functions
functions = get_registered_functions()
print(f"Registered functions: {list(functions.keys())}")

# Get metadata for a specific function
@function()
def sample_function(name: str, age: int = 25) -> dict:
    return {"name": name, "age": age}

metadata = get_function_metadata(sample_function)
print(metadata)
```

**Output:**

```python
{
    "name": "sample_function",
    "type": "function",
    "parameters": [
        {"name": "name", "type": "str", "required": True},
        {"name": "age", "type": "int", "required": False, "default": 25}
    ],
    "return_type": "dict"
}
```

### Runtime Annotations

The decorator adds runtime annotations to functions:

```python
@function()
def annotated_function(data: str) -> str:
    return data.upper()

# Check annotations
print(annotated_function._agnt5_handler_name)  # "annotated_function"
print(annotated_function._agnt5_is_function)   # True
```

## Error Handling

### Basic Error Handling

```python
@function()
def safe_divider(a: float, b: float) -> dict:
    """Safely divide two numbers."""
    try:
        if b == 0:
            return {"error": "Division by zero", "result": None}

        result = a / b
        return {"result": result, "error": None}

    except Exception as e:
        return {"error": str(e), "result": None}
```

### Context-Aware Error Handling

```python
import logging
from agnt5 import function
from agnt5.components import ExecutionContext

@function()
def robust_handler(ctx: ExecutionContext, data: dict) -> dict:
    """Handler with comprehensive error handling."""
    logger = logging.getLogger(__name__)

    try:
        # Log the invocation
        logger.info(f"Processing invocation {ctx.invocation_id}")

        # Validate input
        if not isinstance(data, dict):
            raise ValueError("Input must be a dictionary")

        required_fields = ["id", "name"]
        missing_fields = [field for field in required_fields if field not in data]
        if missing_fields:
            raise ValueError(f"Missing required fields: {missing_fields}")

        # Process data
        result = {
            "processed": True,
            "id": data["id"],
            "name": data["name"].upper(),
            "invocation_id": ctx.invocation_id
        }

        logger.info(f"Successfully processed {data['id']}")
        return result

    except ValueError as e:
        logger.warning(f"Validation error in {ctx.invocation_id}: {e}")
        return {"error": f"Validation error: {e}", "result": None}

    except Exception as e:
        logger.error(f"Unexpected error in {ctx.invocation_id}: {e}")
        return {"error": "Internal error", "result": None}
```

## Type Annotations

Use Python type hints for better documentation and validation:

### Basic Types

```python
from typing import Dict, List, Optional, Union

@function()
def typed_handler(
    name: str,
    age: int,
    tags: List[str],
    metadata: Optional[Dict[str, any]] = None
) -> Dict[str, Union[str, int, List[str]]]:
    """Handler with comprehensive type annotations."""
    return {
        "name": name,
        "age": age,
        "tags": tags,
        "has_metadata": metadata is not None
    }
```

### Pydantic Models

For complex data validation:

```python
from pydantic import BaseModel, Field
from typing import Optional
from agnt5 import function

class UserRequest(BaseModel):
    name: str = Field(..., min_length=1, max_length=100)
    email: str = Field(..., pattern=r'^[\w\.-]+@[\w\.-]+\.\w+$')
    age: Optional[int] = Field(None, ge=0, le=150)

class UserResponse(BaseModel):
    id: str
    name: str
    email: str
    age: Optional[int]
    created_at: str

@function()
def create_user(request: UserRequest) -> UserResponse:
    """Create a user with validation."""
    user_id = generate_user_id()

    return UserResponse(
        id=user_id,
        name=request.name,
        email=request.email,
        age=request.age,
        created_at=datetime.utcnow().isoformat()
    )
```

## Testing Functions

### Direct Testing

Test functions directly without the full platform:

```python
import pytest
from agnt5.decorators import execute_component
from agnt5.components import ExecutionContext, ComponentType

def test_greet_function():
    # Test with execute_component
    result = execute_component(
        "greet_user",
        b'{"name": "Alice"}',
        context=None
    )

    # Result is JSON bytes
    import json
    parsed = json.loads(result.decode())
    assert parsed == "Hello, Alice!"

def test_context_function():
    # Create mock context
    ctx = ExecutionContext(
        invocation_id="test-123",
        component_type=ComponentType.FUNCTION
    )

    # Test directly
    result = context_aware(ctx, {"test": "data"})
    assert result["invocation_id"] == "test-123"
```

### Async Testing

```python
import pytest
import asyncio

@pytest.mark.asyncio
async def test_async_function():
    result = await async_processor({"test": "data"})
    assert "original" in result
    assert "processed_at" in result
```

### Mock Context Testing

```python
from unittest.mock import Mock

def test_with_mock_context():
    # Create mock context
    mock_ctx = Mock(spec=ExecutionContext)
    mock_ctx.invocation_id = "mock-123"
    mock_ctx.component_type = ComponentType.FUNCTION
    mock_ctx.metadata = {"service_name": "test-service"}

    # Test function
    result = context_aware(mock_ctx, {"test": "data"})
    assert result["invocation_id"] == "mock-123"
    assert result["service_name"] == "test-service"
```

## Function Registry

### Registry Management

```python
from agnt5.decorators import (
    get_registered_functions,
    clear_registry,
    get_function_metadata
)

# Get all registered functions
functions = get_registered_functions()

# Clear registry (useful for testing)
clear_registry()

# Re-register functions
@function()
def new_function(data: str) -> str:
    return data.upper()

# Inspect metadata
metadata = get_function_metadata(new_function)
```

### Custom Registration

For advanced use cases, register functions manually:

```python
from agnt5.decorators import register_function

def my_handler(data: str) -> str:
    return data.lower()

# Manual registration
register_function("custom_handler", my_handler)
```

## Best Practices

### Function Design

1. **Keep functions focused** - Each function should have a single responsibility
2. **Use type hints** - Improve documentation and enable validation
3. **Handle errors gracefully** - Return error information rather than raising exceptions
4. **Log appropriately** - Use structured logging for debugging and monitoring

### Performance

1. **Minimize imports** - Import only what you need
2. **Use async for I/O** - Async functions for database queries and API calls
3. **Cache expensive operations** - Use local caching for repeated computations
4. **Batch operations** - Process multiple items together when possible

### Testing

1. **Test functions directly** - Unit test without the platform
2. **Mock external dependencies** - Use mocks for databases, APIs, etc.
3. **Test error conditions** - Ensure error handling works correctly
4. **Use fixtures** - Share common test data and setup

## Next Steps

- [Workflows](workflows) - Multi-step orchestration patterns
- [Worker Runtime](worker) - Configure and deploy workers
- [API Reference](api/decorators) - Complete decorator API reference
- [Examples](examples/basic-worker) - Real-world function examples

---

## Getting Started

_Source: https://agnt5.com/sdk/python/getting-started_

> Installation and first steps with the AGNT5 Python SDK

Get up and running with the AGNT5 Python SDK in minutes. This guide covers installation, your first worker, and local development setup.

## Installation

### System Requirements

- Python 3.8 or higher
- pip or uv package manager

### Install from PyPI

```bash
pip install agnt5
```

### Development Installation

For development or contributing to the SDK:

```bash
git clone https://github.com/agnt5/agnt5
cd agnt5/sdk/sdk-python
pip install -e .
```

### Verify Installation

```python
import agnt5
print(agnt5.__version__)
```

## First Worker

Create a simple worker with a greeting function:

```python title="worker.py"
import asyncio
from agnt5 import Worker, function

@function()
def greet(name: str) -> str:
    """Greet a user by name."""
    return f"Hello, {name}!"

@function("math_add")
def add_numbers(a: int, b: int) -> int:
    """Add two numbers together."""
    return a + b

async def main():
    worker = Worker(service_name="hello-service")
    await worker.run()

if __name__ == "__main__":
    asyncio.run(main())
```

## Deploy to AGNT5

### Install the CLI and Authenticate

```bash
# Install the AGNT5 CLI
brew install agnt5/tap/agnt5  # macOS
# or
curl -LsSf https://agnt5.com/cli.sh | bash  # Linux

# Authenticate
agnt5 auth login

# Deploy your worker
agnt5 deploy
```

### Run Your Worker Locally

In a new terminal, run your worker:

```bash
python worker.py
```

You should see output like:

```
INFO:agnt5.worker:Starting worker for service: hello-service
INFO:agnt5.worker:Registered function: greet
INFO:agnt5.worker:Registered function: math_add
INFO:agnt5.worker:Worker running, waiting for tasks...
```

## Test Your Functions

### Using HTTP API

Test your functions using the Gateway HTTP API:

```bash
# Test the greet function
curl -X POST http://localhost:8080/call \
  -H "Content-Type: application/json" \
  -d '{
    "serviceName": "hello-service",
    "handlerName": "greet",
    "inputData": "QWxpY2U="
  }'
```

The `inputData` is base64-encoded JSON. For `"Alice"`, the base64 is `"QWxpY2U="`.

### Using Python Client

```python
import asyncio
import json
import base64
from agnt5 import Client

async def test_functions():
    client = Client("http://localhost:8080")

    # Test greet function
    name = "Alice"
    input_data = base64.b64encode(json.dumps(name).encode()).decode()

    result = await client.call(
        service_name="hello-service",
        handler_name="greet",
        input_data=input_data
    )

    print(f"Greeting result: {result}")

    # Test add function
    numbers = {"a": 5, "b": 3}
    input_data = base64.b64encode(json.dumps(numbers).encode()).decode()

    result = await client.call(
        service_name="hello-service",
        handler_name="math_add",
        input_data=input_data
    )

    print(f"Addition result: {result}")

asyncio.run(test_functions())
```

## ASGI Integration

For web applications, use the ASGI runtime:

```python title="asgi_app.py"
from agnt5 import Worker, function

@function()
def api_handler(request: dict) -> dict:
    return {
        "message": "Hello from AGNT5!",
        "received": request
    }

# Create ASGI application
app = Worker("web-service", runtime="asgi")
app.enable_cors()  # Enable CORS for browser access
```

Run with uvicorn:

```bash
pip install uvicorn
uvicorn asgi_app:app --reload --port 8000
```

Test the ASGI endpoints:

```bash
# Health check
curl http://localhost:8000/health

# List available functions
curl http://localhost:8000/functions

# Call a function
curl -X POST http://localhost:8000/invoke/api_handler \
  -H "Content-Type: application/json" \
  -d '{"test": "data"}'
```

## Configuration

### Environment Variables

Configure your worker using environment variables:

```bash
export AGNT5_COORDINATOR_ENDPOINT=http://localhost:9091
export AGNT5_SERVICE_NAME=my-service
export AGNT5_LOG_LEVEL=DEBUG

python worker.py
```

### Configuration in Code

```python
import logging
from agnt5 import Worker
from agnt5.logging import install_opentelemetry_logging

# Configure logging
logging.basicConfig(level=logging.INFO)
install_opentelemetry_logging()

# Create worker with custom configuration
worker = Worker(
    service_name="configured-service",
    service_version="1.2.0",
    coordinator_endpoint="http://localhost:9091",
    runtime="standalone"
)
```

## Error Handling

Handle errors gracefully in your functions:

```python
from agnt5 import function
import logging

logger = logging.getLogger(__name__)

@function()
def safe_divide(a: float, b: float) -> dict:
    try:
        if b == 0:
            return {"error": "Division by zero", "result": None}

        result = a / b
        logger.info(f"Division successful: {a} / {b} = {result}")

        return {"result": result, "error": None}

    except Exception as e:
        logger.error(f"Unexpected error: {e}")
        return {"error": str(e), "result": None}
```

## Development Tips

### Hot Reload

During development, restart your worker when code changes:

```python title="dev_worker.py"
import asyncio
import sys
from pathlib import Path
from agnt5 import Worker, function

# Add auto-reload during development
if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        print("\nWorker stopped")
        sys.exit(0)
```

### Debugging

Enable debug logging to see detailed execution information:

```python
import logging
logging.basicConfig(level=logging.DEBUG)

from agnt5.logging import install_opentelemetry_logging
install_opentelemetry_logging(level=logging.DEBUG)
```

### Testing Functions

Test your functions locally without the full platform:

```python
from agnt5.decorators import execute_component

# Test function directly
result = execute_component("greet", b'{"name": "Alice"}')
print(result)
```

## Next Steps

### Core Primitives
- [Functions](functions) - Stateless operations with retries
- [Entities](entity) - Stateful components with unique keys
- [Workflows](workflows) - Multi-step orchestration
- [Context API](context) - Full API reference

### Agent Development Kit
- [Agents](agent) - Autonomous LLM-driven systems
- [Tools](tool) - Extend agent capabilities
- [Sessions](session) - Conversation management
- [Memory](memory) - Long-term knowledge storage

### Configuration
- [Worker Runtime](worker) - Configure and deploy workers
- [Examples](examples/) - Real-world usage patterns

---

## Memory

_Source: https://agnt5.com/sdk/python/memory_

> Long-term knowledge storage with semantic search for agents

Memory is a long-term knowledge storage system that enables agents to remember facts, preferences, and context across conversations. Unlike Session state (short-term), Memory provides persistent, searchable knowledge that agents build upon over time.

## Key Characteristics

- **Long-Term Persistence** - Knowledge survives across sessions and conversations
- **Semantic Search** - Find relevant memories using natural language queries
- **Smart Ingestion** - Automatically extract important facts using LLMs
- **Multiple Backends** - InMemory (dev), Vector (semantic), Database (persistent)
- **Built on Entity** - Inherits durability and consistency
- **Cross-Session** - Shared knowledge accessible to all agents

## Basic Usage

### Creating Memory


  

  
    ```python
    from agnt5 import Memory
    from agnt5.memory import InMemoryService

    # In-memory storage (no persistence)
    memory = Memory(service=InMemoryService())
    ```
  

  
    ```python
    from agnt5 import Memory
    from agnt5.memory import VectorMemoryService

    # Vector storage with semantic search
    memory = Memory(service=VectorMemoryService(
        embedding_model="text-embedding-3-small",
        vector_store="qdrant"
    ))
    ```
  

  
    ```python
    from agnt5 import Memory
    from agnt5.memory import DatabaseMemoryService

    # Database storage for reliability
    memory = Memory(service=DatabaseMemoryService(
        connection_string="postgresql://..."
    ))
    ```
  


### Storing and Retrieving Memories

```python
# Store individual memories
await memory.store(
    key="user_role",
    content="Senior Software Engineer specializing in distributed systems",
    type="user_info",
    confidence=0.95
)

await memory.store(
    key="project_context",
    content="Building a real-time analytics platform for financial data",
    type="project_info"
)

# Retrieve specific memories
memories = await memory.recall(["user_role", "project_context"])
for mem in memories:
    print(f"{mem.key}: {mem.content}")
```

### Semantic Search

```python
# Search using natural language
results = await memory.search(
    query="What does the user know about databases?",
    limit=5
)

for result in results:
    print(f"Score: {result.score:.2f}")
    print(f"Content: {result.content}")
    print(f"Source: {result.metadata.get('source_session')}")
```

### Integration with Agents

```python
from agnt5 import Agent, Session, Memory, LanguageModel

# Create memory
memory = Memory(service=VectorMemoryService())

# Store long-term knowledge
await memory.store("user_expertise", "PhD in Machine Learning, specializes in NLP")
await memory.store("preferred_tools", "Prefers PyTorch over TensorFlow")

# First conversation
session1 = Session(id="conv-001", user_id="researcher-123")
lm = LanguageModel()
agent = Agent(name="assistant", model=lm, memory=memory, session=session1)
await agent.run("Help me implement attention mechanisms")
# Agent recalls user's ML expertise and PyTorch preference

# Later conversation (different session)
session2 = Session(id="conv-042", user_id="researcher-123")
agent2 = Agent(name="assistant", model=lm, memory=memory, session=session2)
await agent2.run("Review my transformer code")
# Agent still remembers user's background and preferences
```

## Smart Ingestion

Automatically extract and store important information from conversations:

```python
# Agent conversation
session = Session(id="consultation-123", user_id="user-456")
agent = Agent(name="advisor", memory=memory, session=session)

await agent.run("I'm building a recommendation system for e-commerce")
await agent.run("We have 10 million users and need sub-100ms latency")
await agent.run("Our team is experienced with Python and Go")

# Extract and store important facts
memory_keys = await memory.ingest_from_session(
    session,
    strategy="smart"  # Uses LLM to identify important facts
)

# Memory now contains:
# - "User building recommendation system for e-commerce"
# - "System requirements: 10M users, <100ms latency"
# - "Team expertise: Python, Go"

# Future conversations automatically recall these facts
```

## Ingestion Strategies

Choose the right strategy for your use case:


  

  
    ```python
    # LLM identifies important facts
    await memory.ingest_from_session(session, strategy="smart")
    ```

    Best for: General conversations where important facts need to be identified
  

  
    ```python
    # Extract names, technologies, organizations
    await memory.ingest_from_session(session, strategy="entities")
    ```

    Best for: Extracting structured information like people, companies, technologies
  

  
    ```python
    # Store conversation summary
    await memory.ingest_from_session(session, strategy="summary")
    ```

    Best for: Creating concise summaries of long conversations
  


## Common Patterns

### User Profile Memory

Build comprehensive user profiles over time:

```python
class UserProfileMemory:
    def __init__(self, user_id: str, memory: Memory):
        self.user_id = user_id
        self.memory = memory
        self.prefix = f"user_{user_id}_"

    async def store_preference(self, category: str, value: str):
        """Store user preference."""
        await self.memory.store(
            key=f"{self.prefix}pref_{category}",
            content=value,
            type="preference",
            user_id=self.user_id
        )

    async def store_expertise(self, domain: str, level: str, details: str):
        """Store user expertise."""
        await self.memory.store(
            key=f"{self.prefix}expertise_{domain}",
            content=f"{level} expertise in {domain}: {details}",
            type="expertise",
            user_id=self.user_id
        )

    async def get_profile(self) -> Dict[str, Any]:
        """Retrieve complete user profile."""
        results = await self.memory.search(
            query=f"user {self.user_id} profile preferences expertise",
            limit=50
        )

        profile = {
            "preferences": {},
            "expertise": {},
            "context": []
        }

        for result in results:
            if result.metadata.get("type") == "preference":
                category = result.key.replace(f"{self.prefix}pref_", "")
                profile["preferences"][category] = result.content
            elif result.metadata.get("type") == "expertise":
                domain = result.key.replace(f"{self.prefix}expertise_", "")
                profile["expertise"][domain] = result.content

        return profile

# Usage
user_memory = UserProfileMemory("user-123", memory)
await user_memory.store_preference("language", "Python")
await user_memory.store_expertise("ml", "advanced", "10+ years in NLP")

profile = await user_memory.get_profile()
```

### Conversation Summarization

Archive long sessions as summaries:

```python
async def archive_session_to_memory(
    session: Session,
    memory: Memory,
    summary_threshold: int = 50
):
    """Archive long sessions as summaries in memory."""

    history = await session.history()

    if len(history) > summary_threshold:
        # Generate comprehensive summary
        from agnt5 import LanguageModel

        lm = LanguageModel()
        conversation = "\n".join([
            f"{msg.role}: {msg.content}" for msg in history
        ])

        summary = await lm.generate(
            prompt=f"""Summarize this conversation in 2-3 paragraphs.
            Focus on key decisions, important facts, and outcomes.

            Conversation:
            {conversation}

            Summary:""",
            max_tokens=300
        )

        # Store summary in memory
        await memory.store(
            key=f"session_summary_{session.id}",
            content=summary.text,
            type="session_summary",
            session_id=session.id,
            user_id=session.user_id,
            message_count=len(history)
        )

        # Optionally prune session to save space
        await session.prune(strategy="keep_summary")

# Usage
await archive_session_to_memory(session, memory, summary_threshold=100)
```

### Learning Agent

Agent that learns from every interaction:

```python
class LearningAgent:
    def __init__(self, name: str, model, tools, memory: Memory):
        self.agent = Agent(name=name, model=model, tools=tools, memory=memory)
        self.memory = memory

    async def run_and_learn(self, prompt: str, session: Session):
        """Execute task and learn from interaction."""

        # Run agent
        result = await self.agent.run(prompt, session=session)

        # Extract and store learnings
        memory_keys = await self.memory.ingest_from_session(
            session,
            strategy="smart"
        )

        # Store outcome for future reference
        await self.memory.store(
            key=f"interaction_{session.id}",
            content=f"Task: {prompt}\nOutcome: {result.output}",
            type="interaction_history",
            success=result.status == "completed"
        )

        return result

    async def recall_similar_tasks(self, prompt: str) -> List[Dict]:
        """Find similar past interactions."""
        return await self.memory.search(
            query=f"Similar to: {prompt}",
            limit=5
        )

# Usage
learning_agent = LearningAgent("assistant", lm, tools, memory)

# Agent learns from each interaction
result = await learning_agent.run_and_learn(
    "Debug this performance issue",
    session
)

# Later: Recall similar past work
similar = await learning_agent.recall_similar_tasks(
    "Another performance problem"
)
```

## Best Practices

### 1. Distinguish Memory from Session State

Use Memory for long-term, Session for short-term:


  

  
    | Aspect | Session State | Memory |
    | --- | --- | --- |
    | Lifetime | Single conversation | Indefinite |
    | Scope | Session-specific | Cross-session |
    | Search | Direct key access | Semantic search |
    | Purpose | Current context | Long-term knowledge |
    | Example | Shopping cart | User preferences |
  

  
    ```python
    # Session State - SHORT-TERM, conversation-specific
    session.set_state("current_task", "analyzing code")
    session.set_state("files_open", ["main.py", "test.py"])

    # Memory - LONG-TERM, cross-conversation
    await memory.store("user_expertise", "Expert in Python")
    await memory.store("coding_style", "Prefers functional programming")
    ```
  


### 2. Add Metadata for Better Retrieval

Enrich memories with metadata:

```python
await memory.store(
    key="technical_decision_001",
    content="Chose PostgreSQL for transactional data, Redis for caching",
    type="decision",
    category="architecture",
    confidence=0.9,
    source_session="planning-session-789",
    timestamp=datetime.now(),
    decision_maker="tech-lead-123",
    rationale="Need ACID guarantees and high read performance"
)

# Later: Search by metadata
postgres_decisions = await memory.search(
    query="database decisions",
    filter={"type": "decision", "category": "architecture"}
)
```

### 3. Implement Memory Maintenance

Manage memory lifecycle:

```python
async def maintain_memory(memory: Memory, user_id: str):
    """Prune old or low-confidence memories."""

    # Remove outdated information
    await memory.forget([
        key for key in await memory.list_keys(user_id=user_id)
        if is_outdated(key)
    ])

    # Update confidence scores based on usage
    for key in await memory.list_keys(user_id=user_id):
        mem = await memory.recall([key])
        if mem[0].metadata.get("last_accessed"):
            days_since_access = calculate_days_since(
                mem[0].metadata["last_accessed"]
            )
            new_confidence = calculate_confidence_decay(
                mem[0].metadata.get("confidence", 1.0),
                days_since_access
            )
            await memory.update(key, confidence=new_confidence)
```

## Session State vs Memory

| Aspect | Session State | Memory |
| --- | --- | --- |
| Lifetime | Single conversation | Indefinite |
| Scope | Session-specific | Cross-session |
| Search | Direct key access | Semantic search |
| Purpose | Current context | Long-term knowledge |
| Storage | Entity state | Entity + Vector DB |
| Example | Shopping cart | User preferences |

**When to use Session State:**
- Current conversation context
- Temporary workflow state
- UI state and navigation

**When to use Memory:**
- User profile and preferences
- Historical interactions
- Domain knowledge
- Learned facts and insights

## Next Steps

- [Session](session) - Short-term conversation state
- [Agent](agent) - Agents use Memory for context
- [Entity](entity) - Underlying primitive for Memory
- [Context API](context) - Memory context operations

---

## Sessions

_Source: https://agnt5.com/sdk/python/session_

> Conversation containers with scoped state and multi-agent coordination

Sessions are conversation containers built on the Entity primitive. They manage multi-turn interactions between users and AI agents, providing structured state management, message history, and audit trails.

## Key Characteristics

- **Built on Entity** - Inherits durability and consistency from Entity
- **Scoped State** - Organize state with session/user/app/temp scopes
- **Message History** - Automatic conversation tracking with metadata
- **Multi-Agent Ready** - Share context across multiple agents
- **Audit Trail** - Complete history of interactions for compliance
- **Flexible Retention** - Configurable data retention policies

## Basic Usage

### Creating a Session

```python
from agnt5 import Session

# Create session with user context
session = Session(
    id="conv-2024-001",
    app_name="research_assistant",
    user_id="user-123",
    metadata={"project": "ai-safety-research"}
)
```

### Managing Messages


  

  
    ```python
    # Append messages to conversation history
    await session.send_message({
        "role": "user",
        "content": "What are the key challenges in AI alignment?"
    })

    await session.send_message({
        "role": "assistant",
        "content": "The main challenges include value learning and robustness."
    })
    ```
  

  
    ```python
    # Get last 10 messages
    messages = await session.history(limit=10)

    # Get all messages
    all_messages = await session.history()

    # Filter by role
    user_messages = [m for m in all_messages if m["role"] == "user"]
    ```
  


### Scoped State Management

Session state uses four scopes for different persistence levels:

```python
# Session scope - conversation-specific (default)
session.set_state("shopping_cart", ["item1", "item2"])
session.set_state("current_step", "checkout")

# User scope - persists across all user sessions
session.set_state("language", "English", scope="user")
session.set_state("timezone", "America/Los_Angeles", scope="user")

# App scope - application-wide global state
session.set_state("api_version", "v2", scope="app")
session.set_state("feature_flags", {"new_ui": True}, scope="app")

# Temp scope - temporary invocation-specific
session.set_state("processing_step", "validation", scope="temp")
```

### Integration with Agents

```python
from agnt5 import Agent, Session, LanguageModel

# Create session
session = Session(
    id="support-ticket-456",
    user_id="customer-789",
    metadata={"ticket_type": "billing"}
)

# Create agent with session
lm = LanguageModel()
agent = Agent(
    name="support_agent",
    model=lm,
    instructions="You are a helpful customer support agent.",
    tools=[search_kb_tool, create_ticket_tool],
    session=session
)

# Agent automatically uses session for context
result = await agent.run("I need help with my recent charge")

# Session maintains full conversation history
history = await session.history()
```

## Common Patterns

### Multi-Agent Coordination

Share context across multiple specialized agents:

```python
# Create shared session
session = Session(
    id="research-workflow-001",
    user_id="researcher-123",
    metadata={"project": "quantum-computing-review"}
)

# Set shared context
session.set_state("research_topic", "quantum error correction")
session.set_state("target_depth", "comprehensive")

# Multiple specialized agents work together
literature_agent = Agent(
    name="literature_reviewer",
    session=session,
    tools=[paper_search]
)

code_agent = Agent(
    name="code_analyzer",
    session=session,
    tools=[github_search]
)

synthesis_agent = Agent(
    name="synthesizer",
    session=session,
    tools=[document_tool]
)

# Execute research pipeline
papers = await literature_agent.run("Find recent papers")
implementations = await code_agent.run("Find implementations")
report = await synthesis_agent.run("Synthesize findings")

# All agents see shared context and each other's work
full_history = await session.history()
```

### Agent Handoff Pattern

Seamlessly transfer conversations between specialized agents:

```python
session = Session(id="customer-inquiry-789", user_id="customer-456")

# Coordinator routes to appropriate specialist
coordinator = Agent(
    name="router",
    session=session,
    tools=[classification_tool]
)
routing = await coordinator.run("How do I upgrade my subscription?")

if routing.category == "billing":
    # Billing agent gets full conversation context
    billing_agent = Agent(
        name="billing_specialist",
        session=session,
        tools=[billing_tools]
    )
    result = await billing_agent.run("Continue from coordinator's analysis")
    # billing_agent sees all previous messages

elif routing.category == "technical":
    tech_agent = Agent(
        name="tech_support",
        session=session,
        tools=[tech_tools]
    )
    result = await tech_agent.run("Handle technical inquiry")
```

### Session State vs Memory


  

  
    | Aspect | Session State | Memory |
    | --- | --- | --- |
    | Scope | Conversation-specific | Cross-conversation |
    | Lifetime | Cleared after session | Persists indefinitely |
    | Use Case | Current context | Long-term knowledge |
    | Example | Current task, cart items | User preferences, history |
  

  
    ```python
    from agnt5 import Session, Memory

    session = Session(id="consultation-123", user_id="user-456")
    memory = Memory(service=VectorMemoryService())

    # Session State - SHORT-TERM, conversation-specific
    session.set_state("current_diagnosis", "initial assessment")
    session.set_state("symptoms_discussed", ["headache", "fatigue"])

    # Memory - LONG-TERM, cross-conversation knowledge
    await memory.store("patient_history", "Chronic migraines, diagnosed 2020")
    await memory.store("medication_allergies", "Penicillin, Sulfa drugs")

    # Session state clears after conversation
    # Memory persists indefinitely across all sessions
    ```
  


### Session Export and Audit

```python
# Create session with audit metadata
session = Session(
    id="compliance-audit-001",
    user_id="analyst-789",
    metadata={
        "regulation": "SOC2",
        "audit_period": "Q4-2024",
        "auditor": "external-firm"
    },
    retention={"ttl_days": 730}  # 2 years
)

# Conduct conversation with full tracking
agent = Agent(name="data_analyst", session=session)
await agent.run("Analyze user access patterns")

# Export session for compliance review
jsonl_export = await session.export(format="jsonl")
# Each line contains: timestamp, role, message, metadata, tool_calls

# Query specific events
recent_events = await session.events(since="2024-01-01", limit=100)

# Prune old messages while keeping metadata
await session.prune(strategy="keep_last_50")
```

### Long-Running Sessions with Pruning

```python
# Create session with automatic pruning
session = Session(
    id="long-conversation-456",
    user_id="user-123",
    metadata={"type": "ongoing_project"}
)

# After many interactions, prune intelligently
await session.prune(strategy="keep_important")  # Uses LLM
await session.prune(strategy="sliding_window", window_size=100)
await session.prune(strategy="summarize_old", threshold=50)

# Session remains performant even with thousands of messages
```

## Configuration

### Session Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `id` | `str` | Unique session identifier |
| `app_name` | `str \| None` | Application name |
| `user_id` | `str \| None` | User identifier |
| `metadata` | `dict \| None` | Session metadata |
| `retention` | `dict \| None` | Retention policy configuration |

### Retention Policies

Configure data retention:


  

  
    ```python
    # For compliance-sensitive applications
    session = Session(
        id="healthcare-session",
        retention={
            "ttl_days": 2555,  # 7 years (HIPAA)
            "auto_prune": False,  # Manual control
            "immutable": True  # Prevent deletion
        }
    )
    ```
  

  
    ```python
    # For performance-sensitive applications
    session = Session(
        id="chat-session",
        retention={
            "ttl_days": 30,  # 30-day retention
            "auto_prune": True,  # Automatic cleanup
            "prune_strategy": "sliding_window",
            "max_messages": 1000
        }
    )
    ```
  


## Best Practices

### 1. Use Appropriate State Scopes

Match state scope to persistence requirements:

```python
# ✓ Session scope - conversation-specific
session.set_state("current_page", 3)
session.set_state("draft_document", content)

# ✓ User scope - user preferences
session.set_state("theme", "dark", scope="user")
session.set_state("notification_preference", "email", scope="user")

# ✓ App scope - global configuration
session.set_state("rate_limit", 1000, scope="app")
session.set_state("feature_flags", flags, scope="app")

# ✓ Temp scope - transient data
session.set_state("validation_step", "in_progress", scope="temp")
```

### 2. Design for Multi-Agent Coordination

Structure session state for agent collaboration:

```python
# Good - Clear coordination structure
session.set_state("workflow_stage", "research")
session.set_state("agent_outputs", {
    "researcher": {"status": "completed", "findings": [...]},
    "analyzer": {"status": "in_progress"},
    "writer": {"status": "pending"}
})

# Agents can check dependencies
current_stage = session.get_state("workflow_stage")
researcher_output = session.get_state("agent_outputs")["researcher"]
```

### 3. Implement Retention Strategies

Manage session lifecycle appropriately:

```python
# For regulated industries
session = Session(
    id="medical-consultation",
    retention={
        "ttl_days": 2555,  # Legal requirement
        "immutable": True
    }
)

# For ephemeral conversations
session = Session(
    id="temp-chat",
    retention={
        "ttl_days": 1,  # Delete after 1 day
        "auto_prune": True
    }
)
```

## Entity vs Session

| Aspect | Entity | Session |
| --- | --- | --- |
| Purpose | General stateful primitive | Conversation-specific |
| State Structure | Flexible key-value | Opinionated message + state |
| API | Low-level (get/set/delete) | High-level (send_message/history) |
| Scoping | Manual | Built-in (session/user/app/temp) |
| Audit | Manual event tracking | Automatic conversation log |
| Use Case | Custom stateful components | AI agent conversations |

**When to use Entity:**
- Building custom stateful patterns
- Need complete control over state structure
- Non-conversation workloads

**When to use Session:**
- AI agent conversations
- Multi-agent coordination needed
- Audit trails required
- Standard conversation patterns

## Next Steps

- [Entity](entity) - Underlying primitive for Session
- [Agent](agent) - Agents use Sessions for context
- [Memory](memory) - Long-term storage vs Session state
- [Context API](context) - Session context operations

---

## Tools

_Source: https://agnt5.com/sdk/python/tool_

> Callable capabilities that extend agent abilities with automatic schema extraction

Tools are callable capabilities that extend what agents can do. Tools provide structured interfaces to functions, APIs, services, and other agents, with automatic schema extraction from Python code.

## Key Characteristics

- **Automatic Schema** - Extract input/output schemas from docstrings and type hints
- **Multiple Types** - Function, Hosted, MCP, OpenAPI, and Agent tools
- **Built on Function** - Inherits durability and retry logic
- **Confirmation Policies** - Optional user approval for dangerous operations
- **Rich Metadata** - Descriptions, examples, and parameter constraints

## Basic Usage

### Function Tools with Auto-Schema

The simplest way to create tools is with the `@tool()` decorator:

```python
from agnt5 import tool

@tool(auto_schema=True)
def search_web(query: str, max_results: int = 10) -> List[Dict[str, str]]:
    """Search the web for information.

    Args:
        query: The search query string
        max_results: Maximum number of results to return

    Returns:
        List of search results with title, url, and snippet
    """
    # Implementation
    return search_results
```

**Schema automatically extracted:**
```json
{
  "name": "search_web",
  "description": "Search the web for information.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": {"type": "string", "description": "The search query string"},
      "max_results": {"type": "integer", "default": 10}
    },
    "required": ["query"]
  }
}
```

### Using Tools with Agents

```python
from agnt5 import Agent, tool, LanguageModel

@tool(auto_schema=True)
def calculate_area(length: float, width: float) -> float:
    """Calculate the area of a rectangle.

    Args:
        length: Length in meters
        width: Width in meters

    Returns:
        Area in square meters
    """
    return length * width

lm = LanguageModel()
agent = Agent(
    name="math_assistant",
    model=lm,
    tools=[calculate_area],
    instructions="Help users with geometry calculations."
)

result = await agent.run("What's the area of a 5m by 3m room?")
# Agent automatically calls calculate_area(5.0, 3.0)
```

## Tool Types

### Function Tools

Direct Python function execution:


  

  
    ```python
    @tool(auto_schema=True)
    def get_weather(city: str) -> Dict[str, Any]:
        """Get current weather for a city."""
        # API call
        return weather_data
    ```
  

  
    ```python
    from typing import List, Optional

    @tool(auto_schema=True)
    def search_documentation(
        query: str,
        language: str = "python",
        max_results: int = 5
    ) -> List[Dict[str, str]]:
        """Search official language documentation.

        Use this tool when you need specific functions, classes,
        or usage examples from official documentation.

        Args:
            query: Function name, class, or concept to search for
            language: Programming language (python, javascript, go, rust)
            max_results: Maximum number of results to return

        Returns:
            List of documentation sections with title, url, and examples

        Examples:
            >>> search_documentation("asyncio.gather", "python")
            [{"title": "asyncio.gather", "url": "...", "example": "..."}]
        """
        # Implementation
        return search_results
    ```
  


### Hosted Tools

Tools deployed as durable AGNT5 workers:

```python
from agnt5 import worker
from agnt5.tools import HostedTool

# Define worker function
@worker.handler
def analyze_data(data: Dict) -> Dict:
    """Worker function for complex data analysis."""
    # Heavy computation here
    return analysis_results

# Create hosted tool
analysis_tool = HostedTool(
    name="analyze_data",
    description="Perform complex data analysis",
    endpoint="agnt5://data-analysis-service/analyze_data"
)

# Use with agent
agent = Agent(name="analyst", tools=[analysis_tool])
```

### MCP Tools

Integrate with Model Context Protocol servers:

```python
from agnt5.tools import MCPTool

# Connect to MCP server
filesystem_tool = MCPTool(
    name="filesystem",
    mcp_server_url="http://localhost:3000/mcp",
    capabilities=["read_file", "write_file", "list_directory"]
)

agent = Agent(name="file_assistant", tools=[filesystem_tool])
```

### OpenAPI Tools

Generate tools from OpenAPI specifications:

```python
from agnt5.tools import OpenAPITool

# Create tools from OpenAPI spec
github_tools = OpenAPITool.from_spec(
    spec_url="https://api.github.com/openapi.json",
    operations=["get_repo", "list_issues", "create_issue"]
)

agent = Agent(name="github_bot", tools=github_tools)
```

## Tool Configuration

### Manual Schema Definition

For more control, define schemas explicitly:

```python
from agnt5 import Tool

search_tool = Tool(
    name="search",
    description="Search for information",
    input_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string", "minLength": 1},
            "filters": {"type": "object"}
        },
        "required": ["query"]
    },
    handler=search_function
)
```

### Confirmation for Dangerous Operations

Require user approval for destructive actions:

```python
@tool(auto_schema=True, confirmation=True)
def delete_database(database_name: str) -> Dict[str, str]:
    """Delete a database permanently.

    Args:
        database_name: Name of the database to delete

    Returns:
        Status of deletion operation

    Warning:
        This operation is irreversible and will delete all data.
    """
    # Requires human approval before execution
    pass

# Agent proposes deletion but waits for approval
agent = Agent(name="admin", tools=[delete_database])
result = await agent.run("Clean up the test database")
# User receives confirmation prompt before tool executes
```

## Common Patterns

### Tool Composition

Combine multiple tools for complex capabilities:

```python
@tool(auto_schema=True)
def search_papers(query: str, year_from: int = 2020) -> List[Dict]:
    """Search academic papers."""
    pass

@tool(auto_schema=True)
def download_pdf(url: str) -> bytes:
    """Download PDF document."""
    pass

@tool(auto_schema=True)
def extract_text(pdf_data: bytes) -> str:
    """Extract text from PDF."""
    pass

# Agent orchestrates multiple tools
research_agent = Agent(
    name="researcher",
    tools=[search_papers, download_pdf, extract_text],
    instructions="Search papers, download them, and extract key findings."
)

result = await research_agent.run("Survey recent work on transformers")
# Agent chains: search_papers → download_pdf → extract_text
```

### Tool Error Handling

Tools with robust error handling:

```python
@tool(auto_schema=True)
def fetch_stock_price(symbol: str) -> Dict[str, Any]:
    """Fetch current stock price.

    Args:
        symbol: Stock ticker symbol (e.g., 'AAPL', 'GOOGL')

    Returns:
        Stock price data

    Raises:
        ValueError: If symbol is invalid
        ConnectionError: If market data service is unavailable
    """
    try:
        price_data = market_api.get_price(symbol)
        return {
            "symbol": symbol,
            "price": price_data.current,
            "change": price_data.change
        }
    except InvalidSymbolError:
        raise ValueError(f"Invalid stock symbol: {symbol}")
    except MarketAPIError as e:
        raise ConnectionError(f"Market data unavailable: {e}")

# Agent handles tool errors gracefully
agent = Agent(name="stock_advisor", tools=[fetch_stock_price])
```

### Dynamic Tool Registration

Register tools at runtime based on context:

```python
# Base toolset
base_tools = [search_tool, calculate_tool]

# Add specialized tools based on user role
if user.role == "admin":
    admin_tools = [delete_user_tool, modify_permissions_tool]
    all_tools = base_tools + admin_tools
else:
    all_tools = base_tools

agent = Agent(
    name="assistant",
    tools=all_tools,
    instructions=f"You are assisting a {user.role}."
)
```

### Tool with Context Access

Tools can access execution context for advanced operations:

```python
from agnt5 import tool, Context

@tool(auto_schema=True)
async def store_memory(ctx: Context, key: str, value: str) -> Dict[str, str]:
    """Store information in long-term memory.

    Args:
        ctx: Execution context (automatically provided)
        key: Memory key
        value: Content to store

    Returns:
        Confirmation of storage
    """
    # Access context for durable storage
    await ctx.memory.set(key, value)

    return {
        "status": "stored",
        "key": key,
        "timestamp": ctx.now()
    }

# Context is automatically injected when tool is called
agent = Agent(name="memory_agent", tools=[store_memory])
```

## Best Practices

### 1. Write Clear Tool Descriptions

Good descriptions help agents use tools correctly:


  

  
    ```python
    @tool(auto_schema=True)
    def search_documentation(query: str, language: str = "python") -> List[Dict]:
        """Search official language documentation for code examples and API references.

        Use this tool when you need to find specific functions, classes, or usage
        examples from official documentation. Returns relevant documentation sections
        with code examples.

        Args:
            query: Specific function name, class, or concept to search for
            language: Programming language (python, javascript, go, rust)

        Returns:
            List of documentation sections with title, url, and code examples
        """
        pass
    ```
  

  
    ```python
    @tool(auto_schema=True)
    def search(q: str) -> List:
        """Search for stuff."""  # Too vague
        pass
    ```
  


### 2. Use Type Hints and Docstrings

Enable automatic schema extraction:

```python
from typing import List, Dict, Optional

@tool(auto_schema=True)
def analyze_sentiment(
    text: str,
    language: str = "en",
    return_scores: bool = False
) -> Dict[str, Any]:
    """Analyze sentiment of text.

    Args:
        text: Text to analyze (minimum 10 characters)
        language: ISO language code (en, es, fr, de)
        return_scores: Include detailed confidence scores

    Returns:
        Sentiment analysis with label (positive/negative/neutral)
        and optional confidence scores
    """
    # Type hints + docstring = complete schema
    pass
```

### 3. Implement Confirmation for Dangerous Operations

Protect users from destructive actions:

```python
# Dangerous operations should require confirmation
@tool(auto_schema=True, confirmation=True)
def execute_code(code: str, language: str = "python") -> Dict[str, str]:
    """Execute arbitrary code in a sandboxed environment.

    Warning:
        Code execution can be dangerous. Requires explicit user approval.
    """
    pass

@tool(auto_schema=True, confirmation=True)
def send_email_blast(recipients: List[str], subject: str, body: str) -> Dict:
    """Send email to multiple recipients.

    Warning:
        Bulk email requires confirmation to prevent spam.
    """
    pass
```

## Function vs Tool

| Aspect | Function | Tool |
| --- | --- | --- |
| Purpose | General computation | Agent capability |
| Schema | Optional | Required (auto-generated) |
| Discovery | Manual invocation | Agent-driven selection |
| Metadata | Basic | Rich (description, examples) |
| Use Case | Backend logic | Agent actions |

**When to use Function:**
- Backend processing
- Internal system operations
- Not exposed to agents

**When to use Tool:**
- Agent capabilities
- External system integration
- User-facing operations

## Next Steps

- [Functions](functions) - Underlying primitive for tools
- [Agent](agent) - Agents use tools for actions
- [Context API](context) - Tool context operations
- [Worker](worker) - Hosted tool deployment

---

## Worker Runtime

_Source: https://agnt5.com/sdk/python/worker_

> Configure and deploy Python workers for AGNT5

The `Worker` class is the high-level runtime that integrates with the AGNT5 platform, automatically registers decorated components, and handles execution coordination.

## Worker Configuration

### Basic Worker

```python
import asyncio
from agnt5 import Worker, function

@function()
def hello(name: str) -> str:
    return f"Hello, {name}!"

async def main():
    worker = Worker(service_name="hello-service")
    await worker.run()

if __name__ == "__main__":
    asyncio.run(main())
```

### Configuration Parameters

```python
worker = Worker(
    service_name="my-service",           # Required: Service identifier
    service_version="1.2.0",             # Version string (default: "1.0.0")
    coordinator_endpoint="http://localhost:9091",  # Worker coordinator URL
    runtime="standalone"                  # Runtime mode: "standalone" or "asgi"
)
```

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `service_name` | `str` | Service identifier for registration | **Required** |
| `service_version` | `str` | Version string for this service | `"1.0.0"` |
| `coordinator_endpoint` | `str` | Worker coordinator URL | `"http://localhost:9091"` |
| `runtime` | `str` | Runtime adapter: `"standalone"` or `"asgi"` | `"standalone"` |

## Runtime Modes

### Standalone Runtime

For background workers, batch processing, and daemon processes:

```python
import asyncio
from agnt5 import Worker, function

@function()
def background_task(data: dict) -> dict:
    # Process data in background
    return {"processed": True, "result": data}

async def main():
    # Standalone worker blocks until stopped
    worker = Worker(
        service_name="background-processor",
        runtime="standalone"
    )
    await worker.run()

if __name__ == "__main__":
    asyncio.run(main())
```

**Characteristics:**
- Blocks until manually stopped (Ctrl+C)
- Connects to worker coordinator
- Ideal for background processing
- Built-in signal handling
- OpenTelemetry integration

### ASGI Runtime

For web applications and HTTP endpoints:

```python
from agnt5 import Worker, function

@function()
def web_handler(request: dict) -> dict:
    return {"message": "Hello from AGNT5!", "data": request}

# Create ASGI application
app = Worker(
    service_name="web-service",
    runtime="asgi"
)

# Enable CORS for browser access
app.enable_cors()
```

Run with any ASGI server:

```bash
# Install ASGI server
pip install uvicorn

# Run the application
uvicorn main:app --reload --port 8000
```

**ASGI Endpoints:**

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | Health check endpoint |
| `/functions` | GET | List registered functions |
| `/invoke/{handler}` | POST | Invoke specific function |

## Environment Configuration

### Environment Variables

Configure workers using environment variables:

```bash
# Service configuration
export AGNT5_SERVICE_NAME=my-service
export AGNT5_SERVICE_VERSION=2.0.0
export AGNT5_COORDINATOR_ENDPOINT=https://coordinator.agnt5.com

# Logging configuration
export AGNT5_LOG_LEVEL=INFO
export AGNT5_LOG_FORMAT=json

# Runtime configuration
export AGNT5_RUNTIME=standalone
export AGNT5_DISABLE_TELEMETRY=false
```

### Configuration Priority

Configuration sources in order of precedence:

1. **Constructor parameters** - Highest priority
2. **Environment variables** - Medium priority
3. **Default values** - Lowest priority

```python
# This worker uses constructor values over environment
worker = Worker(
    service_name="explicit-service",  # Overrides AGNT5_SERVICE_NAME
    coordinator_endpoint="http://localhost:9091"
)
```

## Worker Lifecycle

### Initialization

```python
async def main():
    worker = Worker("my-service")

    # Worker validates Rust extension availability
    # Creates runtime adapter (standalone or ASGI)
    # Installs OpenTelemetry logging
    # Registers all decorated functions and workflows

    await worker.run()  # Starts the worker loop
```

### Registration Process

1. **Function Discovery**: Scans for `@function` decorated callables
2. **Workflow Discovery**: Scans for `@workflow` decorated factories
3. **Component Registration**: Sends metadata to coordinator
4. **Service Announcement**: Service becomes available for invocations

### Graceful Shutdown

```python
import signal
import asyncio
from agnt5 import Worker

class GracefulWorker:
    def __init__(self):
        self.worker = Worker("graceful-service")
        self.shutdown_requested = False

    async def run(self):
        # Register signal handlers
        signal.signal(signal.SIGTERM, self._signal_handler)
        signal.signal(signal.SIGINT, self._signal_handler)

        try:
            await self.worker.run()
        except KeyboardInterrupt:
            print("Shutdown requested via keyboard interrupt")
        finally:
            await self._cleanup()

    def _signal_handler(self, signum, frame):
        print(f"Received signal {signum}, initiating graceful shutdown...")
        self.shutdown_requested = True

    async def _cleanup(self):
        print("Cleaning up resources...")
        # Perform cleanup tasks
        # Close database connections
        # Finish in-flight requests
        # Remove OpenTelemetry handlers
        print("Cleanup complete")

async def main():
    graceful_worker = GracefulWorker()
    await graceful_worker.run()

if __name__ == "__main__":
    asyncio.run(main())
```

## ASGI Integration

### Basic ASGI App

```python
from agnt5 import Worker, function

@function()
def api_endpoint(data: dict) -> dict:
    return {"status": "success", "received": data}

# Create ASGI app
app = Worker("api-service", runtime="asgi")
```

### CORS Configuration

Enable CORS for browser access:

```python
# Enable CORS with defaults (allows all origins)
app.enable_cors()

# Enable CORS with specific origins
app.enable_cors(origins=["https://myapp.com", "https://localhost:3000"])

# Disable CORS
app.disable_cors()
```

### Custom Middleware

Add ASGI middleware:

```python
from starlette.middleware.cors import CORSMiddleware
from starlette.middleware.gzip import GZipMiddleware

app = Worker("api-service", runtime="asgi")

# Add middleware (if using Starlette/FastAPI patterns)
# Note: This is conceptual - actual middleware integration depends on ASGI runtime implementation
```

### Error Handling

ASGI runtime provides consistent error responses:

```python
# Function that raises an exception
@function()
def failing_function(data: dict) -> dict:
    raise ValueError("Something went wrong")

# ASGI runtime catches and formats the error:
# {
#   "error": "Function failing_function failed: Something went wrong",
#   "status": 500
# }
```

## Worker Methods

### Runtime Control

```python
worker = Worker("my-service")

# Check if worker is running
if worker.is_running():
    print("Worker is active")

# For ASGI workers only - get ASGI callable
if worker.runtime == "asgi":
    asgi_app = worker.__call__  # ASGI callable interface
```

### Component Registration

```python
# Manual component registration (usually automatic)
worker._register_components()

# Internal message handling (not part of public API)
# worker._handle_message(request)
```

## Observability

### OpenTelemetry Integration

Workers automatically install OpenTelemetry logging:

```python
import logging
from agnt5 import Worker
from agnt5.logging import install_opentelemetry_logging, remove_opentelemetry_logging

# Custom logging setup
logger = logging.getLogger("my-service")

# Install telemetry with custom formatter
install_opentelemetry_logging(
    logger=logger,
    level=logging.DEBUG,
    format_string="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
)

worker = Worker("my-service")

# Telemetry is automatically cleaned up on worker shutdown
```

### Structured Logging

```python
import logging
from agnt5 import Worker, function

logger = logging.getLogger(__name__)

@function()
def logged_function(ctx, data: dict) -> dict:
    # Structured logging with context
    logger.info(
        "Processing function",
        extra={
            "invocation_id": ctx.invocation_id,
            "service_name": ctx.metadata.get("service_name"),
            "data_size": len(str(data))
        }
    )

    result = {"processed": True}

    logger.info(
        "Function completed",
        extra={
            "invocation_id": ctx.invocation_id,
            "success": True
        }
    )

    return result
```

## Development Patterns

### Hot Reload Development

```python
import os
import sys
from agnt5 import Worker, function

# Development configuration
if os.getenv("ENVIRONMENT") == "development":
    import logging
    logging.basicConfig(level=logging.DEBUG)

@function()
def development_handler(data: dict) -> dict:
    return {"env": "development", "data": data}

async def main():
    worker = Worker(
        service_name="dev-service",
        coordinator_endpoint=os.getenv("COORDINATOR_URL", "http://localhost:9091")
    )

    try:
        await worker.run()
    except KeyboardInterrupt:
        print("\nDevelopment worker stopped")
        sys.exit(0)

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())
```

### Testing Workers

```python
import pytest
from unittest.mock import AsyncMock, patch
from agnt5 import Worker, function

@function()
def test_function(data: str) -> str:
    return data.upper()

@pytest.fixture
async def mock_worker():
    with patch('agnt5.worker.PyWorker'):
        worker = Worker("test-service")
        yield worker

@pytest.mark.asyncio
async def test_worker_registration(mock_worker):
    # Test component registration
    mock_worker._register_components()

    # Verify functions are registered
    from agnt5.decorators import get_registered_functions
    functions = get_registered_functions()
    assert "test_function" in functions

@pytest.mark.asyncio
async def test_worker_asgi_mode():
    app = Worker("test-service", runtime="asgi")
    assert callable(app)  # ASGI callable interface
```

## Production Deployment

### Container Deployment

```dockerfile
FROM python:3.11-slim

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY . .

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:8000/health || exit 1

# Run worker
CMD ["python", "worker.py"]
```

### Environment Configuration

```bash
# Production environment variables
AGNT5_SERVICE_NAME=production-service
AGNT5_SERVICE_VERSION=1.2.0
AGNT5_COORDINATOR_ENDPOINT=https://coordinator.agnt5.com
AGNT5_LOG_LEVEL=INFO
AGNT5_LOG_FORMAT=json
```

### Health Monitoring

```python
import asyncio
import logging
from agnt5 import Worker, function

logger = logging.getLogger(__name__)

@function()
def health_check() -> dict:
    """Health check endpoint."""
    return {
        "status": "healthy",
        "service": "production-service",
        "timestamp": time.time()
    }

async def main():
    worker = Worker(
        service_name="production-service",
        service_version=os.getenv("SERVICE_VERSION", "1.0.0")
    )

    logger.info("Starting production worker")

    try:
        await worker.run()
    except Exception as e:
        logger.error(f"Worker failed: {e}")
        raise
    finally:
        logger.info("Worker shutdown complete")

if __name__ == "__main__":
    asyncio.run(main())
```

## Best Practices

### Service Design

1. **Service Naming** - Use consistent, descriptive service names
2. **Version Management** - Use semantic versioning for service versions
3. **Resource Management** - Clean up resources in shutdown handlers
4. **Error Handling** - Handle exceptions gracefully in workers
5. **Health Checks** - Implement health check functions for monitoring

### Performance

1. **Connection Pooling** - Reuse database and HTTP connections
2. **Async Operations** - Use async functions for I/O operations
3. **Resource Limits** - Configure appropriate memory and CPU limits
4. **Scaling** - Deploy multiple worker instances for high throughput
5. **Monitoring** - Track worker performance and error rates

### Security

1. **Input Validation** - Validate all function inputs
2. **Error Messages** - Don't expose sensitive information in errors
3. **Authentication** - Use proper authentication for coordinator connections
4. **Network Security** - Use secure connections (HTTPS/TLS) in production
5. **Secrets Management** - Use environment variables for sensitive configuration

## Next Steps

### Core Primitives
- [Functions](functions) - Stateless operations with retries
- [Entities](entity) - Stateful components
- [Workflows](workflows) - Multi-step orchestration
- [Context API](context) - Full API reference

### Agent Development Kit
- [Agents](agent) - Autonomous LLM-driven systems
- [Tools](tool) - Extend agent capabilities
- [Sessions](session) - Conversation management
- [Memory](memory) - Long-term knowledge storage

### Resources
- [Examples](examples/basic-worker) - Worker deployment examples

---

## Workflows

_Source: https://agnt5.com/sdk/python/workflows_

> Multi-step orchestration and durable execution patterns

Workflows enable durable, multi-step orchestration with automatic recovery, state persistence, and complex dependency management. Built on the AGNT5 orchestration plane for exactly-once execution guarantees.

## Basic Workflow

### Simple Sequential Workflow

```python
from agnt5 import workflow, task_step
from agnt5.workflows import FlowDefinition

@workflow()
def data_pipeline() -> FlowDefinition:
    return FlowDefinition([
        task_step(
            name="extract",
            service_name="etl-service",
            handler_name="extract_data"
        ),
        task_step(
            name="transform",
            service_name="etl-service",
            handler_name="transform_data",
            dependencies=["extract"]
        ),
        task_step(
            name="load",
            service_name="etl-service",
            handler_name="load_data",
            dependencies=["transform"]
        )
    ])
```

### Parallel Execution

Steps without dependencies execute in parallel:

```python
@workflow()
def parallel_processing() -> FlowDefinition:
    return FlowDefinition([
        # These three steps run in parallel
        task_step(
            name="process_a",
            service_name="service",
            handler_name="process_type_a"
        ),
        task_step(
            name="process_b",
            service_name="service",
            handler_name="process_type_b"
        ),
        task_step(
            name="process_c",
            service_name="service",
            handler_name="process_type_c"
        ),
        # This step waits for all three to complete
        task_step(
            name="merge_results",
            service_name="service",
            handler_name="merge_results",
            dependencies=["process_a", "process_b", "process_c"]
        )
    ])
```

## Step Types

### Task Steps

Execute function handlers on services:

```python
from agnt5.workflows import task_step

# Basic task step
step = task_step(
    name="unique_step_name",
    service_name="my-service",
    handler_name="my_handler"
)

# Task with dependencies and input data
step = task_step(
    name="dependent_step",
    service_name="my-service",
    handler_name="process_data",
    dependencies=["previous_step"],
    input_data={"config": "production", "batch_size": 100}
)

# Task with object keys (Phase 2)
step = task_step(
    name="object_step",
    service_name="object-service",
    handler_name="update_state",
    dependencies=["init_step"],
    object_keys=["user:123", "cart:456"]
)
```

### Wait Signal Steps

Pause execution until external signals:

```python
from agnt5.workflows import wait_signal_step

# Basic signal wait
step = wait_signal_step(
    name="wait_for_approval",
    signal_name="approval_granted",
    dependencies=["review_step"]
)

# Signal wait with timeout
step = wait_signal_step(
    name="wait_with_timeout",
    signal_name="user_action",
    dependencies=["prompt_user"],
    timeout_ms=300000,  # 5 minutes
    on_timeout="timeout_handler_step"
)
```

### Wait Timer Steps

Scheduled delays and cron-based execution:

```python
from agnt5.workflows import wait_timer_step

# Fixed delay
step = wait_timer_step(
    name="delay_before_retry",
    timer_key="retry_delay",
    delay_ms=30000,  # 30 seconds
    dependencies=["failed_step"]
)

# Cron schedule
step = wait_timer_step(
    name="nightly_batch",
    timer_key="nightly",
    cron_expr="0 2 * * *",  # 2 AM daily
    dependencies=["prep_step"]
)

# Timer with retries
step = wait_timer_step(
    name="retry_with_backoff",
    timer_key="exponential_backoff",
    delay_ms=5000,
    max_retries=3,
    dependencies=["error_step"]
)
```

## Workflow Examples

### ETL Pipeline

```python
@workflow()
def nightly_etl() -> FlowDefinition:
    return FlowDefinition([
        # Start with data validation
        task_step(
            name="validate_sources",
            service_name="etl-service",
            handler_name="validate_data_sources"
        ),

        # Extract from multiple sources in parallel
        task_step(
            name="extract_database",
            service_name="etl-service",
            handler_name="extract_from_database",
            dependencies=["validate_sources"]
        ),
        task_step(
            name="extract_api",
            service_name="etl-service",
            handler_name="extract_from_api",
            dependencies=["validate_sources"]
        ),
        task_step(
            name="extract_files",
            service_name="etl-service",
            handler_name="extract_from_files",
            dependencies=["validate_sources"]
        ),

        # Wait for all extractions to complete
        task_step(
            name="merge_extracted_data",
            service_name="etl-service",
            handler_name="merge_data",
            dependencies=["extract_database", "extract_api", "extract_files"]
        ),

        # Transform data
        task_step(
            name="clean_data",
            service_name="etl-service",
            handler_name="clean_and_normalize",
            dependencies=["merge_extracted_data"]
        ),
        task_step(
            name="enrich_data",
            service_name="etl-service",
            handler_name="enrich_with_metadata",
            dependencies=["clean_data"]
        ),

        # Wait for maintenance window
        wait_timer_step(
            name="wait_for_maintenance_window",
            timer_key="maintenance",
            cron_expr="0 3 * * *",  # 3 AM
            dependencies=["enrich_data"]
        ),

        # Load data
        task_step(
            name="load_to_warehouse",
            service_name="etl-service",
            handler_name="load_data_warehouse",
            dependencies=["wait_for_maintenance_window"]
        ),

        # Generate reports
        task_step(
            name="generate_reports",
            service_name="reporting-service",
            handler_name="generate_daily_reports",
            dependencies=["load_to_warehouse"]
        )
    ])
```

### Approval Workflow

```python
@workflow()
def document_approval() -> FlowDefinition:
    return FlowDefinition([
        # Submit document for review
        task_step(
            name="submit_document",
            service_name="doc-service",
            handler_name="submit_for_review",
            input_data={"priority": "normal"}
        ),

        # Notify reviewers
        task_step(
            name="notify_reviewers",
            service_name="notification-service",
            handler_name="send_review_notifications",
            dependencies=["submit_document"]
        ),

        # Wait for approval (with timeout)
        wait_signal_step(
            name="wait_for_approval",
            signal_name="document_approved",
            dependencies=["notify_reviewers"],
            timeout_ms=172800000,  # 48 hours
            on_timeout="escalate_approval"
        ),

        # Escalation path
        task_step(
            name="escalate_approval",
            service_name="doc-service",
            handler_name="escalate_to_manager",
            # No dependencies - triggered by timeout
        ),

        # Wait for escalated approval
        wait_signal_step(
            name="wait_escalated_approval",
            signal_name="escalated_approval",
            dependencies=["escalate_approval"],
            timeout_ms=86400000  # 24 hours
        ),

        # Publish approved document
        task_step(
            name="publish_document",
            service_name="doc-service",
            handler_name="publish_approved_document",
            dependencies=["wait_for_approval", "wait_escalated_approval"]
        )
    ])
```

## Workflow Registration

### Using the Decorator

```python
from agnt5 import workflow
from agnt5.workflows import get_registered_workflows

@workflow()
def my_workflow() -> FlowDefinition:
    return FlowDefinition([...])

@workflow("custom_name")
def workflow_with_custom_name() -> FlowDefinition:
    return FlowDefinition([...])

# Inspect registered workflows
workflows = get_registered_workflows()
print(f"Registered workflows: {list(workflows.keys())}")
```

### Manual Registration

```python
from agnt5.workflows import register_workflow

def create_workflow_definition() -> FlowDefinition:
    return FlowDefinition([
        task_step("step1", service_name="service", handler_name="handler1"),
        task_step("step2", service_name="service", handler_name="handler2",
                 dependencies=["step1"])
    ])

# Manual registration
register_workflow("manual_workflow", create_workflow_definition())
```

## Workflow Data Classes

### FlowDefinition

Container for workflow steps with serialization:

```python
from agnt5.workflows import FlowDefinition

# Create definition
flow = FlowDefinition([
    task_step("step1", service_name="svc", handler_name="h1"),
    task_step("step2", service_name="svc", handler_name="h2", dependencies=["step1"])
])

# Serialize to dictionary
flow_dict = flow.to_dict()

# Serialize to JSON string
flow_json = flow.to_json()
```

### WorkflowStep

Individual step configuration:

```python
from agnt5.workflows import WorkflowStep, StepType

# Manual step creation (usually use helper functions instead)
step = WorkflowStep(
    name="custom_step",
    step_type=StepType.TASK,
    service_name="my-service",
    handler_name="my_handler",
    dependencies=["previous_step"],
    input_data={"key": "value"}
)
```

### Configuration Classes

```python
from agnt5.workflows import SignalConfig, TimerConfig

# Signal configuration
signal_config = SignalConfig(
    name="approval_signal",
    timeout_ms=3600000,  # 1 hour
    on_timeout="timeout_step"
)

# Timer configuration
timer_config = TimerConfig(
    key="batch_timer",
    delay_ms=60000,  # 1 minute
    max_retries=5
)

# Cron timer configuration
cron_timer = TimerConfig(
    key="daily_job",
    cron_expr="0 0 * * *",  # Daily at midnight
    max_retries=3
)
```

## Validation and Error Handling

### Workflow Validation

AGNT5 validates workflows during registration:

```python
from agnt5.workflows import register_workflow, FlowDefinition, task_step

# This will raise ValueError: Missing dependencies
try:
    invalid_flow = FlowDefinition([
        task_step("step2", service_name="svc", handler_name="h2",
                 dependencies=["step1"]),  # step1 doesn't exist
        task_step("step3", service_name="svc", handler_name="h3",
                 dependencies=["step2"])
    ])
    register_workflow("invalid", invalid_flow)
except ValueError as e:
    print(f"Validation error: {e}")
```

### Validation Rules

- At least one step must be defined
- Step names must be unique within the workflow
- Dependencies must reference existing steps
- Dependencies must appear earlier in the definition (causal order)
- Required fields must be populated based on step type

## Testing Workflows

### Workflow Definition Testing

```python
import pytest
from agnt5.workflows import FlowDefinition, task_step, get_registered_workflows

def test_workflow_definition():
    # Test workflow structure
    flow = FlowDefinition([
        task_step("extract", service_name="etl", handler_name="extract"),
        task_step("transform", service_name="etl", handler_name="transform",
                 dependencies=["extract"])
    ])

    # Verify serialization
    flow_dict = flow.to_dict()
    assert len(flow_dict["steps"]) == 2
    assert flow_dict["steps"][1]["dependencies"] == ["extract"]

def test_workflow_registration():
    @workflow()
    def test_workflow() -> FlowDefinition:
        return FlowDefinition([
            task_step("test_step", service_name="test", handler_name="test")
        ])

    # Verify registration
    workflows = get_registered_workflows()
    assert "test_workflow" in workflows
```

### Integration Testing

Test workflows with a local development environment:

```python
import asyncio
from agnt5 import Client

async def test_workflow_execution():
    client = Client("http://localhost:8080")

    # Trigger workflow
    result = await client.start_workflow(
        workflow_name="data_pipeline",
        input_data={"source": "test_data"}
    )

    workflow_id = result["workflow_id"]

    # Poll for completion
    while True:
        status = await client.get_workflow_status(workflow_id)
        if status["state"] in ["completed", "failed"]:
            break
        await asyncio.sleep(1)

    assert status["state"] == "completed"
```

## Best Practices

### Design Patterns

1. **Idempotent Steps** - Design steps to be safely retryable
2. **Small Steps** - Break complex operations into smaller, focused steps
3. **Clear Dependencies** - Make step relationships explicit
4. **Meaningful Names** - Use descriptive names for steps and workflows
5. **Error Handling** - Plan for failure and recovery scenarios

### Performance

1. **Parallel Execution** - Remove unnecessary dependencies to enable parallelism
2. **Batch Operations** - Group related operations into single steps
3. **Resource Management** - Consider resource usage when designing workflows
4. **State Minimization** - Keep workflow state as small as possible

### Monitoring

1. **Structured Logging** - Add logging to workflow steps
2. **Progress Tracking** - Use meaningful step names and descriptions
3. **Metrics Collection** - Track workflow success rates and durations
4. **Error Alerting** - Set up alerts for workflow failures

## Next Steps

- [Worker Runtime](worker) - Configure and deploy workers
- [API Reference](api/workflows) - Complete workflows API reference
- [Examples](examples/workflow-example) - Real-world workflow patterns


# CLI Reference

---

## Authentication Commands

_Source: https://agnt5.com/cli_

> Authentication and identity management for AGNT5 CLI

Authentication is required before you can create projects, deploy, or interact with the Control Plane. Credentials are stored in `~/.agnt5/config.yaml` and read on every invocation.


**Commands**: `agnt5 auth login [--api-key <value>]`, `agnt5 auth logout`, `agnt5 auth whoami`
**Credential store**: `~/.agnt5/config.yaml` (persisted on login, read on every invocation)
**Env overrides**: `AGNT5_API_KEY` bypasses the login command; `AGNT5_API_URL` overrides the Control Plane URL
**Auth flow**: browser-based OAuth via PropelAuth; CLI polls the Control Plane until an API key is issued


### `agnt5 auth login`

<CommandLayout command="auth login">
  <div slot="documentation">
    Launches the authentication flow. By default the CLI requests a short-lived session ID from the Control Plane, opens your browser to the PropelAuth login screen, and polls until an API key is issued. The generated key is persisted to `~/.agnt5/config.yaml` so subsequent commands can reuse it.

    ### Syntax
    ```bash
    agnt5 auth login [options]
    ```

    ### Options

    | Flag | Description |
    | --- | --- |
    | `--api-key <value>` | Skip the browser flow and provide an existing API key. The CLI validates the key by fetching the current user before saving it locally. |

    <Callout type="info">
    The CLI respects `AGNT5_API_URL` and other context settings when constructing the OAuth URLs, so ensure your context is correct before logging in. You can also provide `AGNT5_API_KEY` in the environment to bypass the login command entirely.
    </Callout>
  </div>

  <div slot="examples">
    
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 auth login
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Starting authentication flow...
          ✓ Session ID requested from Control Plane

          Opening browser for authentication...
          → https://auth.agnt5.com/propelauth/login

          Waiting for authentication to complete...
          ✓ Authentication successful
          ✓ API key saved to ~/.agnt5/config.yaml

          You are now authenticated as: user@example.com
          ```
        </ExampleBlock>
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 auth login --api-key agnt5_sk_abc123...
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Validating provided API key...
          ✓ API key is valid
          ✓ User verified: user@example.com
          ✓ API key saved to ~/.agnt5/config.yaml

          Authentication complete.
          ```
        </ExampleBlock>
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 auth login
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          ✓ Already authenticated as: user@example.com
          ✓ API key is valid and active

          Current context: production
          API URL: https://api.agnt5.com

          No action needed.
          ```
        </ExampleBlock>
      
    
  </div>
</CommandLayout>

### `agnt5 auth logout`

<CommandLayout command="auth logout">
  <div slot="documentation">
    Clears any stored API keys and tokens from `~/.agnt5/config.yaml`. You can re-authenticate later with `agnt5 auth login`.

    ### Syntax
    ```bash
    agnt5 auth logout
    ```
  </div>

  <div slot="examples">
    
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 auth logout
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          ✓ API key cleared from ~/.agnt5/config.yaml
          ✓ Authentication tokens removed

          You have been logged out successfully.
          Use 'agnt5 auth login' to authenticate again.
          ```
        </ExampleBlock>
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 auth logout
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          No authentication credentials found.
          Already logged out.
          ```
        </ExampleBlock>
      
    
  </div>
</CommandLayout>

### `agnt5 auth status`

<CommandLayout command="auth status">
  <div slot="documentation">
    Displays whether you are authenticated, printing the email associated with the stored key along with the active environment and API base URL. If the saved key is invalid the command reports the failure and suggests `agnt5 auth login`.

    ### Syntax
    ```bash
    agnt5 auth status
    ```
  </div>

  <div slot="examples">
    
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 auth status
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          ✓ Authenticated as: user@example.com
          ✓ API key is valid

          Environment: production
          API URL: https://api.agnt5.com
          Context: production

          Authentication status: Active
          ```
        </ExampleBlock>
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 auth status
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          ✗ Authentication failed
          ✗ Stored API key is invalid or expired

          Please run 'agnt5 auth login' to re-authenticate.
          ```
        </ExampleBlock>
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 auth status
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          ✗ Not authenticated

          No API key found in ~/.agnt5/config.yaml
          Run 'agnt5 auth login' to authenticate.
          ```
        </ExampleBlock>
      
    
  </div>
</CommandLayout>

### `agnt5 whoami`

<CommandLayout command="whoami">
  <div slot="documentation">
    Prints the email address tied to the stored credentials. This command is also available via `agnt5 auth whoami` and returns `Not authenticated` when no valid key is present.

    ### Syntax
    ```bash
    agnt5 whoami
    ```
  </div>

  <div slot="examples">
    
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 whoami
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          user@example.com
          ```
        </ExampleBlock>
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 whoami
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Not authenticated
          ```
        </ExampleBlock>
      
    
  </div>
</CommandLayout>

### `agnt5 version`

<CommandLayout command="version">
  <div slot="documentation">
    Display CLI build metadata including version string, Go runtime, and platform. Use this command to inspect the CLI build information.

    ### Syntax
    ```bash
    agnt5 version
    ```

    <Callout type="info">
    Use `agnt5 version` paired with `agnt5 whoami` to confirm both your binary and credentials before deploying.
    </Callout>
  </div>

  <div slot="examples">
    
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 version
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          AGNT5 CLI v1.2.3

          Build Information:
            Version: 1.2.3
            Go version: go1.21.0
            Platform: darwin/amd64
            Build date: 2024-01-15 10:30:45
            Git commit: abc1234
          ```
        </ExampleBlock>
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 version && agnt5 whoami
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          AGNT5 CLI v1.2.3

          Build Information:
            Version: 1.2.3
            Go version: go1.21.0
            Platform: darwin/amd64
            Build date: 2024-01-15 10:30:45
            Git commit: abc1234

          user@example.com
          ```
        </ExampleBlock>
      
    
  </div>
</CommandLayout>

---

## Commands Reference

_Source: https://agnt5.com/cli_

> Complete reference for all AGNT5 CLI commands and their options

**Top-level commands**: `agnt5 init`, `agnt5 run`, `agnt5 deploy`, `agnt5 logs`, `agnt5 config`, `agnt5 auth`, `agnt5 project`, `agnt5 context`, `agnt5 list`
**Invocation shape**: `agnt5 <command> [args] [options]`
**Help**: `agnt5 --help` for top-level; `agnt5 <command> --help` per subcommand


### `agnt5 init`

Set up the **current directory** as an AGNT5 project: scaffold a starter project and link it to AGNT5. Aliased as `agnt5 link`.

```bash
agnt5 init [name] [options]
```

Provide a name to scaffold a new project in the current directory (`agnt5 init my-agent`). With no name, init inspects the directory — scaffolding an empty one, adding config to existing code, or relinking an existing project.

**Options:**
- `--template <name>` - Scaffold from a template (e.g. `python/weather-agent`, optionally `@version`)
- `--version <version>` - Template version (defaults to latest)
- `--language <lang>` - Language for scaffolding or a new project (defaults to `agnt5.yaml` or `python`)
- `--project <id>` - Link to an existing project by ID or ref instead of scaffolding
- `--new` - Create a new empty project on AGNT5 and link to it
- `--name <name>` - Project name (alternative to the positional argument; used with `--new`)
- `--workspace <id|name>` - Workspace to link within (skips the workspace prompt)
- `-v, --verbose` - Show verbose output

**Examples:**
```bash
agnt5 init my-agent                          # Scaffold + link the current directory
agnt5 init                                   # Set up + link the current directory
agnt5 init --project <project-id>            # Link to an existing project by ID
agnt5 init --new --name my-proj              # Create a new project and link to it
agnt5 init my-agent --template python/weather-agent
```

### `agnt5 create`

Create a new AGNT5 project in a **new directory** and register it on AGNT5 — a convenience wrapper around `agnt5 init`.

```bash
agnt5 create [name] [options]
```

**Options:**
- `--template <name>` - Template to scaffold from (e.g. `python/weather-agent`, optionally `@version`)
- `--version <version>` - Template version (defaults to latest)
- `--local` - Create the project locally without registering it on AGNT5
- `-v, --verbose` - Show verbose output

**Examples:**
```bash
agnt5 create my-agent
agnt5 create my-agent --template python/weather-agent
```

### `agnt5 run`

Execute workflows locally or remotely with comprehensive logging and error handling.

```bash
agnt5 run <workflow> [options]
```

**Options:**
- `--input <file>` - Input data file (JSON)
- `--env <environment>` - Target environment (local, dev, staging, prod)
- `--remote` - Execute on remote AGNT5 runtime
- `--watch` - Watch for file changes and re-run
- `--debug` - Enable debug output

**Examples:**
```bash
agnt5 run my-workflow
agnt5 run data-processor --input data.json
agnt5 run my-workflow --remote --env staging
agnt5 run my-workflow --watch --debug
```

## Deployment Commands

### `agnt5 deploy`

Deploy your workflows to production with zero-downtime deployments and automatic scaling.

```bash
agnt5 deploy [options]
```

**Options:**
- `--env <environment>` - Target environment (staging, production)
- `--watch` - Watch deployment status
- `--no-build` - Skip build step
- `--force` - Force deployment even with warnings
- `--rollback` - Rollback to previous deployment

**Examples:**
```bash
agnt5 deploy
agnt5 deploy --env staging
agnt5 deploy --watch --env production
agnt5 deploy --rollback
```

### `agnt5 build`

Build your project for deployment.

```bash
agnt5 build [options]
```

**Options:**
- `--env <environment>` - Build for specific environment
- `--output <directory>` - Output directory (default: dist)
- `--minify` - Minify output files
- `--sourcemap` - Generate source maps

**Examples:**
```bash
agnt5 build
agnt5 build --env production --minify
agnt5 build --output ./build --sourcemap
```

## Monitoring Commands

### `agnt5 logs`

Stream real-time logs from your workflows with filtering, search, and export capabilities.

```bash
agnt5 logs [options]
```

**Options:**
- `--follow, -f` - Follow log output in real-time
- `--filter <level>` - Filter by log level (error, warn, info, debug)
- `--grep <pattern>` - Filter logs by pattern
- `--tail <number>` - Show last N lines (default: 100)
- `--env <environment>` - Target environment
- `--export <file>` - Export logs to file

**Examples:**
```bash
agnt5 logs
agnt5 logs --follow --filter error
agnt5 logs --grep "workflow-123" --tail 50
agnt5 logs --env production --export logs.json
```

### `agnt5 status`

Check the status of your workflows, deployments, and system health across environments.

```bash
agnt5 status [options]
```

**Options:**
- `--env <environment>` - Target environment
- `--watch, -w` - Watch status in real-time
- `--json` - Output in JSON format
- `--verbose` - Show detailed status information

**Examples:**
```bash
agnt5 status
agnt5 status --env production --watch
agnt5 status --json --verbose
```

## Configuration Commands

### `agnt5 config`

Manage CLI configuration and settings.

```bash
agnt5 config <command> [options]
```

**Subcommands:**
- `get <key>` - Get configuration value
- `set <key> <value>` - Set configuration value
- `list` - List all configuration values
- `reset` - Reset configuration to defaults

**Options:**
- `--global` - Modify global configuration
- `--env <environment>` - Environment-specific config

**Examples:**
```bash
agnt5 config get api-key
agnt5 config set api-key your-api-key
agnt5 config set timeout 30000 --env production
agnt5 config list --global
agnt5 config reset
```

### `agnt5 auth`

Manage authentication with AGNT5 services.

```bash
agnt5 auth <command>
```

**Subcommands:**
- `login` - Authenticate with AGNT5
- `logout` - Remove authentication
- `whoami` - Show current user
- `token` - Manage API tokens

**Examples:**
```bash
agnt5 auth login
agnt5 auth whoami
agnt5 auth logout
```

## Environment Commands

### `agnt5 env`

Manage deployment environments and their configuration.

```bash
agnt5 env <command> [options]
```

**Subcommands:**
- `list` - List all environments
- `create <name>` - Create new environment
- `delete <name>` - Delete environment
- `set <key> <value>` - Set environment variable
- `unset <key>` - Remove environment variable

**Examples:**
```bash
agnt5 env list
agnt5 env create staging
agnt5 env set DATABASE_URL postgres://... --env staging
agnt5 env unset DEBUG --env production
agnt5 env delete old-staging
```

## Utility Commands

### `agnt5 validate`

Validate project configuration and workflow definitions.

```bash
agnt5 validate [file] [options]
```

**Options:**
- `--schema` - Validate against specific schema
- `--fix` - Attempt to fix validation errors
- `--strict` - Use strict validation rules

**Examples:**
```bash
agnt5 validate
agnt5 validate workflow.yaml
agnt5 validate --strict --fix
```

### `agnt5 doctor`

Diagnose common issues with your AGNT5 setup.

```bash
agnt5 doctor [options]
```

**Options:**
- `--verbose` - Show detailed diagnostic information
- `--fix` - Attempt to fix detected issues

**Examples:**
```bash
agnt5 doctor
agnt5 doctor --verbose --fix
```

## Global Options

These options are available for all commands:

- `--help, -h` - Show help information
- `--version, -v` - Show CLI version
- `--verbose` - Enable verbose output
- `--quiet, -q` - Suppress non-error output
- `--config <file>` - Use specific config file

---

## Configuration

_Source: https://agnt5.com/cli_

> Configure the AGNT5 CLI for your development environment and deployment targets

Configure the AGNT5 CLI for your development environment, API authentication, and deployment targets.


**Config file locations**: project root (`agnt5.config.js`, `agnt5.config.json`, or `agnt5.yaml`); user home (`~/.agnt5/config.yaml` for credentials, `~/.agnt5/context.yaml` for environment)
**Config formats**: JavaScript (`agnt5.config.js`) or JSON (`agnt5.config.json`); manifests use YAML (`agnt5.yaml`)
**Precedence**: CLI flags > env vars (`AGNT5_*`) > project config > user config > built-in defaults


## Project Configuration

The CLI uses a configuration file in your project root. The CLI supports both JavaScript and JSON formats:

### `agnt5.config.js`

```javascript
module.exports = {
  // Project settings
  name: 'my-project',
  version: '1.0.0',
  description: 'My AI workflow project',

  // Development server
  dev: {
    port: 3000,
    host: 'localhost',
    watch: ['src/**/*', 'workflows/**/*'],
    reload: true,
    open: true
  },

  // Build settings
  build: {
    outDir: 'dist',
    minify: true,
    sourcemap: false,
    target: 'node16'
  },

  // Deployment settings
  deploy: {
    environment: 'production',
    region: 'us-east-1',
    timeout: 300000,
    retries: 3
  },

  // Workflow configuration
  workflows: {
    timeout: 60000,
    retries: 2,
    concurrency: 10
  }
};
```

### `agnt5.config.json`

```json
{
  "name": "my-project",
  "version": "1.0.0",
  "dev": {
    "port": 3000,
    "host": "localhost",
    "watch": ["src/**/*"]
  },
  "deploy": {
    "environment": "production",
    "region": "us-east-1"
  }
}
```

## Environment Variables

Configure the CLI using environment variables. These can be set in your shell or in a `.env` file:

### Authentication
```bash
# API authentication
AGNT5_API_KEY=your-api-key
AGNT5_BASE_URL=https://api.agnt5.com

# Alternative: use auth token
AGNT5_AUTH_TOKEN=your-jwt-token
```

### Runtime Configuration
```bash
# Default environment
AGNT5_ENVIRONMENT=development

# Logging
AGNT5_LOG_LEVEL=info  # error, warn, info, debug
AGNT5_LOG_FORMAT=pretty  # pretty, json

# Timeouts (in milliseconds)
AGNT5_TIMEOUT=30000
AGNT5_CONNECT_TIMEOUT=5000

# Development settings
AGNT5_DEV_PORT=3000
AGNT5_DEV_HOST=localhost
AGNT5_HOT_RELOAD=true
```

### Deployment Configuration
```bash
# Default deployment environment
AGNT5_DEPLOY_ENV=production

# Runtime settings
AGNT5_RUNTIME_REGION=us-east-1
AGNT5_RUNTIME_MEMORY=512
AGNT5_RUNTIME_TIMEOUT=300
```

## Global CLI Configuration

Manage global CLI settings that persist across all projects:

### View Current Configuration
```bash
agnt5 config list --global
```

### Set Global Configuration
```bash
# API settings
agnt5 config set api-key your-api-key --global
agnt5 config set base-url https://api.agnt5.com --global

# Default preferences
agnt5 config set log-level info --global
agnt5 config set editor vscode --global
agnt5 config set auto-update true --global
```

### Configuration File Location

Global configuration is stored in:
- **macOS/Linux**: `~/.config/agnt5/config.json`
- **Windows**: `%APPDATA%\agnt5\config.json`

## Environment-Specific Configuration

Configure different settings for different environments:

### Development Environment
```bash
agnt5 config set timeout 10000 --env development
agnt5 config set log-level debug --env development
agnt5 config set hot-reload true --env development
```

### Staging Environment
```bash
agnt5 config set base-url https://staging-api.agnt5.com --env staging
agnt5 config set timeout 30000 --env staging
agnt5 config set log-level info --env staging
```

### Production Environment
```bash
agnt5 config set base-url https://api.agnt5.com --env production
agnt5 config set timeout 60000 --env production
agnt5 config set log-level warn --env production
```

## API Keys and Authentication

### Setting Up API Keys

1. **Get your API key** from the AGNT5 dashboard
2. **Set it globally** for all projects:
   ```bash
   agnt5 config set api-key your-api-key --global
   ```
3. **Or set per environment:**
   ```bash
   agnt5 config set api-key your-dev-key --env development
   agnt5 config set api-key your-prod-key --env production
   ```

### Using Environment Files

Create `.env` files for each environment:

#### `.env.development`
```bash
AGNT5_API_KEY=dev_api_key_here
AGNT5_BASE_URL=https://dev-api.agnt5.com
AGNT5_LOG_LEVEL=debug
```

#### `.env.production`
```bash
AGNT5_API_KEY=prod_api_key_here
AGNT5_BASE_URL=https://api.agnt5.com
AGNT5_LOG_LEVEL=warn
```

### Authentication Methods

The CLI supports multiple authentication methods in order of precedence:

1. **Command-line flags**: `--api-key your-key`
2. **Environment variables**: `AGNT5_API_KEY`
3. **Project config file**: `agnt5.config.js`
4. **Global config**: `~/.config/agnt5/config.json`
5. **Interactive login**: `agnt5 auth login`

## Configuration Validation

Validate your configuration to ensure everything is set up correctly:

```bash
# Validate current configuration
agnt5 config validate

# Validate specific environment
agnt5 config validate --env production

# Show configuration sources
agnt5 config validate --verbose
```

## Configuration Schema

The complete configuration schema:

```typescript
interface AgntConfig {
  // Project metadata
  name?: string;
  version?: string;
  description?: string;

  // API configuration
  apiKey?: string;
  baseUrl?: string;
  timeout?: number;

  // Development server
  dev?: {
    port?: number;
    host?: string;
    watch?: string[];
    reload?: boolean;
    open?: boolean;
  };

  // Build configuration
  build?: {
    outDir?: string;
    minify?: boolean;
    sourcemap?: boolean;
    target?: string;
  };

  // Deployment settings
  deploy?: {
    environment?: string;
    region?: string;
    timeout?: number;
    retries?: number;
  };

  // Workflow settings
  workflows?: {
    timeout?: number;
    retries?: number;
    concurrency?: number;
  };

  // Logging configuration
  logging?: {
    level?: 'error' | 'warn' | 'info' | 'debug';
    format?: 'pretty' | 'json';
  };
}
```

## Best Practices

### Security
- **Never commit API keys** to version control
- **Use environment-specific keys** for different deployment targets
- **Rotate keys regularly** and update configuration
- **Use `.env` files** for local development

### Organization
- **Use project config files** for team-shared settings
- **Use global config** for personal preferences
- **Document environment variables** in your project README
- **Validate configuration** in CI/CD pipelines

### Performance
- **Set appropriate timeouts** for your use case
- **Configure concurrency limits** based on your resources
- **Use region-specific endpoints** for better latency
- **Enable caching** where appropriate

---

## Context Switching Commands (Advanced)

_Source: https://agnt5.com/cli_

> Switch between local development endpoints and hosted environments

Advanced users can switch between local development endpoints and hosted environments with the `agnt5 context` command group. Contexts influence which Control Plane and Gateway URLs the CLI uses, and they can also seed environment-specific configuration files.


**Commands**: `agnt5 context` (show current), `agnt5 context use <name>`, `agnt5 context list`
**Context store**: `~/.agnt5/context.yaml`
**Default context**: `production` (API URL `https://api.agnt5.com`)
**Hidden from `--help`**: yes, but invokable directly


<Callout type="info">
Although the commands are marked hidden in `--help`, you can still run them directly. These are advanced commands primarily used for development and testing against different AGNT5 environments.
</Callout>

### `agnt5 context`

<CommandLayout command="context">
  <div slot="documentation">
    Prints the currently active context (defaults to `production` when none is stored) along with the API base URL pulled from `~/.agnt5/context.yaml`.

    ### Syntax
    ```bash
    agnt5 context
    ```
  </div>

  <div slot="examples">
    <ExampleBlock title="Command" variant="command">
      ```bash
      # Show current context
      agnt5 context
      ```
    </ExampleBlock>

    <ExampleBlock title="Response" variant="response">
      ```
      Current context: production
      API URL: https://api.agnt5.com
      ```
    </ExampleBlock>
  </div>
</CommandLayout>

### `agnt5 context list`

<CommandLayout command="context list">
  <div slot="documentation">
    Lists the built-in contexts (`local`, `staging`, `production`) and marks the active one with `*`.

    ### Syntax
    ```bash
    agnt5 context list
    ```
  </div>

  <div slot="examples">
    <ExampleBlock title="Command" variant="command">
      ```bash
      # List all available contexts
      agnt5 context list
      ```
    </ExampleBlock>

    <ExampleBlock title="Response" variant="response">
      ```
      Available contexts:

        local       http://localhost:34181
        staging     https://api.agnt5.xyz
      * production  https://api.agnt5.com
      ```
    </ExampleBlock>
  </div>
</CommandLayout>

### `agnt5 context set`

<CommandLayout command="context set">
  <div slot="documentation">
    Writes the chosen context to `~/.agnt5/context.yaml`, updates related settings, and copies `~/.agnt5/config.<context>.yaml` into `config.yaml` when present. The command also prints the final API and gateway URLs so you can confirm the change.

    ### Syntax
    ```bash
    agnt5 context set <context>
    ```

    ### Available Contexts

    | Context | API URL | Gateway URL | Notes |
    | --- | --- | --- | --- |
    | `local` | `http://localhost:34181` | `http://localhost:34183` | Dev stack with local OAuth |
    | `staging` | `https://api.agnt5.xyz` | `https://gw.agnt5.xyz` | Pre-production testing |
    | `production` | `https://api.agnt5.com` | `https://gw.agnt5.com` | Live environment (default) |
  </div>

  <div slot="examples">
    
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Switch to local development
          agnt5 context set local
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          ✓ Context switched to: local
          ✓ Configuration copied from config.local.yaml

          Active endpoints:
            API URL: http://localhost:34181
            Gateway: http://localhost:34183
            gRPC Gateway: localhost:34184
            Auth URL: https://86934364.propelauthtest.com

          You are now targeting the local development stack.
          ```
        </ExampleBlock>
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Switch to staging environment
          agnt5 context set staging
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          ✓ Context switched to: staging
          ✓ Configuration copied from config.staging.yaml

          Active endpoints:
            API URL: https://api.agnt5.xyz
            Gateway: https://gw.agnt5.xyz
            Auth URL: https://auth.agnt5.xyz/propelauth

          You are now targeting the staging environment.
          ```
        </ExampleBlock>
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Switch back to production
          agnt5 context set production
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          ✓ Context switched to: production
          ✓ Configuration copied from config.production.yaml

          Active endpoints:
            API URL: https://api.agnt5.com
            Gateway: https://gw.agnt5.com
            Auth URL: https://auth.agnt5.com/propelauth

          You are now targeting the production environment.
          ```
        </ExampleBlock>
      
    
  </div>
</CommandLayout>

## Context Configuration

Every context also updates `agnt5_env` to a descriptive value (`agnt5-local`, `agnt5-staging`, `agnt5-production`). Commands like `agnt5 auth login` and `agnt5 deploy` pick up these values the next time they run, ensuring you are talking to the correct control plane.

### Environment-Specific Configuration

<Callout type="tip">
Keep environment-specific credentials in `~/.agnt5/config.local.yaml`, `config.staging.yaml`, etc. Switching contexts copies the relevant file over `config.yaml`, so your API keys stay in sync with the environment you just selected.
</Callout>

### Configuration Files by Context

| File | Purpose |
| --- | --- |
| `~/.agnt5/context.yaml` | Stores the currently active context |
| `~/.agnt5/config.yaml` | Main configuration file, updated when contexts switch |
| `~/.agnt5/config.local.yaml` | Local environment-specific settings |
| `~/.agnt5/config.staging.yaml` | Staging environment-specific settings |
| `~/.agnt5/config.production.yaml` | Production environment-specific settings |

### Context Workflow

```bash
# 1. Check current context
agnt5 context

# 2. List available contexts
agnt5 context list

# 3. Switch to local development
agnt5 context set local

# 4. Authenticate against local environment
agnt5 auth login

# 5. Work with local stack
agnt5 project list

# 6. Switch back to production
agnt5 context set production
```

## Use Cases

### Local Development
Switch to `local` context when working with the development stack:

```bash
agnt5 context set local
agnt5 auth login
```

### Staging Testing
Use `staging` context for pre-production testing:

```bash
agnt5 context set staging
agnt5 auth login
agnt5 deploy --staging
```

### Production Operations
Default `production` context for live deployments:

```bash
agnt5 context set production
agnt5 auth login
agnt5 deploy --prod
```

<Callout type="warning">
**Important:** Always verify your context before performing sensitive operations like production deployments. Use `agnt5 context` to confirm you're targeting the correct environment.
</Callout>

---

## Deployment Commands

_Source: https://agnt5.com/cli_

> Build, push, and deploy AGNT5 projects with comprehensive deployment pipeline

`agnt5 deploy` is the all-in-one command that builds your project, pushes the resulting image to the configured registry, validates the target workspace, and creates (or updates) a deployment. It intentionally mirrors the Vercel CLI's single entry point: run `agnt5 deploy` from the project root and the CLI orchestrates the rest.


**Command**: `agnt5 deploy [options]`
**Required**: authenticated session (`agnt5 auth login`); project binding (`.agnt5/project-ref`); deployment manifest (`agnt5.yaml`); running Docker daemon
**Key flags**: `--environment`, `--prod`, `--staging`, `--dry-run`, `--build-only`, `--platform`, `--replicas`, `--cpu`, `--memory`, `--push-remote`
**Side effects**: builds Docker image; pushes to local registry (and remote if `--push-remote`); creates/updates Control Plane deployment
**Stages**: dry-run plan (optional) → build → push → deploy


## Prerequisites

- You must be authenticated (`agnt5 auth login`) so the CLI can talk to the Control Plane and container registries
- The working directory needs a project binding via `.agnt5/project-ref` and a deployment manifest (`agnt5.yaml`). `agnt5 project create` scaffolds both for Python projects
- Docker must be installed and running; the CLI performs connectivity checks and will error out with guidance if Docker or the registry cannot be reached

### `agnt5 deploy`

<CommandLayout command="deploy">
  <div slot="documentation">
    The complete deployment workflow with build, push, and deployment orchestration.

    ### Syntax
    ```bash
    agnt5 deploy [options]
    ```

    ### Command Workflow

    1. **Dry run (optional)** – With `--dry-run` the CLI prints a deployment plan and exits without building or deploying
    2. **Build** – Creates a Docker context, optionally generates a Dockerfile for Python projects, and uses the local Docker daemon to build the image
    3. **Push** – Tags are pushed to the local registry by default, and optionally mirrored to a remote registry when `--push-remote` is set
    4. **Deploy** – The Control Plane client validates or creates the workspace, resumes it if paused, and issues a deployment request

    ### Options

    **Common Options**
    | Flag | Description |
    | --- | --- |
    | `--project-dir` | Use a different directory as the build context (default: `.`) |
    | `--environment` | Name of the deployment environment (default: `development`) |
    | `--prod` | Shorthand flag that forces `environment` to `production` |
    | `--staging` | Shorthand flag that forces `environment` to `staging` |
    | `--dry-run` | Show the plan without building or deploying |
    | `--build-only` | Stop after a successful build/push so you can deploy later |

    **Build Options**
    | Flag | Description |
    | --- | --- |
    | `--dockerfile` | Path to the Dockerfile (defaults to `./Dockerfile`) |
    | `--no-cache` | Disable Docker layer caching |
    | `--clean-cache` | Prune Docker build cache before building |
    | `--pull` | Always attempt to pull newer base images |
    | `--platform` | Target platforms for multi-arch builds |
    | `--build-args` | Additional build arguments |
    | `--target` | Build a specific stage from multi-stage Dockerfile |
    | `--tags` | Append extra image tags |

    **Registry Options**
    | Flag | Description |
    | --- | --- |
    | `--push` | Push to local registry (default: `true`) |
    | `--push-remote` | Mirror to remote registry |

    **Deployment Options**
    | Flag | Description |
    | --- | --- |
    | `--replicas` | Number of replicas (default: `1`) |
    | `--cpu` | CPU limit |
    | `--memory` | Memory limit |
  </div>

  <div slot="examples">
    
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Deploy to development environment
          agnt5 deploy
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Starting deployment...
          ✓ Docker connectivity check passed
          ✓ Project reference found: acme/my-project
          ✓ Building image: localhost:5001/acme/my-project:latest

          Building Docker image...
          [+] Building 45.2s (12/12) FINISHED
          ✓ Image built successfully

          ✓ Pushing to local registry
          ✓ Validating workspace (development)
          ✓ Deploying to workspace

          Deployment successful!

          Next steps:
            curl http://localhost:8090/call -d '{"serviceName":"my-project"}'
            agnt5 logs
          ```
        </ExampleBlock>

        <ExampleBlock title="Command" variant="command">
          ```bash
          # Deploy to staging
          agnt5 deploy --staging
          ```
        </ExampleBlock>
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Clean build without cache
          agnt5 deploy --clean-cache
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Starting deployment with clean cache...
          ✓ Pruning Docker build cache
          ✓ Pulling fresh base images

          Building Docker image...
          [+] Building 120.5s (12/12) FINISHED
          ✓ Clean build completed
          ```
        </ExampleBlock>

        <ExampleBlock title="Command" variant="command">
          ```bash
          # Multi-platform build
          agnt5 deploy --platform linux/amd64,linux/arm64
          ```
        </ExampleBlock>

        <ExampleBlock title="Command" variant="command">
          ```bash
          # Build only (no deployment)
          agnt5 deploy --build-only
          ```
        </ExampleBlock>
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Full production deployment
          agnt5 deploy --prod --replicas 3 --cpu 1 --memory 1Gi --tags v1.2.0
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Starting production deployment...
          ✓ Environment: production
          ✓ Replicas: 3
          ✓ Resources: 1 CPU, 1Gi memory
          ✓ Additional tags: v1.2.0

          Building Docker image...
          [+] Building 52.1s (12/12) FINISHED
          ✓ Image tagged: v1.2.0

          ✓ Pushing to local registry
          ✓ Mirroring to remote registry
          ✓ Validating production workspace
          ✓ Deploying with 3 replicas

          Production deployment successful!

          Deployment ID: dep-prod-abc123
          Status: running (3/3 replicas ready)
          ```
        </ExampleBlock>
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          # See deployment plan
          agnt5 deploy --dry-run
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Deployment Plan (DRY RUN):

          Project: acme/my-project
          Environment: development
          Image: localhost:5001/acme/my-project:latest
          Replicas: 1
          Resources: default

          Build Steps:
          1. Validate Docker connectivity
          2. Build image from ./Dockerfile
          3. Push to localhost:5001

          Deploy Steps:
          1. Validate/create development workspace
          2. Deploy with 1 replica
          3. Wait for ready status

          No changes will be made (dry run mode).
          ```
        </ExampleBlock>

        <ExampleBlock title="Command" variant="command">
          ```bash
          # Plan production deployment
          agnt5 deploy --prod --dry-run --replicas 3
          ```
        </ExampleBlock>
      
    
  </div>
</CommandLayout>

## Build Stage Details

The build stage performs several safeguards before issuing a Docker build:

- Validates Docker connectivity by pinging the daemon and pulling a tiny `hello-world` image to confirm registry access
- Ensures Docker is installed, the project directory exists, and a Dockerfile is available (generating one for Python projects when needed)
- Reads defaults from `config.yaml`/`agnt5.yaml` to name the image after your project reference and merges in any additional tags or build arguments you provided

<Callout type="info">
If you set `--clean-cache` or `--no-cache`, the CLI prunes the Docker build cache before starting the build and forces base image pulls. Progress updates stream directly to the terminal (including the current Docker build step).
</Callout>

## Registry Pushes

After a successful build, the CLI tags the image for the configured registry:

### Local Registry
- Local pushes go to `localhost:5001` by default (or whatever `deploy.registry.local_url` resolves to)
- Authentication uses your AGNT5 API key

### Remote Registry
- Remote pushes use `deploy.registry.remote_url` when defined; otherwise the CLI falls back to the default remote registry (`iarun-agnt5-cr.protoml.dev`)
- Credentials come from `config.yaml` or, if omitted, reuse your API key
- When both `--push` and `--push-remote` are enabled the CLI pushes to the local registry first, then mirrors the tag to the remote endpoint

<Callout type="warning">
You can opt out of pushing entirely with `--push=false`, but keep in mind that `agnt5 deploy` still expects to deploy the latest image tag.
</Callout>

## Workspace Validation and Deployment

The deployment step uses the Control Plane API to ensure your workspace is ready:

### Workspace States

| State | Action |
| --- | --- |
| **No workspace** | CLI creates one automatically and waits (up to 10 minutes) for it to reach the `ready` phase |
| **Paused** | Workspaces are resumed before deployment |
| **Pending/Provisioning** | Triggers a wait loop until ready |
| **Failed** | Produces actionable error messages and stops the deployment |

### Deployment Process

When the workspace is ready the CLI constructs a deployment payload with your image reference, replica count, and resource hints, then polls every five seconds (for up to five minutes) for the deployment to reach a `running`/`ready` status. Upon success it prints handy follow-up steps, including a `curl` example and a reminder to inspect logs via `agnt5 logs`.

## Complete Example Workflow

```bash
# 1. Check deployment plan
agnt5 deploy --prod --dry-run --replicas 3

# 2. Build and deploy to production
agnt5 deploy --prod --replicas 3 --cpu 1 --memory 1Gi --tags v1.2.0

# 3. Monitor deployment (see deployment visibility commands)
agnt5 list --environment production
agnt5 logs
```

<Callout type="tip">
Use `--dry-run` first to verify the deployment plan, then run the full command. Combine with `agnt5 list` and `agnt5 logs` to monitor the rollout.
</Callout>


**Programmatic equivalents**: the CLI calls Control Plane HTTP endpoints — see [API reference](/api-reference/create-contact.md) for the request shapes

---

## Deployment Visibility Commands

_Source: https://agnt5.com/cli_

> Monitor and inspect deployment history and logs

Two top-level commands surface deployment information. They mirror Vercel's `vercel list` and `vercel logs`, but the current implementation is still a work in progress. Expect behavior to evolve as the Control Plane endpoints mature.


**Commands**: `agnt5 list [--environment <env>] [--limit <n>] [--status <s>] [--all]` (alias `agnt5 ls`); `agnt5 logs [options]`
**Status**: work-in-progress; both commands return a placeholder error today (`list functionality not yet implemented`) — use the Control Plane UI/API directly until the integration ships
**Inspection alternatives**: query the Control Plane HTTP API or browse Studio


<Callout type="warning">
**Work in Progress**

Both commands are currently under development. They return placeholder errors today but will provide full deployment visibility once the Control Plane endpoints are stabilized.
</Callout>

### `agnt5 list`

<CommandLayout command="list">
  <div slot="documentation">
    Displays a list of deployments for the current project. The command accepts filters that will be wired to the Control Plane once the backing API stabilizes.

    ### Syntax
    ```bash
    agnt5 list [options]
    agnt5 ls [options]
    ```

    ### Options

    | Flag | Description |
    | --- | --- |
    | `--environment` | Environment to inspect (default: `development`) |
    | `--limit` | Maximum number of deployments to show (default: `10`) |
    | `--status` | Filter by deployment status |
    | `--all` | Include deployments from every environment |

    <Callout type="info">
    **Current Status:** Returns a placeholder error today (`list functionality not yet implemented`). Use the Control Plane UI or APIs directly for detailed history until the CLI integration ships.
    </Callout>
  </div>

  <div slot="examples">
    
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          # List recent deployments
          agnt5 list
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Error: list functionality not yet implemented

          Use the Control Plane UI for deployment history.
          ```
        </ExampleBlock>

        <ExampleBlock title="Command" variant="command">
          ```bash
          # Short alias
          agnt5 ls
          ```
        </ExampleBlock>
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Filter by status
          agnt5 list --status running --limit 20
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Error: list functionality not yet implemented

          Expected output:
          ID          | Status  | Environment | Created    | Image
          ------------|---------|-------------|------------|-------
          dep-abc123  | running | production  | 2 min ago  | v1.2.0
          dep-def456  | running | staging     | 1 hr ago   | v1.1.8
          ```
        </ExampleBlock>

        <ExampleBlock title="Command" variant="command">
          ```bash
          # List all deployments across environments
          agnt5 list --all
          ```
        </ExampleBlock>
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Show production deployments
          agnt5 list --environment production
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Error: list functionality not yet implemented

          Expected output for production:
          ID          | Status  | Created    | Image  | Replicas
          ------------|---------|------------|--------|----------
          dep-prod-01 | running | 2 min ago  | v1.2.0 | 3/3
          dep-prod-02 | stopped | 1 hr ago   | v1.1.9 | 0/3
          ```
        </ExampleBlock>
      
    
  </div>
</CommandLayout>

### `agnt5 logs`

<CommandLayout command="logs">
  <div slot="documentation">
    Streams logs for a specific deployment. When an ID is omitted the command will eventually default to the latest deployment for the current project.

    ### Syntax
    ```bash
    agnt5 logs [deployment-id] [options]
    ```

    ### Options

    | Flag | Description |
    | --- | --- |
    | `--follow`, `-f` | Follow log output |
    | `--tail` | Number of lines to show from the end of the logs (default: `100`) |
    | `--since` | Timestamp or duration filter (e.g., `2h`, `30m`) |

    <Callout type="info">
    **Current Status:** Returns a placeholder error until log streaming is implemented. The CLI currently surfaces a message reminding you that a deployment ID is required.
    </Callout>
  </div>

  <div slot="examples">
    
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Show logs for latest deployment
          agnt5 logs
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Error: deployment ID required

          Log streaming not yet implemented.
          Use the Control Plane UI for deployment logs.
          ```
        </ExampleBlock>

        <ExampleBlock title="Command" variant="command">
          ```bash
          # Show last 50 lines from recent logs
          agnt5 logs --tail 50
          ```
        </ExampleBlock>
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Stream logs for specific deployment
          agnt5 logs deploy-abc123 --follow
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Error: deployment ID required

          Expected behavior:
          2024-01-15T10:30:45Z [INFO] Starting service...
          2024-01-15T10:30:46Z [INFO] Handler registered: greet_user
          2024-01-15T10:30:47Z [INFO] Service ready on port 8080
          2024-01-15T10:30:48Z [INFO] Received request: greet_user
          ... (streaming continues)
          ```
        </ExampleBlock>

        <ExampleBlock title="Command" variant="command">
          ```bash
          # Follow logs with short flag
          agnt5 logs deploy-abc123 -f
          ```
        </ExampleBlock>
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Show logs from last 2 hours
          agnt5 logs --since 2h
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Error: deployment ID required

          Expected filtered output:
          2024-01-15T08:30:45Z [INFO] Service healthy
          2024-01-15T08:35:12Z [INFO] Request processed
          2024-01-15T09:15:33Z [WARN] High memory usage
          2024-01-15T09:45:21Z [INFO] Memory usage normal
          ```
        </ExampleBlock>

        <ExampleBlock title="Command" variant="command">
          ```bash
          # Follow logs with time filter
          agnt5 logs deploy-abc123 -f --since 30m
          ```
        </ExampleBlock>
      
    
  </div>
</CommandLayout>

## Planned Integration

Once these commands are complete they will work hand-in-hand with `agnt5 deploy` to provide an end-to-end workflow:

### Example Future Workflow

```bash
# 1. Deploy your project
agnt5 deploy --prod

# 2. List deployments to see the new one
agnt5 list --environment production

# 3. Monitor logs for the deployment
agnt5 logs deploy-abc123 --follow

# 4. Check deployment status
agnt5 list --status running
```

### Integration with Deployment Pipeline

The visibility commands will integrate seamlessly with the deployment workflow:

- **Post-deployment monitoring**: After `agnt5 deploy` completes, use `agnt5 logs` to monitor the new deployment
- **Historical analysis**: Use `agnt5 list` to compare deployment performance over time
- **Debugging**: Filter logs by time ranges to troubleshoot specific deployment issues
- **Multi-environment visibility**: Compare deployments across development, staging, and production

### Expected Features

When implementation is complete, expect:

- **Rich filtering**: Filter deployments by status, environment, time range, and more
- **Real-time updates**: Live log streaming with automatic reconnection
- **Deployment details**: Full metadata about each deployment including build info, resource usage, and health status
- **Integration hooks**: Commands will automatically detect the current project context and default to relevant deployments

<Callout type="tip">
Until these commands are implemented, you can monitor deployments through the Control Plane UI or use the direct APIs for programmatic access.
</Callout>

---

## CLI Overview

_Source: https://agnt5.com/cli_

> Command-line interface for developing, testing, and deploying AI workflows locally and in production

**Binary**: `agnt5`
**Install (macOS)**: `brew install agnt5/tap/agnt5`
**Install (Linux)**: `curl -LsSf https://agnt5.com/cli.sh | bash`
**Core commands**: `agnt5 init`, `agnt5 deploy`, `agnt5 logs`, `agnt5 config`, `agnt5 auth`, `agnt5 project`
**Config home**: `~/.agnt5/` (credentials, context)


## Core Commands

- `agnt5 init` - Scaffold new projects from templates
- `agnt5 deploy` - Push to production or staging environments
- `agnt5 logs` - Stream logs from any environment
- `agnt5 config` - Manage environment variables and settings

## Installation


  

  
    Install the CLI using Homebrew:

    ```bash
    brew install agnt5/tap/agnt5
    ```

  

  
    Install using the install script:

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

    <Callout type="warning">
    **Configure your PATH**

    Add the CLI to your PATH after installation:

    ```bash
    echo 'export PATH="$HOME/.agnt5/bin:$PATH"' >> ~/.bashrc
    source ~/.bashrc
    ```

    Use `~/.zshrc` if you're using zsh instead of bash.
    </Callout>

  


### Verify Installation

```bash
agnt5 --version
```

## Quickstart

```bash
# Initialize a new project
agnt5 init my-workflow
cd my-workflow

# Authenticate and deploy
agnt5 auth login
agnt5 deploy
```

## Upgrading


  

{" "}


    ```bash
    brew upgrade agnt5
    ```
  

  
    ```bash
    agnt5 upgrade
    ```

---

## Project Management Commands

_Source: https://agnt5.com/cli_

> Create and manage AGNT5 projects with Control Plane integration

The `agnt5 project` command family helps you create Control Plane projects, sync local configuration, and explore existing projects. Many operations require an API key because they call the Control Plane directly.


**Commands**: `agnt5 project create [name] [--organization-id <id>]` (alias `agnt5 create`); other `agnt5 project` subcommands manage existing projects
**Languages supported**: `python`, `typescript`
**Required**: API key (`agnt5 auth login` first)
**Side effects**: creates project in Control Plane; for Python projects scaffolds `app.py`, `src/<project>/functions.py`, etc.; writes `.agnt5/project-ref` for subsequent CLI calls


### `agnt5 project create`

<CommandLayout command="project create">
  <div slot="documentation">
    Creates a new project remotely and, for Python projects, scaffolds a ready-to-run repository on disk. The command is also available as a top-level shortcut `agnt5 create`.

    ### Syntax
    ```bash
    agnt5 project create [project-name] [options]
    agnt5 create [project-name] [options]
    ```

    ### Options

    | Flag | Description |
    | --- | --- |
    | `--organization-id` | Force the Control Plane organization to associate with the new project. |

    ### Flow Summary

    1. Prompt (or accept a CLI argument) for the project name
    2. Prompt for a language (`python` or `typescript`)
    3. Resolve the organization ID or prompt to choose
    4. Call the Control Plane to create the project
    5. Generate full project skeleton for Python projects
    6. Write `.agnt5/project-ref` for future CLI commands
    7. Print next steps

    ### Python Project Scaffolding

    For Python projects, the CLI generates:
    - `app.py`, `src/<project>/functions.py`
    - `tests/__init__.py`, `tests/test_functions.py`
    - `pyproject.toml`, `agnt5.yaml`, `Dockerfile`
    - `.gitignore`, `README.md`

    <Callout type="info">
    Non-Python languages currently skip the scaffolding step but still create the remote project and update your local metadata.
    </Callout>
  </div>

  <div slot="examples">
    
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 project create
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          ? Project name: my-ai-workflow
          ? Select language:
            ❯ python
              typescript
          ? Python version: 3.12

          ? Select organization:
            ❯ Acme Corp (org-abc123)
              Personal (org-def456)

          Creating project...
          ✓ Project created successfully

          Project Details:
            ID: proj-xyz789
            Name: my-ai-workflow
            Slug: my-ai-workflow
            Reference: acme/my-ai-workflow
            Status: active

          Next steps:
            cd my-ai-workflow
            pip install -r requirements.txt
            agnt5 deploy
          ```
        </ExampleBlock>
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 create python-workflow
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Creating project 'python-workflow'...
          ? Select language: python
          ? Python version: 3.12
          ? Organization: Acme Corp (org-abc123)

          ✓ Project created in Control Plane
          ✓ Generating Python project structure...

          Generated files:
            ✓ app.py
            ✓ src/python_workflow/__init__.py
            ✓ src/python_workflow/functions.py
            ✓ tests/test_functions.py
            ✓ pyproject.toml
            ✓ agnt5.yaml
            ✓ Dockerfile
            ✓ .gitignore
            ✓ README.md

          ✓ .agnt5/project-ref created

          Project ready! Next steps:
            cd python-workflow
            pip install -e .
            agnt5 deploy
          ```
        </ExampleBlock>
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 create my-project --organization-id org-abc123
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Creating project 'my-project'...
          Using organization: org-abc123

          ? Select language:
            ❯ python
              typescript

          ✓ Project created successfully

          Project Details:
            ID: proj-123456
            Organization: org-abc123
            Reference: acme/my-project

          Project directory created with Python scaffolding.
          ```
        </ExampleBlock>
      
    
  </div>
</CommandLayout>

### `agnt5 project list`

<CommandLayout command="project list">
  <div slot="documentation">
    Lists projects visible to your API key in a simple table. Pagination, search, and ordering options are available.

    ### Syntax
    ```bash
    agnt5 project list [options]
    ```

    ### Options

    | Flag | Description |
    | --- | --- |
    | `--page`, `-p` | Page number to request (default: `1`) |
    | `--page-size` | Number of projects per page (default: `20`) |
    | `--search`, `-s` | Filter by name, ref, or slug |
    | `--language`, `-l` | Filter by language (e.g., `python`) |
    | `--status` | Filter by status returned from the Control Plane |
    | `--order-by` | Sort column: `created`, `updated`, `name` (default: `updated`) |
    | `--order-dir` | Sort direction: `asc` or `desc` (default: `desc`) |

    The output includes truncated IDs, names, references, languages (with versions when available), statuses, and creation dates. Pagination metadata at the bottom shows how many results are displayed relative to the total.
  </div>

  <div slot="examples">
    
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 project list
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Projects (showing 3 of 3 total):

          ID        | Name             | Reference           | Language | Status  | Updated
          ----------|------------------|---------------------|----------|---------|----------
          proj-abc  | my-ai-workflow   | acme/my-ai-workflow | python   | active  | 2 days ago
          proj-def  | data-processor   | acme/data-processor | python   | active  | 1 week ago
          proj-ghi  | api-service      | acme/api-service    | node     | paused  | 2 weeks ago

          Page 1 of 1 (3 projects total)
          ```
        </ExampleBlock>
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 project list --search "workflow" --language python
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Projects matching 'workflow' (language: python):

          ID        | Name             | Reference           | Language | Status  | Updated
          ----------|------------------|---------------------|----------|---------|----------
          proj-abc  | my-ai-workflow   | acme/my-ai-workflow | python   | active  | 2 days ago
          proj-xyz  | batch-workflow   | acme/batch-workflow | python   | active  | 5 days ago

          Page 1 of 1 (2 projects found, 2 total)
          ```
        </ExampleBlock>
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 project list --page 2 --page-size 10 --order-by created --order-dir asc
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Projects (page 2, ordered by created date):

          ID        | Name             | Reference           | Language | Status  | Created
          ----------|------------------|---------------------|----------|---------|----------
          proj-klm  | analytics-api    | acme/analytics-api  | python   | active  | Jan 15
          proj-nop  | webhook-handler  | acme/webhook-handler| node     | active  | Jan 18
          proj-qrs  | ml-pipeline      | acme/ml-pipeline    | python   | active  | Jan 20

          Page 2 of 5 (30 projects total, showing 11-20)
          ```
        </ExampleBlock>
      
    
  </div>
</CommandLayout>

### `agnt5 project info`

<CommandLayout command="project info">
  <div slot="documentation">
    <Callout type="warning">
    **Work in Progress**

    Placeholder command that will eventually print detailed metadata about the current project or a provided ID. For now it simply acknowledges the request. Use `agnt5 project list` to locate IDs until the implementation is complete.
    </Callout>

    ### Syntax
    ```bash
    agnt5 project info [project-id]
    ```

    This command will eventually provide comprehensive project details including configuration, deployment status, environment variables, and resource usage metrics.
  </div>

  <div slot="examples">
    
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 project info
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Command acknowledged but not yet implemented.
          Use 'agnt5 project list' to view available projects.
          ```
        </ExampleBlock>
      

      
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 project info proj-123
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Command acknowledged but not yet implemented.
          Use 'agnt5 project list' to view available projects.
          ```
        </ExampleBlock>
      
    
  </div>
</CommandLayout>

### `agnt5 project init`

<CommandLayout command="project init">
  <div slot="documentation">
    <Callout type="warning">
    **Work in Progress**

    Reserved for initializing an existing directory as an AGNT5 project. The command currently prints a stub message.
    </Callout>

    ### Syntax
    ```bash
    agnt5 project init
    ```

    This command will eventually initialize an existing directory as an AGNT5 project by creating the necessary configuration files and project metadata.
  </div>

  <div slot="examples">
    <ExampleBlock title="Command" variant="command">
      ```bash
      agnt5 project init
      ```
    </ExampleBlock>

    <ExampleBlock title="Response" variant="response">
      ```
      Command acknowledged but not yet implemented.
      Use 'agnt5 project create' to create new projects.
      ```
    </ExampleBlock>
  </div>
</CommandLayout>

## Local Project Metadata

Most project-aware commands rely on two files created during `project create`:

| File | Purpose |
| --- | --- |
| `.agnt5/project-ref` | Binds the working directory to a Control Plane project reference |
| `agnt5.yaml` | Holds language, environment, deploy, and variable configuration for the deployment pipeline |

<Callout type="tip">
If you clone an existing project make sure both files are present (or run `SaveProjectRef` / `SaveDeploymentProjectConfig` helper functions) before using `agnt5 deploy`.
</Callout>

### Project Reference File

The `.agnt5/project-ref` file contains the Control Plane project reference that links your local directory to the remote project. This file is automatically created during `agnt5 project create` and is required for deployment commands.

### Deployment Configuration

The `agnt5.yaml` file contains project-specific configuration used by the deployment pipeline:

```yaml
# Example agnt5.yaml structure
language: python
version: "3.12"
environment:
  development:
    # Development-specific config
  production:
    # Production-specific config
deploy:
  # Deployment configuration
variables:
  # Environment variables
```

---

## Troubleshooting

_Source: https://agnt5.com/cli_

> Common issues and solutions for the AGNT5 CLI

Common issues and solutions when using the AGNT5 CLI.


**Diagnostic commands**: `agnt5 --version`, `agnt5 auth whoami`, `agnt5 context`
**Common failure modes**: missing CLI on PATH (`command not found`); missing/expired credentials; Docker daemon unreachable; wrong context for the target environment
**Reset paths**: re-run `agnt5 auth login` to refresh credentials; `agnt5 context use <name>` to switch environment; reinstall via the platform's install method to fix PATH issues


## Installation Issues

### Command Not Found

**Problem**: `agnt5: command not found` after installation.

**Solutions**:
1. **Check if npm global packages are in PATH**:
   ```bash
   npm config get prefix
   echo $PATH
   ```

2. **Reinstall the CLI**:
   ```bash
   npm uninstall -g agnt5
   npm install -g agnt5
   ```

3. **Use npx as alternative**:
   ```bash
   npx agnt5 --version
   ```

4. **Add npm global bin to PATH** (if missing):
   ```bash
   # Add to ~/.bashrc or ~/.zshrc
   export PATH=$PATH:$(npm config get prefix)/bin
   ```

### Permission Denied

**Problem**: Permission errors during installation on macOS/Linux.

**Solutions**:
1. **Use a Node version manager** (recommended):
   ```bash
   # Install nvm
   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
   nvm install 18
   nvm use 18
   npm install -g agnt5
   ```

2. **Change npm's default directory**:
   ```bash
   mkdir ~/.npm-global
   npm config set prefix '~/.npm-global'
   echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
   source ~/.bashrc
   npm install -g agnt5
   ```

3. **Use sudo** (not recommended):
   ```bash
   sudo npm install -g agnt5
   ```

### Windows Installation Issues

**Problem**: Installation fails on Windows.

**Solutions**:
1. **Run as Administrator**:
   - Right-click Command Prompt/PowerShell
   - Select "Run as Administrator"
   - Run installation command

2. **Use Windows Subsystem for Linux (WSL)**:
   ```bash
   wsl --install
   # Then install in WSL environment
   ```

3. **Use Chocolatey**:
   ```bash
   choco install nodejs
   npm install -g agnt5
   ```

## Authentication Issues

### Invalid API Key

**Problem**: "Invalid API key" or "Unauthorized" errors.

**Solutions**:
1. **Verify your API key**:
   ```bash
   agnt5 config get api-key
   ```

2. **Reset and re-enter API key**:
   ```bash
   agnt5 config set api-key your-new-api-key
   ```

3. **Use interactive login**:
   ```bash
   agnt5 auth login
   ```

4. **Check environment variables**:
   ```bash
   echo $AGNT5_API_KEY
   ```

### Token Expired

**Problem**: Authentication token has expired.

**Solutions**:
1. **Re-authenticate**:
   ```bash
   agnt5 auth logout
   agnt5 auth login
   ```

2. **Generate new API key** from AGNT5 dashboard

3. **Update configuration**:
   ```bash
   agnt5 config set api-key your-new-key
   ```

## Deployment Issues

### Deployment Timeout

**Problem**: Deployments fail due to timeout.

**Solutions**:
1. **Increase timeout**:
   ```bash
   agnt5 deploy --timeout 600000  # 10 minutes
   ```

2. **Configure in project config**:
   ```javascript
   // agnt5.config.js
   module.exports = {
     deploy: {
       timeout: 600000
     }
   };
   ```

3. **Check deployment status**:
   ```bash
   agnt5 status --env production --verbose
   ```

4. **Use incremental deployment**:
   ```bash
   agnt5 deploy --incremental
   ```

### Build Failures

**Problem**: Build process fails during deployment.

**Solutions**:
1. **Check build logs**:
   ```bash
   agnt5 build --verbose
   ```

2. **Clean build cache**:
   ```bash
   agnt5 build --clean
   ```

3. **Test build locally**:
   ```bash
   agnt5 build --env production
   ```

4. **Check dependencies**:
   ```bash
   npm audit
   npm update
   ```

## Network Issues

### Connection Timeout

**Problem**: Commands fail with connection timeout.

**Solutions**:
1. **Check network connectivity**:
   ```bash
   ping api.agnt5.com
   ```

2. **Increase timeout**:
   ```bash
   agnt5 config set timeout 60000
   ```

3. **Configure proxy** (if behind corporate firewall):
   ```bash
   npm config set proxy http://proxy.company.com:8080
   npm config set https-proxy http://proxy.company.com:8080
   ```

4. **Use different base URL**:
   ```bash
   agnt5 config set base-url https://api-eu.agnt5.com
   ```

### SSL Certificate Issues

**Problem**: SSL/TLS certificate errors.

**Solutions**:
1. **Update Node.js** to latest stable version

2. **Use different registry** (temporary):
   ```bash
   npm config set registry https://registry.npmjs.org/
   ```

3. **Disable SSL verification** (not recommended for production):
   ```bash
   npm config set strict-ssl false
   ```

4. **Update CA certificates**:
   ```bash
   # macOS
   brew update && brew upgrade ca-certificates

   # Ubuntu/Debian
   sudo apt-get update && sudo apt-get upgrade ca-certificates
   ```

## Performance Issues

### Slow Commands

**Problem**: CLI commands are running slowly.

**Solutions**:
1. **Enable caching**:
   ```bash
   agnt5 config set cache.enabled true
   ```

2. **Increase concurrency**:
   ```bash
   agnt5 config set concurrency 20
   ```

3. **Use local runtime** for development:
   ```bash
   agnt5 run workflow --local
   ```

4. **Profile command execution**:
   ```bash
   agnt5 --verbose --profile run workflow
   ```

### Memory Issues

**Problem**: CLI process uses too much memory.

**Solutions**:
1. **Increase Node.js memory limit**:
   ```bash
   export NODE_OPTIONS="--max-old-space-size=4096"
   agnt5 command
   ```

2. **Reduce concurrency**:
   ```bash
   agnt5 config set workflows.concurrency 5
   ```

3. **Clear cache**:
   ```bash
   agnt5 cache clear
   ```

## Configuration Issues

### Configuration Not Loading

**Problem**: CLI ignores configuration files.

**Solutions**:
1. **Verify config file location**:
   ```bash
   agnt5 config validate --verbose
   ```

2. **Check config file syntax**:
   ```bash
   node -c agnt5.config.js
   ```

3. **Use explicit config file**:
   ```bash
   agnt5 --config ./my-config.js command
   ```

4. **Reset configuration**:
   ```bash
   agnt5 config reset
   ```

## Getting Help

### Enable Debug Mode

For detailed troubleshooting information:

```bash
agnt5 --debug command
agnt5 --verbose command
```

### Check System Information

```bash
agnt5 doctor --verbose
```

### Validate Setup

```bash
agnt5 config validate
agnt5 auth whoami
agnt5 status --verbose
```

### Contact Support

If you're still experiencing issues:

1. **Check the logs**:
   ```bash
   agnt5 logs --level error --tail 100
   ```

2. **Create a minimal reproduction case**

3. **Include system information**:
   ```bash
   agnt5 --version
   node --version
   npm --version
   echo $AGNT5_API_KEY | cut -c1-8  # First 8 chars only
   ```

4. **Report the issue** with full error messages and steps to reproduce


# Changelog

---

## Agent Memory and Context Management

_Source: https://agnt5.com/changelog_

> Persistent conversation memory with automatic context window management

Agents now maintain durable conversation history across sessions with intelligent context window management. No more context loss when conversations span days or exceed token limits.

## Automatic Context Summarization

When conversation history approaches the LLM's token limit, AGNT5 automatically summarizes older messages while preserving recent exchanges verbatim:

```python
@agent()
class SupportAgent:
    async def handle_message(self, user_id: str, message: str):
        # Context automatically managed
        response = await self.chat(message)
        return response
```

The agent maintains full conversation history in durable storage. Recent messages stay intact for immediate context. Older messages get compressed through summarization. The LLM sees a seamless conversation thread that fits within token limits.

## Why Context Matters

Long-running agent conversations — customer support, research assistants, coding copilots — require persistent memory. Users expect agents to remember previous interactions, not restart from scratch each session.

With automatic context management, your agents scale to conversations of any length. The complexity of token counting, summarization, and history management becomes invisible.

[Read the agent documentation](/docs/fundamentals/agents.md) for implementation details.

---

## Python SDK: Type-Safe Entity State

_Source: https://agnt5.com/changelog_

> TypedDict support for entity state with full autocomplete and validation

Entity state management now supports Python's `TypedDict`, bringing full type safety and IDE autocomplete to your durable entities.

### The Problem

Previously, entity state was untyped — a plain dictionary that could hold any structure. This worked, but required manual validation and provided no IDE support:

```python
@entity()
class UserSession:
    async def update_preferences(self, key: str, value: any):
        # What fields exist in self.state? No autocomplete to help.
        self.state[key] = value
```

#### The Solution

Define your state structure with `TypedDict`, and the SDK enforces it at runtime:

```python
from typing import TypedDict

class SessionState(TypedDict):
    user_id: str
    preferences: dict[str, str]
    last_active: int

@entity()
class UserSession:
    state: SessionState

    async def update_preference(self, key: str, value: str):
        # Full autocomplete on self.state.preferences
        self.state["preferences"][key] = value
```

Type checking happens automatically. Invalid state updates fail fast with clear error messages. Your IDE provides autocomplete for all state fields.

Read the [entity documentation](/docs/fundamentals/entities.md) to learn more about type-safe state management.

---

## Improved Workflow State Persistence

_Source: https://agnt5.com/changelog_

> Enhanced checkpoint recovery and deterministic replay for long-running workflows

When workflows span hours or days, state persistence becomes critical. This release strengthens AGNT5's checkpoint recovery system to handle complex state transitions more reliably.

## What Changed

We've redesigned how workflow state gets persisted during execution. Previously, checkpoints were created after each function invocation. Now, checkpoints capture the complete workflow context — including local variables, pending tasks, and execution history.

```python
@workflow()
async def research_pipeline(topic: str):
    # Checkpoint created here with full context
    sources = await gather_sources(topic)

    # If failure occurs here, workflow resumes with sources intact
    summaries = await summarize_sources(sources)

    return await synthesize_report(summaries)
```

This means when a workflow resumes after a failure, it picks up exactly where it left off. No re-execution of completed steps. No lost progress.

## Why This Matters

Long-running AI workflows often fail mid-execution — API timeouts, rate limits, infrastructure issues. With enhanced checkpoint recovery, these failures no longer mean starting over.

Your workflows become truly durable. Pause them. Resume them. Replay them with different code. The execution history is the source of truth.

Learn more in the [workflow documentation](/docs/fundamentals/workflows.md).