> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joystream.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents and recipes

> An agent is the governed intelligent realization of a capability spec. The recipe is the approved route it travels.

The capability spec describes the organizational ability. The agent is the runnable entity created to perform it.

The shorthand:

<Note>
  Agent = Recipe + LLM reasoning
</Note>

## What an agent is made of

```mermaid theme={null}
flowchart TD
    A["<b>Agent</b>"]
    A --> B["Capability spec version"]
    A --> C["Runtime recipe"]
    A --> D["LLM reasoning"]
    A --> E["Skills and tools"]
    A --> F["Policies and boundaries"]
    A --> G["Permissions and bindings"]
    A --> H["Runtime configuration"]
    A --> I["Memory access"]
    A --> J["Evidence requirements"]
```

The agent brings intelligence to the recipe. It can interpret context, reason through ambiguity, select among approved actions, adapt inputs, make bounded decisions, request clarification, escalate, and recover from expected variation.

But it does not operate without structure. It remains governed by the capability spec, the approved recipe, access policies, tool permissions, deployment boundaries, acceptance criteria, and evidence requirements.

## The runtime recipe

The runtime recipe is the versioned, reviewable, executable plan through which an agent delivers the capability. It represents the largely deterministic way of doing things.

A recipe describes major activities, dependencies, ordering, parallel work, skills and tools, expected inputs and outputs, decision boundaries, acceptance criteria, failure policies, retries, timeouts, approvals, and escalation paths.

It is human-readable, inspectable, reviewable, versioned, bounded, executable, and replayable where appropriate.

A recipe is not a fully deterministic workflow. It defines the stable structure of the work while leaving bounded spaces in which the agent can reason.

```mermaid theme={null}
flowchart TD
    A[Destination A] --> B[Destination B]
    B --> C{Decision boundary}
    C -->|approved path| D[Path C]
    C -->|out of bounds| E[Escalation]
    D --> F[Destination D]
```

The recipe determines the destinations and the boundaries. The agent determines the best road between them.

A capability may have multiple historical recipe versions, a currently approved recipe, experimental recipes, and eventually alternative recipes for different contexts.

## Error policies

Each step in a recipe carries an error policy that decides what happens when it fails.

| Policy        | On failure                                      |
| ------------- | ----------------------------------------------- |
| `CRITICAL`    | Abort the run                                   |
| `MUST_HAPPEN` | Retry with backoff, then abort if still failing |
| `BEST_EFFORT` | Record the failure and continue                 |

These are what let a recipe stay bounded without being brittle. A best-effort notification failing shouldn't stop an onboarding; a failed account creation should.

## Agent versions

An agent version is an immutable executable realization of a capability spec version. It combines a spec version, a recipe version, selected models, skills and tools, policies, runtime configuration, and compatibility metadata.

```mermaid theme={null}
flowchart LR
    A["Capability spec v4"] --> D["<b>Agent version 12</b>"]
    B["Recipe v7"] --> D
    C["Model configuration<br/>Skills and policies"] --> D
```

An agent version is immutable once built. Changes create a new version. That gives every deployment and every run exact provenance.

A new spec, recipe, model, policy, or tool configuration may create a new agent version without creating a new capability.

## The agent stays explicit

JoyStream does not dissolve the agent into an abstract collection of actors, skills, and workflows. Users ask direct questions — what agent did we build, which agent is running, which version failed, which agent has production access — and the product answers them directly.

## In the product today

`jstm agent build` compiles a committed spec into a runnable package and pins a version. `jstm agent view <agent-id> --tree` shows the recipe as a work tree; `--graph` shows it as a graph; `--package` shows the built package.

## Next

<Columns cols={2}>
  <Card title="The lifecycle" href="/concepts/lifecycle" icon="git-branch">
    How an agent version earns its way to production.
  </Card>

  <Card title="Runs and work" href="/concepts/runs-and-work" icon="list-checks">
    What happens when a recipe actually executes.
  </Card>
</Columns>