---
title: "How do I use Ballet playbooks in an agent framework?"
description: "TL;DR: Expose your Ballet playbooks as tools inside any agent framework two ways. The MCP path points the framework's MCP client at https://api.ballet.dev/mcp and auto-imports tools like runplaybook and getrun. The REST path defines a single custom tool that calls POST /api/playbooks/:id/execute. Both authenticate with a workspace API token."
canonical_url: "https://docs.ballet.dev/articles/how-do-i-use-ballet-playbooks-in-an-agent-framework-q3PWTx18lY"
md_url: "https://docs.ballet.dev/articles/how-do-i-use-ballet-playbooks-in-an-agent-framework-q3PWTx18lY.md"
---
# How do I use Ballet playbooks in an agent framework?

**TL;DR:** Expose your Ballet playbooks as tools inside any agent framework two ways. The MCP path points the framework's MCP client at `https://api.ballet.dev/mcp` and auto-imports tools like `run_playbook` and `get_run`. The REST path defines a single custom tool that calls `POST /api/playbooks/:id/execute`. Both authenticate with a workspace API token.

## Who this is for

Developers building agents that should be able to run Ballet playbooks as part of their reasoning loop.

## What are the two integration patterns?

**MCP** — point the framework's MCP client at `https://api.ballet.dev/mcp` and Ballet's tools (`list_playbooks`, `run_playbook`, `get_run`, and the rest) are imported automatically. Best when you want the agent to discover and manage playbooks, or you are already using MCP.

**REST custom tool** — define one tool in your framework that POSTs to the execute endpoint. Best when you want to expose exactly one playbook with a tight schema.

Both use the same auth: send a workspace API token as `Authorization: Bearer mt_live_…`. See [authentication](/articles/how-do-i-authenticate-with-the-ballet-api-tWaqCPLyGT). The MCP endpoint also supports browser-based OAuth for interactive clients — see [the MCP endpoint](/articles/how-do-i-connect-to-ballets-mcp-endpoint-1ydPKBzHZm).

Both surfaces are served from `api.ballet.dev`. `app.ballet.dev` serves Ballet Studio and will not answer API or MCP requests.

## Which framework are you using?

* [Vercel AI SDK](/articles/how-do-i-call-ballet-playbooks-from-the-vercel-ai-sdk-f2WDKmGWk5) — TypeScript, `createMCPClient` or a `tool()` definition.
* [LangChain / LangGraph](/articles/how-do-i-call-ballet-playbooks-from-langchain-9oGBp3Ih16) — Python, `MultiServerMCPClient` or a `@tool`.
* [Mastra](/articles/how-do-i-call-ballet-playbooks-from-mastra-mUk4Q7k4Lw) — TypeScript, `MCPClient` or `createTool`.
* [Google ADK](/articles/how-do-i-call-ballet-playbooks-from-google-adk-jxG6oinH4u) — Python, `McpToolset` or a `FunctionTool`.
* [Pydantic AI](/articles/how-do-i-call-ballet-playbooks-from-pydantic-ai-K5Tei4NZRG) — Python, `MCPServerStreamableHTTP` toolset or a function tool.

## Tips that apply everywhere

* Start with the MCP path to let the agent see all playbooks, then narrow with a tool filter once you know which it needs.
* For the REST path, give the tool a clear name and description so the model knows when to run the playbook.
* Treat the playbook's `run_stop.output` as the tool result; surface `success` so the agent can handle failures.

## Related articles

* [The MCP endpoint](/articles/how-do-i-connect-to-ballets-mcp-endpoint-1ydPKBzHZm)
* [Run playbooks over the REST API](/articles/how-do-i-run-a-playbook-over-the-rest-api-KQIz0apagm)
* [How do I authenticate with the Ballet API?](/articles/how-do-i-authenticate-with-the-ballet-api-tWaqCPLyGT)