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. The MCP endpoint also supports browser-based OAuth for interactive clients — see the MCP endpoint.
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 — 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.