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

# Edit and run plans

> Update plan steps with revision checks and approval checkpoints.

Use the [quickstart client](/docs/documentation/agent/sdk/quickstart#create-a-client). Replace uppercase IDs with your plan and conversation IDs.
The `SAVED_*_KEY` values represent persisted keys for those commands.

A plan is a `fal.block` with `kind: "plan"` inside an assistant message.
Use its ID with `agent.plans`. Pass the owning conversation ID with every plan request.

## Methods

| Method                                                         | Result                                      |
| -------------------------------------------------------------- | ------------------------------------------- |
| `plans.retrieve(id, { conversation, ...options })`             | Current `AgentPlanBlock`.                   |
| `plans.update(id, change, options?)`                           | Updated `AgentPlanBlock` with its revision. |
| `plans.run(id, { conversation, expected_revision }, options?)` | Accepted `AgentResponseView`.               |

`update` and `run` accept an `idempotencyKey` through their options.
Persist one key for each logical command before sending it.

## Update the editable steps

An update replaces the complete editable step list.
Keep existing IDs to preserve steps. Omit an ID to add a step.
Remove a step by omitting it from the array. Change execution order by reordering the array.

| Field                       | Requirement                                                               |
| --------------------------- | ------------------------------------------------------------------------- |
| `conversation`              | Owning conversation ID.                                                   |
| `expected_revision`         | Revision returned by the latest plan read.                                |
| `title`                     | Optional nonempty title, up to 120 characters.                            |
| `steps`                     | Complete array of 1–50 editable steps.                                    |
| `steps[].id`                | Existing step ID, or omitted for a new step. Existing IDs must be unique. |
| `steps[].label`             | Step instruction of 1–500 characters after trimming.                      |
| `steps[].endpoint_id`       | Model endpoint of 1–200 characters, or `null` to clear it.                |
| `steps[].model_pinned`      | Required boolean. A pinned model requires an endpoint.                    |
| `steps[].requires_approval` | Required boolean for the approval checkpoint.                             |

This example replaces the plan with one new step.

```ts theme={null}
import { agent } from "./client.ts";

const conversation = "CONVERSATION_ID";
const plan = await agent.plans.retrieve("PLAN_ID", {
  conversation,
});

await agent.plans.update(
  plan.id,
  {
    conversation,
    expected_revision: plan.revision,
    steps: [
      {
        label: "Generate a product photo",
        model_pinned: false,
        requires_approval: true,
      },
    ],
  },
  { idempotencyKey: "SAVED_EDIT_KEY" },
);
```

A stale revision or an edit during execution returns `409`.
Retrieve the latest plan and apply your changes to that version before retrying.

## Run a plan

Send the revision you want to run. In this example, that revision is `3`.

```ts theme={null}
import { agent } from "./client.ts";

const response = await agent.plans.run(
  "PLAN_ID",
  {
    conversation: "CONVERSATION_ID",
    expected_revision: 3,
  },
  { idempotencyKey: "SAVED_RUN_KEY" },
);

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

The returned response can pause at an approval checkpoint.
Use the [approval flow](/docs/documentation/agent/sdk/inputs) to continue that response.