How do I use Ballet playbooks in an agent framework?
1min read
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. The MCP endpoint also supports browser-based OAuth for interactive clients — see the MCP endpoint.
Which framework are you using?
- Vercel AI SDK — TypeScript,
createMCPClientor atool()definition. - LangChain / LangGraph — Python,
MultiServerMCPClientor a@tool. - Mastra — TypeScript,
MCPClientorcreateTool. - Google ADK — Python,
McpToolsetor aFunctionTool. - Pydantic AI — Python,
MCPServerStreamableHTTPtoolset 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.outputas the tool result; surfacesuccessso the agent can handle failures.