Blueprint graph
Write a Blueprint shows how to write a graph, and Blueprints and approvals explains how a task runs it.
Graph fields
blueprints.read returns a version's graph, and blueprints.replace-draft takes one, with these fields:
| Field | What it holds |
|---|---|
description | What the work achieves. Chat uses it to choose a Blueprint. Commit requires it. |
model | Optional. The providerId and modelId that new tasks run on. |
effort | Optional. The effort of model. It needs model. |
requirements | Values that a task needs. |
capabilities | The actions that agent nodes may take. A capability has a name, an operation, and optionally nodes. |
groups | Named groups of nodes. A group has a key, a label, and an optional parent. |
nodes | The steps of the work. A node has a key, a label, a group, and a kind. |
edges | Which node runs after which. An edge has from, to, and when. |
databaseReadOnly | Optional. When true, tasks get only the read-only login of each database. |
A new task runs on model at effort unless it names its own, and a version without model runs on the Project's model selection. blueprints.replace-draft refuses a model that no model account of the Organization runs with MODEL_ACCOUNT_MISSING, an effort that the model does not run at with EFFORT_UNSUPPORTED, and an effort without a model with BLUEPRINT_EFFORT_WITHOUT_MODEL. providers.models lists the models and their efforts, and blueprints.list shows each Blueprint's latest committed model and effort as its defaults.
Nodes, groups, and edges refer to one another by key. An edge's when is succeeded, failed, or completed.
A requirement has a name, a type (string, number, or boolean), a source (dispatch for a value given when the task starts, organization for an Organization variable, issue for the issue the task is linked to, whose id is its string value), and optional. An optional description of at most 200 characters says what to enter, such as "The issue key, such as ENG-482." A form shows it next to the input, and devboxes in Chat words its question for a missing value by it.
| Node kind | Fields | What it runs |
|---|---|---|
agent | instructions, outcomes | The agent until it reports the node complete. The first one also gets the task's instruction. |
command | command | The named Project Command until it exits. Exit code 0 succeeds. |
service | command | The named Project Command in the background. Succeeds once ready passes. |
publish | none | Pushes the agent's commits to the task's branch and opens its pull request. |
review | none | Starts a Review when the task succeeds after reaching this node. |
A task starts from the Session's branch and its unpublished changes. Git-ignored files such as installed dependencies stay behind, and the task's nodes share one workspace. Put a command node that runs the Project's install command before the nodes that need dependencies.
A graph has no cycles, at most one publish node, and at most one review node. The review node has exactly one incoming edge, a succeeded edge from the publish node, and no outgoing edges.
A committed version never changes. A write to it fails with BLUEPRINT_VERSION_COMMITTED. A task fails to start with PROJECT_COMMAND_MISSING when a node names a command that the Project lacks, and with PROJECT_COMMAND_MISMATCH when a service node names a command without a ready check, or a command node names one with it.
Capabilities
| What the agent can do | Operation |
|---|---|
| Edit, close, reopen, or comment on GitHub pull requests, and answer their reviews. | repositories.github-write |
| Read a pull request with its review comments. | repositories.review |
| Read the checks of a pull request. | repositories.checks |
| Read issues in the Project's Linear Team, Jira Project, or GitHub repository. | issues.read |
| Create, update, and comment on those issues. | issues.write |
| Start a Session in the Run's own Project. See the limits below the table. | sessions.dispatch |
| Read a Session of the Organization, with its Runs and their results. | sessions.inspect |
Every agent node's step may use a capability, unless the capability lists the keys of agent nodes in nodes. Then only those steps may use it, for example issues.write only in the step that reports on the issue. A call outside those steps fails with CAPABILITY_NOT_IN_STEP: from another step, from the final check of the work, or from an answer to a person's message that reaches the work between steps. A message answered while a listed step runs may use it. A Review or recheck runs no step, so its capabilities ignore nodes. A key in nodes that names no node fails the write with BLUEPRINT_REFERENCE_MISSING, and one that names a node of another kind fails it with BLUEPRINT_CAPABILITY_INVALID.
The publish node needs publication.commit, which lets it push the Run's commits to the Session's branch and open that branch's pull request. It is a permission, not an operation you invoke. A delegation token or a Chat policy that starts a Blueprint with a publish node must allow publication.commit, and every capability operation of the Blueprint. A Blueprint that binds sessions.dispatch in a Project with a repository needs publication.commit too, because the work it starts can publish under the same permissions.
Work that a Run starts with sessions.dispatch begins from the starting Run's workspace as it was at the call: a taskbox's files, or a repository's changes that the starting Run has not pushed, applied to the new branch. Commits the starting Run already pushed stay on its own branch, and work on a new branch starts from the Project's branch. To build on those commits, name the starting Run's own pull request with pullRequest. Its conversation starts fresh. It has these limits:
- It runs with the starting Run's permissions. Its Blueprint can need only the operations the starting Run holds: the starting Blueprint's capability operations and
publication.commit. Taking a tracker issue throughissueneedsissues.writeamong them. - It can't start work of its own: a Blueprint that binds
sessions.dispatchis refused withTASK_STARTED_WORK_DISPATCH. - It opens its own branch and pull request. To continue the starting Run's own pull request, it names that pull request with
pullRequest: its branch then starts from that pull request's head, and its pull request merges into the starting Run's branch. Any other pull request is refused withTASK_STARTED_WORK_OTHER_PULL_REQUEST.