Running a Saved Playbook
Use play.submit for a playbook that is already installed on the MCP server's
machine. Use the playbook skill instead when the file itself needs authoring or editing.
Required call sequence
Ask for the catalog in its own call and confirm
play.submitis available:mcp__plugin_orchestrate_lion__request(help=true)Ask for the schema with the exact playbook name. A playbook's declared arguments change the schema, so the catalog marks this fingerprint as varying by
playbook:mcp__plugin_orchestrate_lion__request(help={"verb": "play.submit", "playbook": "minimal"})Copy that reply's
schema_fingerprintinto the op as a sibling ofargs:mcp__plugin_orchestrate_lion__request(ops=[ {"op": "play.submit", "args": {"playbook": "minimal", "prompt": "Explain monads with one example."}, "schema_fingerprint": "<fingerprint from the qualified help call>"} ])
Never put schema_fingerprint inside args. It is not read there, so the server refuses the
op as stale. Do not combine help and ops in one call; the server refuses that shape too.
Worked example
This example uses a saved playbook at ~/.lionagi/playbooks/minimal.playbook.yaml. If it is
not already present, create it first:
name: minimal
model: claude
prompt: |
Explain the supplied topic in plain language, with one concrete example.
Run the qualified help and submit calls above, then read the returned run_id:
mcp__plugin_orchestrate_lion__request(ops=[
{"op": "job.status", "args": {"run_id": "<run_id>"}}
])
Repeat job.status until the run is terminal, then retrieve its console tail and artifact list:
mcp__plugin_orchestrate_lion__request(ops=[
{"op": "job.output", "args": {"run_id": "<run_id>"}}
])
The submit response is only a run id, not the playbook's result. job.list finds recent runs;
job.kill stops one by run_id.
Arguments and planning
- Read the qualified help schema for every custom playbook argument. Pass each declared
argument directly inside the op's
args; do not invent another nesting layer. - Set
dry_run: trueinsideargsto plan without executing workers. The dry run is still a background job, so inspect it throughjob.statusandjob.output. - If calling
flow.submitwith aplaybookinstead, use the same qualified-help rule with{"verb": "flow.submit", "playbook": "<same name>"}. - Multiple ops run in order, but one op returning
ok=falsedoes not stop its siblings. Check every op'sokfield instead of trusting the top-level response alone.
Checkout-local alternative
Inside a lionagi checkout with li on PATH:
li play minimal "Explain monads with one example."
Use li play minimal --help to see the playbook's declared flags.