Skip to main content

Quickstart: run a durable agent with your AI coding agent

In this quickstart, your AI coding agent runs a durable AI agent on Catalyst with the framework you pick. You will learn how to:

  • Set up Claude Code, Codex or the Copilot CLI with the Catalyst AI plugin.
  • Have your agent run a sample agent in your default project, or in the project you pick.
  • See a crashed agent run wait instead of fail, then finish after a restart.
tip

Not using an AI coding agent? Follow the CLI version of this quickstart.

Catalyst works with the following agent frameworks, select one and continue following the quickstart.

Your coding agent drives CatalystYour machineCatalystCoding agentCatalyst AI pluginSample agentyour frameworkMCP serverAgentyour projectshellcreates
Your coding agent drives CatalystYour agent uses the Catalyst MCP server for everything in Catalyst, and your shell to run the sample agent, which talks to Catalyst through its App ID.

1. Prerequisites​

  • Claude Code, OpenAI Codex, or the GitHub Copilot CLI. Claude Code is the agent these steps are tested with.
  • Git
  • Python 3.12 or 3.13
  • uv
  • No model API key: the sample runs on a built-in offline model.

You don't need the Diagrid CLI. The sample runs in the default project when it exists; otherwise your agent lists your projects and lets you pick one, or creates a new one for you.

2. Install the Catalyst AI plugin​

Run the command for your agent. It installs the Catalyst AI plugin: the Catalyst skills and the Catalyst MCP server:

claude plugin marketplace add diagridio/catalyst-ai && claude plugin install catalyst-ai@diagrid

The plugin installs the skills, registers the Catalyst MCP server, and adds the /catalyst-ai:try-workflow and /catalyst-ai:try-agent commands.

3. Sign in​

Authenticate once:

Run /mcp, choose plugin:catalyst-ai:catalyst, and choose Authenticate.

Your browser opens. Sign in, or create a free account, then approve your agent's access. From then on, your agent acts as you.

If you just created your account, verify your email, open catalyst.diagrid.io once to finish setting it up, and then authenticate again.

To check it worked, ask your agent: "Who am I in Catalyst?"

4. Run the demo​

Start your agent in an empty folder. For Codex and the Copilot CLI, start it in the folder where you installed the skills. Pick your framework and paste its prompt. If the framework needs a model API key, set it as an environment variable in your terminal before you start your agent: setting it later means restarting the agent.

This sample runs on a built-in offline model, so you don't need an API key.

I'm new to Diagrid Catalyst. Show me a durable LangGraph agent that survives a crash, using the Catalyst MCP tools for everything in Catalyst, and your shell for git and running the app. The sample runs on a built-in offline model, so no API key is needed. Use the LangGraph sample from step 3. Don't ask me which demo or framework to use, and don't offer `/catalyst-ai:try-agent` or any other demo.
`<project>` in this prompt is the name, not the numeric ID, of the project settled in step 2: `default` unless step 2 settles another.
Whenever a run starts, whenever you wait for me, and at the end, give me that run's console link as a markdown link, never in backticks or a code block, so I can click it: [Run <instance-id> in Catalyst](https://catalyst.diagrid.io/workflows/schedule-planner/<instance-id>?project=<project>). Put the plain URL on the line after it as well, also outside backticks, in case my terminal does not render links.
1. Call `catalyst_whoami` and tell me which org I'm signed in to. If that fails, help me sign in.
2. Check with `catalyst_list_projects` that project `default` exists, and use it if it does. If it does not, list the other projects I have and ask me to pick one or to have you create a new project for me. Only create a project if I choose that. Your Catalyst skills say not to create projects, but here I am asking you to: ask me for a name, check with `catalyst_get_usage` that I have room for another project, create it with `catalyst_apply` and a `Project` manifest (`catalyst_get_resource_schema` shows its shape), and use it from then on. Never tell me to create it myself in the console. If I have no projects, offer to create one the same way.
3. Clone https://github.com/diagridio/catalyst-quickstarts and take `agents/langgraph`. With `catalyst_apply`, make sure agent `schedule-planner` exists in project `<project>`. Catalyst provides its state, pub/sub and registry, so apply only the agent itself.
4. Get its connection with `catalyst_get_connection`, add the values to the `.env` in the sample folder (gitignored), and start `uv run crash_test.py` on port 8001 in the background with the `.env` loaded.
5. Start a run with `POST http://localhost:8001/crash/run` and the body `{"id":"gala-42","topic":"company gala on March 15","kill_after_seconds":8}`, so the agent dies mid-run. Show me with `catalyst_get_workflow_run` that the run is RUNNING and waiting, not failed, and wait until I type continue.
6. Restart it the same way. When the run completes, send the same request again to collect its result, and show me from its history that the steps finished before the crash ran once and only the one it cut off ran again.
7. Explain in at most three sentences why it survived, then offer one next step and wait for my pick.

5. What happens​

Your agent works through the prompt step by step. The Catalyst skills fire on their own; you don't name them.

  1. It checks your model key first, if the sample needs one. The key must be set as an environment variable in the terminal where you started your agent. Your agent checks that it is set without printing it. If it isn't, it stops before creating anything, so you can set the key, restart your agent and paste the prompt again. It never asks you to paste the key into the chat, and never writes it to a file.
  2. It checks who you are. catalyst-setup confirms the connection with catalyst_whoami and tells you your organization.
  3. It picks the project. It checks with catalyst_list_projects that default exists, and uses it. If default is gone, it lists your other projects and asks which to use, or whether to create a new one for you. It only creates a project if you choose that, with catalyst_apply, so you never have to create it in the console yourself.
  4. It gets the sample for your framework from catalyst-quickstarts.
  5. It creates the agent. catalyst-agent-scaffold applies the Agent resource with catalyst_apply. Catalyst provides the agent's state, pub/sub and registry, so nothing else is created.
  6. It connects the agent. catalyst_get_connection returns the connection values, which your agent adds to the sample's .env, and it starts the sample in the background with your key taken from the environment.
  7. It crashes a run. It sends POST /crash/run with kill_after_seconds: 8. The sample kills itself during its second step.
  8. It shows the run waiting. catalyst_get_workflow_run shows the run as RUNNING and waiting, not failed. Your agent waits until you type continue.
  9. It restarts the agent. The run resumes on its own. Your agent sends the same request again to collect the result.
  10. It shows the history. The first step ran once. Only the step the crash cut off ran again.
  11. It explains why, in at most three sentences, and offers you one next step.

At every stage, your agent prints a link to the run in the Catalyst console.

6. View in the Catalyst web console​

Open the link your agent printed. The run's page shows each model call and tool call as a step, with the interrupted one run twice.

7. Clean up​

Ask your agent:

Stop the sample agent, then delete its agent resource from the project you used.

Deleting is marked destructive, so your agent asks you to confirm first. The default project stays; if you created a project for the sample, your agent asks before deleting that too.

Summary​

  • You set up your AI coding agent with the Catalyst AI plugin.
  • Your agent ran a durable agent in your default project (or the one you picked) with your framework, crashed it, and showed you it resume.
  • Only the step the crash interrupted ran twice; the finished steps came from the run's history.

Next steps​

⌨️

Agent quickstart (CLI)

Run the same agent with the Diagrid CLI, step by step.

🤖

Build with an AI coding agent

Every skill in the plugin, and what your agent can change.

🧠

AI agents

How durable agents work on Catalyst.

Last updated on