Loading…
Introduction
TL;DR: Build on Ballet programmatically. Run playbooks from your own apps and agents over the REST API or Ballet's MCP endpoint, stream live run events, wake suspended runs, and connect playbooks out to external systems and SDKs. Start with an API token, call a playbook, then wire it into an agent framework like the Vercel AI SDK, LangChain, Mastra, or Google ADK.
Who this is for
Developers integrating Ballet with custom apps, backend services, CI/CD, or agent frameworks — in either direction.
What can I build?
Ballet integrations go two ways:
- Call into Ballet — external apps and agents invoke playbooks as tools. Use the REST API for direct control or the MCP endpoint to expose playbooks (and agents, skills, tools) to any MCP-aware client.
- Connect Ballet out — playbooks reach external systems and SDKs from inside steps, via MCP connectors, HTTP steps, and custom tools.
Where do I start?
- Create a workspace API token in Settings → API tokens.
- Read Foundations to run a playbook over REST and stream its events.
- For durable human-in-the-loop, see Wake a suspended run.
- To wire Ballet into an agent, see Agent frameworks.
- To let playbooks reach your systems, see Connecting to external systems.
How is this organized?
- Foundations — authentication, REST API, streaming run events, wake suspended runs, webhooks, and the MCP endpoint.
- Agent frameworks — call Ballet playbooks as tools from Vercel AI SDK, LangChain, Mastra, and Google ADK.
- Connecting to external systems — MCP connectors, HTTP and custom tools, and secrets in steps.