agent_persona_run
Run one-shot Agent Stage personas asynchronously to produce a saved, applyable diff proposal over existing project material. Start returns a job_id; poll with job_get, finalize the completed job to mint a proposal_id, then apply if desired.
When to use
Use when the caller wants one or more BeatBandit personas to propose concrete, applyable project changes in one pass.
Use when the requested outcome is a saved `proposal_id` that can be inspected and later applied.
Use `phase=finalize` after `job_get` reports completion to mint the saved proposal.
Use `phase=apply` to commit a previously minted persona proposal.
Check `has_actionable_changes` on `finalize`; if false, there is no applyable change to commit.
When not to use
Do not use for ongoing Story Mentor conversations.
Do not use for open-ended critique, scored coverage, writers-room notes, or general recommendations; use `story_review_run` with `analysis_wizard` or `room_review` instead.
Do not use for direct low-level card or screenplay edits.
Do not use to fill one empty treatment card or other missing structured stage content; use `story_development_run` for the relevant builder wizard or `story_mutate` for exact known card updates.
Examples
“Ask the continuity and character personas to propose concrete project changes, poll the returned job_id, then finalize to inspect the proposal_id.”
“Apply a saved persona proposal.”
Anti-examples
- Start a Story Mentor session.
- Give me notes on how to improve this screenplay — use `story_review_run` (`analysis_wizard` or `room_review`) instead.
- Generate a brand-new outline from a raw idea.
- Fill card 50.10.10 with Act 1 treatment prose.
Backend capabilities
Linked resources
Tool calls may return resource_links pointing at these resource families.
Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"phase",
"project_id"
],
"properties": {
"phase": {
"type": "string",
"enum": [
"start",
"finalize",
"apply"
]
},
"project_id": {
"type": "integer"
},
"roles": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"writer",
"reviewer",
"character",
"continuity",
"planner",
"producer",
"dialogue",
"theme",
"format",
"clarity"
]
}
},
"direction": {
"type": "string",
"maxLength": 4000
},
"scope": {
"type": "object",
"properties": {
"scene_id": {
"type": "string"
},
"sequence_code": {
"type": "string"
},
"act_code": {
"type": "string"
}
},
"additionalProperties": false
},
"job_id": {
"type": "string"
},
"proposal_id": {
"type": "string"
}
},
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"phase": {
"const": "start"
}
}
},
"then": {
"required": [
"roles"
]
}
},
{
"if": {
"properties": {
"phase": {
"const": "finalize"
}
}
},
"then": {
"required": [
"job_id"
]
}
},
{
"if": {
"properties": {
"phase": {
"const": "apply"
}
}
},
"then": {
"required": [
"proposal_id"
]
}
}
]
}Output schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"phase"
],
"properties": {
"phase": {
"type": "string"
},
"proposal_id": {
"type": "string"
},
"async": {
"type": "boolean"
},
"job_id": {
"type": "string"
},
"status": {
"type": "string"
},
"poll_after_seconds": {
"type": "integer"
},
"has_actionable_changes": {
"type": "boolean"
},
"roles": {
"type": "array",
"items": {
"type": "string"
}
},
"summary": {
"type": "array",
"items": {
"type": "object"
}
},
"updates": {
"type": "array",
"items": {
"type": "object"
}
},
"creates": {
"type": "array",
"items": {
"type": "object"
}
},
"notes_patch": {
"type": "object"
},
"screenplay_ops": {
"type": "object"
},
"applied_summary": {
"type": "object"
},
"snapshot_rev": {
"type": "integer"
},
"credits_charged": {
"type": "number"
},
"credits_skipped_reason": {
"type": "string"
},
"resource_links": {
"type": "array",
"items": {
"type": "object"
}
}
},
"additionalProperties": true
}