---
title: "Introduction"
description: "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."
canonical_url: "https://docs.ballet.dev/articles/introduction-CTR7cHHV6P"
md_url: "https://docs.ballet.dev/articles/introduction-CTR7cHHV6P.md"
---
# 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?

1. Create a workspace API token in **Settings → API tokens**.
2. Read [Foundations](/articles/developer-foundations-l0vvRnLSoH) to run a playbook over REST and stream its events.
3. For durable human-in-the-loop, see [Wake a suspended run](/articles/how-do-i-wake-a-suspended-run-with-reply-or-resume-EDYuheV1x4).
4. To wire Ballet into an agent, see [Agent frameworks](/articles/how-do-i-use-ballet-playbooks-in-an-agent-framework-q3PWTx18lY).
5. To let playbooks reach your systems, see [Connecting to external systems](/articles/how-do-playbooks-connect-to-external-systems-Jije3yYddT).

![](https://docs.ballet.dev/api/attachments.redirect?id=b41abb8a-fdd5-4f72-86f8-7bb673389bf7 "=3016x1670")

## How is this organized?

* [Foundations](/articles/developer-foundations-l0vvRnLSoH) — authentication, REST API, streaming run events, wake suspended runs, webhooks, and the MCP endpoint.
* [Agent frameworks](/articles/how-do-i-use-ballet-playbooks-in-an-agent-framework-q3PWTx18lY) — call Ballet playbooks as tools from Vercel AI SDK, LangChain, Mastra, and Google ADK.
* [Connecting to external systems](/articles/how-do-playbooks-connect-to-external-systems-Jije3yYddT) — MCP connectors, HTTP and custom tools, and secrets in steps.

## Related articles

* [How do I create and use API tokens?](/articles/how-do-i-create-and-use-api-tokens-Wp34UyMlMH)
* [How do I wake a suspended run with reply or resume?](/articles/how-do-i-wake-a-suspended-run-with-reply-or-resume-EDYuheV1x4)
* [How do I connect an MCP server?](/articles/how-do-i-connect-an-mcp-server-RtBQhNBIoy)
* [What triggers can start a playbook?](/articles/what-triggers-can-start-a-playbook-manual-schedule-webhook-P4mdwPZDGg)
* [How do I run a playbook?](/articles/how-do-i-run-a-playbook-dChtouCzok)