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

# Migrating to the New Agent Loop

> Use Astro's /migrate command to upgrade your agent from the legacy loop to the new agent loop

The `/migrate` command tells Astro to automatically convert your agent from the **old agent loop** to the **new loop**. The new loop uses only `agent` and `output` nodes, removing legacy node types like `url`, `playwright_script`, and `api`.

## When to Migrate

Legacy agents can no longer run: an execution request for an agent that hasn't been migrated is rejected before it starts. If your agent was built before the new loop was introduced, migrating is required to get it running again.

Your agent needs migrating if it contains any of these legacy node types:

* `url` — standalone URL navigation nodes
* `playwright_script` — raw Playwright script nodes
* `api` — direct API call nodes

New agents built today use the new loop by default.

## How to Use /migrate

Open Astro on your agent's Builder page and type:

```
/migrate
```

Astro will analyse your current agent and apply all necessary transformations automatically, saving as it goes.

## What Gets Changed

<AccordionGroup>
  <Accordion title="new_agent_loop flag">
    Sets `new_agent_loop: true` as a top-level key in the workflow's `settings.yaml`.
  </Accordion>

  <Accordion title="URL nodes removed">
    Each `url` node is removed. Its target URL is merged into the nearest downstream `agent` node as a "go to \<url>" instruction at the start of that node's instructions.
  </Accordion>

  <Accordion title="Playwright script nodes converted">
    Each `playwright_script` node becomes an `agent` node whose `instructions.md` describes the action in objective terms, letting the model adapt to the page. Only where the script is already proven and stable does Astro keep the fast path.
  </Accordion>

  <Accordion title="API nodes removed">
    Each `api` node is removed. The nearest relevant `agent` node is updated with an instruction to make the request itself — in-page, or via bash for a server-side call — and to pass any result downstream as an output variable.
  </Accordion>

  <Accordion title="Tools converted to capabilities">
    The new loop has no per-node tool list, so each legacy node's `tools` array becomes a `capabilities` object.
  </Accordion>

  <Accordion title="Routing terminology updated">
    All uses of "routing" and "interrupting" are replaced with "hand off".
  </Accordion>

  <Accordion title="Scratchpad replaced with output variables">
    Scratchpad read/write operations are replaced with output variable operations — for example, "place the result on the scratchpad" becomes "pass the result as an output variable".
  </Accordion>

  <Accordion title="Failure handling moved to output nodes">
    Outcome-selection logic (e.g. "hand off with outcome 'success' if X, 'failure' if Y") is moved out of `agent` node instructions and into the corresponding `output` node's `instructions.md`, with `instructions_enabled: true` set on that output node.
  </Accordion>

  <Accordion title="query_context usage rewritten">
    Any node that relied on `query_context` is updated to read the value from its execution data directly, and the upstream node is updated to output that value explicitly.
  </Accordion>
</AccordionGroup>

## After Migration

Once Astro has saved the draft, review the changes in the Builder before publishing:

* Confirm no `url`, `playwright_script`, or `api` nodes remain
* Check that each `agent` node's instructions accurately describe the intended behaviour
* Verify that output nodes have the correct outcome-selection criteria in their instructions
* Run a test execution to confirm the agent behaves as expected