# 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](https://docs.diagrid.io/getting-started/quickstarts/ai-agents). ::: Catalyst works with the following agent frameworks, select one and continue following the quickstart. **Supported agent frameworks:** CrewAI, LangGraph, Strands, Microsoft Agent Framework, Spring AI, Google ADK, OpenAI Agents, Pydantic AI, Deep Agents, Claude Agents, Mastra **Diagram: Your coding agent drives Catalyst.** Your 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. - **Your machine**: Coding agent (Catalyst AI plugin), Sample agent (your framework) - **Catalyst**: MCP server, Agent (your project) - Coding agent (Catalyst AI plugin) → Sample agent (your framework) (shell) - Coding agent (Catalyst AI plugin) → MCP server - MCP server → Agent (your project) (creates) - Sample agent (your framework) ↔ Agent (your project) ## 1. Prerequisites **CrewAI** - Claude Code, OpenAI Codex, or the GitHub Copilot CLI. Claude Code is the agent these steps are tested with. - [Git](https://git-scm.com/downloads) - [Python 3.12 or 3.13](https://www.python.org/downloads/) - [uv](https://docs.astral.sh/uv/getting-started/installation/) - [An OpenAI API key](https://platform.openai.com/api-keys) set as the OPENAI_API_KEY environment variable before you start your agent **LangGraph** - Claude Code, OpenAI Codex, or the GitHub Copilot CLI. Claude Code is the agent these steps are tested with. - [Git](https://git-scm.com/downloads) - [Python 3.12 or 3.13](https://www.python.org/downloads/) - [uv](https://docs.astral.sh/uv/getting-started/installation/) - No model API key: the sample runs on a built-in offline model. **Strands** - Claude Code, OpenAI Codex, or the GitHub Copilot CLI. Claude Code is the agent these steps are tested with. - [Git](https://git-scm.com/downloads) - [Python 3.12 or 3.13](https://www.python.org/downloads/) - [uv](https://docs.astral.sh/uv/getting-started/installation/) - [An OpenAI API key](https://platform.openai.com/api-keys) set as the OPENAI_API_KEY environment variable before you start your agent **Microsoft Agent Framework** - Claude Code, OpenAI Codex, or the GitHub Copilot CLI. Claude Code is the agent these steps are tested with. - [Git](https://git-scm.com/downloads) - [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) - No model API key: the sample runs on a built-in offline model. **Spring AI** - Claude Code, OpenAI Codex, or the GitHub Copilot CLI. Claude Code is the agent these steps are tested with. - [Git](https://git-scm.com/downloads) - [JDK 21](https://adoptium.net/) and [Maven 3.9+](https://maven.apache.org/download.cgi) - No model API key: the sample runs on a built-in offline model. **Google ADK** - Claude Code, OpenAI Codex, or the GitHub Copilot CLI. Claude Code is the agent these steps are tested with. - [Git](https://git-scm.com/downloads) - [Python 3.12 or 3.13](https://www.python.org/downloads/) - [uv](https://docs.astral.sh/uv/getting-started/installation/) - [An OpenAI API key](https://platform.openai.com/api-keys) set as the OPENAI_API_KEY environment variable before you start your agent **OpenAI Agents** - Claude Code, OpenAI Codex, or the GitHub Copilot CLI. Claude Code is the agent these steps are tested with. - [Git](https://git-scm.com/downloads) - [Python 3.12 or 3.13](https://www.python.org/downloads/) - [uv](https://docs.astral.sh/uv/getting-started/installation/) - [An OpenAI API key](https://platform.openai.com/api-keys) set as the OPENAI_API_KEY environment variable before you start your agent **Pydantic AI** - Claude Code, OpenAI Codex, or the GitHub Copilot CLI. Claude Code is the agent these steps are tested with. - [Git](https://git-scm.com/downloads) - [Python 3.12 or 3.13](https://www.python.org/downloads/) - [uv](https://docs.astral.sh/uv/getting-started/installation/) - [An OpenAI API key](https://platform.openai.com/api-keys) set as the OPENAI_API_KEY environment variable before you start your agent **Deep Agents** - Claude Code, OpenAI Codex, or the GitHub Copilot CLI. Claude Code is the agent these steps are tested with. - [Git](https://git-scm.com/downloads) - [Python 3.12 or 3.13](https://www.python.org/downloads/) - [uv](https://docs.astral.sh/uv/getting-started/installation/) - [An OpenAI API key](https://platform.openai.com/api-keys) set as the OPENAI_API_KEY environment variable before you start your agent **Claude Agents** - Claude Code, OpenAI Codex, or the GitHub Copilot CLI. Claude Code is the agent these steps are tested with. - [Git](https://git-scm.com/downloads) - [Python 3.12 or 3.13](https://www.python.org/downloads/) - [uv](https://docs.astral.sh/uv/getting-started/installation/) - [An Anthropic API key](https://console.anthropic.com/settings/keys) set as the ANTHROPIC_API_KEY environment variable before you start your agent. Being signed in to Claude Code does not count: the sample needs the API key itself **Mastra** - Claude Code, OpenAI Codex, or the GitHub Copilot CLI. Claude Code is the agent these steps are tested with. - [Git](https://git-scm.com/downloads) - [Node.js 22.13 or newer](https://nodejs.org/en/) - [An OpenAI API key](https://platform.openai.com/api-keys) set as the OPENAI_API_KEY environment variable before you start your agent 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 Code** **macOS/Linux** ```bash claude plugin marketplace add diagridio/catalyst-ai && claude plugin install catalyst-ai@diagrid ``` **Windows** ```powershell 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. **Codex** **macOS/Linux** ```bash npx skills add diagridio/catalyst-ai --agent codex --skill '*' --yes && codex mcp add catalyst --url https://mcp.cloud.r1.diagrid.io/mcp --oauth-client-id codex ``` **Windows** ```powershell npx skills add diagridio/catalyst-ai --agent codex --skill '*' --yes codex mcp add catalyst --url https://mcp.cloud.r1.diagrid.io/mcp --oauth-client-id codex ``` This installs the skills into `.agents/skills/` in the current project, and adds the Catalyst MCP server. **Copilot CLI** **macOS/Linux** ```bash npx skills add diagridio/catalyst-ai --agent github-copilot --skill '*' --yes && copilot mcp add --transport http catalyst https://mcp.cloud.r1.diagrid.io/mcp ``` **Windows** ```powershell npx skills add diagridio/catalyst-ai --agent github-copilot --skill '*' --yes copilot mcp add --transport http catalyst https://mcp.cloud.r1.diagrid.io/mcp ``` This installs the skills into `.agents/skills/` in the current project, and adds the Catalyst MCP server. Then open `~/.copilot/mcp-config.json` and add `"oauthClientId": "copilot-cli"` to the `catalyst` entry, so Copilot signs in with its registered client ID: ```json { "mcpServers": { "catalyst": { "type": "http", "url": "https://mcp.cloud.r1.diagrid.io/mcp", "oauthClientId": "copilot-cli", "tools": ["*"] } } } ``` ## 3. Sign in Authenticate once: **Claude Code** Run `/mcp`, choose `plugin:catalyst-ai:catalyst`, and choose **Authenticate**. **Codex** ```bash codex mcp login catalyst ``` **Copilot CLI** Run `/mcp`, choose `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](https://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. **CrewAI** ```text I'm new to Diagrid Catalyst. Show me a durable CrewAI agent that survives a crash, using the Catalyst MCP tools for everything in Catalyst, and your shell for git and running the app. Use the CrewAI 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. `` 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 in Catalyst](https://catalyst.diagrid.io/workflows/venue-scout/?project=). Put the plain URL on the line after it as well, also outside backticks, in case my terminal does not render links. 1. Before anything else, check that `OPENAI_API_KEY` is set as an environment variable in your shell, without printing its value, for example with `[ -n "$OPENAI_API_KEY" ]`. This sample calls a hosted model. If it is not set, stop here and change nothing: tell me to set it in my terminal, restart you from that terminal and paste this prompt again, and wait. Never ask me to paste the key into the chat, and never write it to a file. 2. Call `catalyst_whoami` and tell me which org I'm signed in to. If that fails, help me sign in. 3. 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. 4. Clone https://github.com/diagridio/catalyst-quickstarts and take `agents/crewai`. With `catalyst_apply`, make sure agent `venue-scout` exists in project ``. Catalyst provides its state, pub/sub and registry, so apply only the agent itself. 5. 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 and `OPENAI_API_KEY` taken from the environment. 6. Start a run with `POST http://localhost:8001/crash/run` and the body `{"id":"gala-42","prompt":"Find a venue in Austin for a company gala","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. 7. 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. 8. Explain in at most three sentences why it survived, then offer one next step and wait for my pick. ``` **LangGraph** ```text 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. `` 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 in Catalyst](https://catalyst.diagrid.io/workflows/schedule-planner/?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 ``. 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. ``` **Strands** ```text I'm new to Diagrid Catalyst. Show me a durable Strands agent that survives a crash, using the Catalyst MCP tools for everything in Catalyst, and your shell for git and running the app. Use the Strands 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. `` 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 in Catalyst](https://catalyst.diagrid.io/workflows/budget-planner/?project=). Put the plain URL on the line after it as well, also outside backticks, in case my terminal does not render links. 1. Before anything else, check that `OPENAI_API_KEY` is set as an environment variable in your shell, without printing its value, for example with `[ -n "$OPENAI_API_KEY" ]`. This sample calls a hosted model. If it is not set, stop here and change nothing: tell me to set it in my terminal, restart you from that terminal and paste this prompt again, and wait. Never ask me to paste the key into the chat, and never write it to a file. 2. Call `catalyst_whoami` and tell me which org I'm signed in to. If that fails, help me sign in. 3. 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. 4. Clone https://github.com/diagridio/catalyst-quickstarts and take `agents/strands`. With `catalyst_apply`, make sure agent `budget-planner` exists in project ``. Catalyst provides its state, pub/sub and registry, so apply only the agent itself. 5. 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 and `OPENAI_API_KEY` taken from the environment. 6. Start a run with `POST http://localhost:8001/crash/run` and the body `{"id":"retreat-42","prompt":"Calculate a budget for a corporate retreat with venue, catering, and entertainment","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. 7. 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. 8. Explain in at most three sentences why it survived, then offer one next step and wait for my pick. ``` **Microsoft Agent Framework** ```text I'm new to Diagrid Catalyst. Show me a durable Microsoft Agent Framework 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 Microsoft Agent Framework 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. `` 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 in Catalyst](https://catalyst.diagrid.io/workflows/event-planner/?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/microsoft-dotnet`. With `catalyst_apply`, make sure agent `event-planner` exists in 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 `dotnet run --urls http://localhost:5050` on port 5050 in the background with the `.env` loaded. 5. Start a run with `POST http://localhost:5050/crash/run` and the body `{"id":"gala-42","prompt":"Find a venue in Austin for a company gala","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. ``` **Spring AI** ```text I'm new to Diagrid Catalyst. Show me a durable Spring AI 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 Spring AI 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. `` 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 in Catalyst](https://catalyst.diagrid.io/workflows/spring-ai-crash-recovery/?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/spring-ai/crash-recovery`. With `catalyst_apply`, make sure agent `spring-ai-crash-recovery` exists in 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 `mvn spring-boot:run` on port 8080 in the background with the `.env` loaded. 5. Start a run with `POST http://localhost:8080/crash/run` and the body `{"id":"trip-42","reference":"ABC123","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. ``` **Google ADK** ```text I'm new to Diagrid Catalyst. Show me a durable Google ADK agent that survives a crash, using the Catalyst MCP tools for everything in Catalyst, and your shell for git and running the app. Use the Google ADK 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. `` 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 in Catalyst](https://catalyst.diagrid.io/workflows/entertainment-planner/?project=). Put the plain URL on the line after it as well, also outside backticks, in case my terminal does not render links. 1. Before anything else, check that `OPENAI_API_KEY` is set as an environment variable in your shell, without printing its value, for example with `[ -n "$OPENAI_API_KEY" ]`. This sample calls a hosted model. If it is not set, stop here and change nothing: tell me to set it in my terminal, restart you from that terminal and paste this prompt again, and wait. Never ask me to paste the key into the chat, and never write it to a file. 2. Call `catalyst_whoami` and tell me which org I'm signed in to. If that fails, help me sign in. 3. 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. 4. Clone https://github.com/diagridio/catalyst-quickstarts and take `agents/adk`. With `catalyst_apply`, make sure agent `entertainment-planner` exists in project ``. Catalyst provides its state, pub/sub and registry, so apply only the agent itself. 5. 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 and `OPENAI_API_KEY` taken from the environment. 6. Start a run with `POST http://localhost:8001/crash/run` and the body `{"id":"party-42","prompt":"Find entertainment for a corporate holiday party","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. 7. 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. 8. Explain in at most three sentences why it survived, then offer one next step and wait for my pick. ``` **OpenAI Agents** ```text I'm new to Diagrid Catalyst. Show me a durable OpenAI Agents agent that survives a crash, using the Catalyst MCP tools for everything in Catalyst, and your shell for git and running the app. Use the OpenAI Agents 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. `` 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 in Catalyst](https://catalyst.diagrid.io/workflows/catering-coordinator/?project=). Put the plain URL on the line after it as well, also outside backticks, in case my terminal does not render links. 1. Before anything else, check that `OPENAI_API_KEY` is set as an environment variable in your shell, without printing its value, for example with `[ -n "$OPENAI_API_KEY" ]`. This sample calls a hosted model. If it is not set, stop here and change nothing: tell me to set it in my terminal, restart you from that terminal and paste this prompt again, and wait. Never ask me to paste the key into the chat, and never write it to a file. 2. Call `catalyst_whoami` and tell me which org I'm signed in to. If that fails, help me sign in. 3. 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. 4. Clone https://github.com/diagridio/catalyst-quickstarts and take `agents/openai-agents`. With `catalyst_apply`, make sure agent `catering-coordinator` exists in project ``. Catalyst provides its state, pub/sub and registry, so apply only the agent itself. 5. 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 and `OPENAI_API_KEY` taken from the environment. 6. Start a run with `POST http://localhost:8001/crash/run` and the body `{"id":"gala-42","prompt":"Find catering for a corporate gala","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. 7. 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. 8. Explain in at most three sentences why it survived, then offer one next step and wait for my pick. ``` **Pydantic AI** ```text I'm new to Diagrid Catalyst. Show me a durable Pydantic AI agent that survives a crash, using the Catalyst MCP tools for everything in Catalyst, and your shell for git and running the app. Use the Pydantic AI 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. `` 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 in Catalyst](https://catalyst.diagrid.io/workflows/decoration-planner/?project=). Put the plain URL on the line after it as well, also outside backticks, in case my terminal does not render links. 1. Before anything else, check that `OPENAI_API_KEY` is set as an environment variable in your shell, without printing its value, for example with `[ -n "$OPENAI_API_KEY" ]`. This sample calls a hosted model. If it is not set, stop here and change nothing: tell me to set it in my terminal, restart you from that terminal and paste this prompt again, and wait. Never ask me to paste the key into the chat, and never write it to a file. 2. Call `catalyst_whoami` and tell me which org I'm signed in to. If that fails, help me sign in. 3. 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. 4. Clone https://github.com/diagridio/catalyst-quickstarts and take `agents/pydantic-ai`. With `catalyst_apply`, make sure agent `decoration-planner` exists in project ``. Catalyst provides its state, pub/sub and registry, so apply only the agent itself. 5. 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 and `OPENAI_API_KEY` taken from the environment. 6. Start a run with `POST http://localhost:8001/crash/run` and the body `{"id":"gala-42","prompt":"Find decorations for a garden wedding theme","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. 7. 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. 8. Explain in at most three sentences why it survived, then offer one next step and wait for my pick. ``` **Deep Agents** ```text I'm new to Diagrid Catalyst. Show me a durable Deep Agents agent that survives a crash, using the Catalyst MCP tools for everything in Catalyst, and your shell for git and running the app. Use the Deep Agents 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. `` 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 in Catalyst](https://catalyst.diagrid.io/workflows/transportation-planner/?project=). Put the plain URL on the line after it as well, also outside backticks, in case my terminal does not render links. 1. Before anything else, check that `OPENAI_API_KEY` is set as an environment variable in your shell, without printing its value, for example with `[ -n "$OPENAI_API_KEY" ]`. This sample calls a hosted model. If it is not set, stop here and change nothing: tell me to set it in my terminal, restart you from that terminal and paste this prompt again, and wait. Never ask me to paste the key into the chat, and never write it to a file. 2. Call `catalyst_whoami` and tell me which org I'm signed in to. If that fails, help me sign in. 3. 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. 4. Clone https://github.com/diagridio/catalyst-quickstarts and take `agents/deepagents`. With `catalyst_apply`, make sure agent `transportation-planner` exists in project ``. Catalyst provides its state, pub/sub and registry, so apply only the agent itself. 5. 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 and `OPENAI_API_KEY` taken from the environment. 6. Start a run with `POST http://localhost:8001/crash/run` and the body `{"id":"gala-42","prompt":"Find transportation for a corporate gala","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. 7. 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. 8. Explain in at most three sentences why it survived, then offer one next step and wait for my pick. ``` **Claude Agents** ```text I'm new to Diagrid Catalyst. Show me a durable Claude Agents agent that survives a crash, using the Catalyst MCP tools for everything in Catalyst, and your shell for git and running the app. Use the Claude Agents 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. `` 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 in Catalyst](https://catalyst.diagrid.io/workflows/photography-planner/?project=). Put the plain URL on the line after it as well, also outside backticks, in case my terminal does not render links. 1. Before anything else, check that `ANTHROPIC_API_KEY` is set as an environment variable in your shell, without printing its value, for example with `[ -n "$ANTHROPIC_API_KEY" ]`. This sample calls a hosted model. Being signed in to Claude Code does not count: the sample needs the API key itself. If it is not set, stop here and change nothing: tell me to set it in my terminal, restart you from that terminal and paste this prompt again, and wait. Never ask me to paste the key into the chat, and never write it to a file. 2. Call `catalyst_whoami` and tell me which org I'm signed in to. If that fails, help me sign in. 3. 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. 4. Clone https://github.com/diagridio/catalyst-quickstarts and take `agents/claude-agents`. With `catalyst_apply`, make sure agent `photography-planner` exists in project ``. Catalyst provides its state, pub/sub and registry, so apply only the agent itself. 5. 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 and `ANTHROPIC_API_KEY` taken from the environment. 6. Start a run with `POST http://localhost:8001/crash/run` and the body `{"id":"gala-42","prompt":"Find photography for a corporate gala","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. 7. 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. 8. Explain in at most three sentences why it survived, then offer one next step and wait for my pick. ``` **Mastra** ```text I'm new to Diagrid Catalyst. Show me a durable Mastra agent that survives a crash, using the Catalyst MCP tools for everything in Catalyst, and your shell for git and running the app. Use the Mastra 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. `` 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 in Catalyst](https://catalyst.diagrid.io/workflows/sre-agent/?project=). Put the plain URL on the line after it as well, also outside backticks, in case my terminal does not render links. 1. Before anything else, check that `OPENAI_API_KEY` is set as an environment variable in your shell, without printing its value, for example with `[ -n "$OPENAI_API_KEY" ]`. This sample calls a hosted model. If it is not set, stop here and change nothing: tell me to set it in my terminal, restart you from that terminal and paste this prompt again, and wait. Never ask me to paste the key into the chat, and never write it to a file. 2. Call `catalyst_whoami` and tell me which org I'm signed in to. If that fails, help me sign in. 3. 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. 4. Clone https://github.com/diagridio/catalyst-quickstarts and take `agents/mastra`. With `catalyst_apply`, make sure agent `sre-agent` exists in project ``. Catalyst provides its state, pub/sub and registry, so apply only the agent itself. 5. Get its connection with `catalyst_get_connection`, add the values to the `.env` in the sample folder (gitignored), and start `npm install && npm run crash-test` on port 8001 in the background with the `.env` loaded and `OPENAI_API_KEY` taken from the environment. 6. Start a run with `POST http://localhost:8001/crash/run` and the body `{"id":"inc-4471","prompt":"What is the status of incident INC-4471?","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. 7. 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. 8. 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: ```text 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)](https://docs.diagrid.io/getting-started/quickstarts/ai-agents) — Run the same agent with the Diagrid CLI, step by step. - [Build with an AI coding agent](https://docs.diagrid.io/develop/local-development/ai-coding-agent) — Every skill in the plugin, and what your agent can change. - [AI agents](https://docs.diagrid.io/concepts/ai-agents) — How durable agents work on Catalyst.