Edit and run plans

Use the quickstart 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.

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.

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 to continue that response.

Setting Up

Model APIs

Serverless

Compute

Organizations

fal Agent

fal Assets

Edit and run plans

Methods

Update the editable steps

Run a plan

​Methods

​Update the editable steps

​Run a plan

Methods

Update the editable steps

Run a plan