---
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://app.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://app.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?

| Pattern | How it works | Best when |
|---|---|---|
| **MCP** | Point the framework's MCP client at `https://app.ballet.dev/mcp`; Ballet's tools (`list_playbooks`, `run_playbook`, `get_run`, …) are imported automatically | You want the agent to discover and manage playbooks, or you're already using MCP |
| **REST custom tool** | Define one tool in your framework that POSTs to the execute endpoint | 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).

## 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)