Workflow run tools

Overview

These tools cover a workflow run from start to finish:

• Start a run with create_workflow_run.
• Follow it with get_workflow_run. Use search_workflow_runs to find runs or browse their history.
• Act on it while it's in progress with control_workflow_run: approve, reject, revoke or cancel.
• Inspect the result with get_workflow_run_logs, get_workflow_outputs, list_workflow_artifacts and get_workflow_artifact.

Reading a run's status, logs, outputs and artifacts is read-only. Starting and controlling runs are write tools, see Availability.

All tools work for standalone workflows and for workflows inside a stack. The assistant works out which kind it is from the id.

get_workflow_run

Reads one workflow run's current status and details directly from the platform. Use it to follow a run after it starts: the search index used by search_workflow_runs can lag behind the run's actual state.

Input	Description
Run (required)	The full run id returned when the run starts, by search_workflow_runs, or in a stack run's child workflow list.

The response includes the status, run details and a statusView that tells the assistant whether the run has finished, succeeded or needs human action. APPROVAL_REQUIRED and PAUSED mean the run is waiting, not finished. The assistant should tell you what is blocking it rather than approve it automatically.

This also works for a run started on just one workflow inside a stack. To follow a whole stack deployment, use get_stack_run.

Example prompts

"Has the payments-api run finished? Check its current status."

get_workflow_run_logs

Fetches the console output of a single run: the plan, apply or destroy logs.

caution

Log text is returned without an additional redaction pass. Credentials or other sensitive values printed by a workflow can enter the conversation when these logs are fetched.

Input	Description
Run (required)	The run, as found with search_workflow_runs.
Errors only	Return only the error lines. The fastest way to diagnose a failed run.
Maximum lines	Default 500, maximum 5,000.
From the end	By default the last lines are returned, since that's usually where a failure shows up. Can be switched to return the first lines instead.

When the platform provides one, the response includes a link to the complete log file, so nothing is lost when the output is trimmed.

Example prompts

"Why did the last run of payments-api fail?"

"Show me the first 200 lines of the plan for run nfgym507nuzy."

get_workflow_outputs

Fetches the outputs a workflow published, such as Terraform or OpenTofu outputs like VPC ids, endpoints and ARNs. It works at three levels:

• one standalone workflow
• one workflow inside a stack
• a whole stack, which returns the outputs of every workflow in it

Outputs marked as sensitive are always redacted by the tool before they reach your assistant. The response also links to the outputs file, usually the platform's masked copy with sensitive values hidden. If the platform served the unmasked file instead, the response says so.

Input	Description
Workflow or stack (required)	As found with the search tools.
Maximum outputs	Per workflow. Default 100, maximum 1,000. A whole stack covers at most 100 of its workflows.

Example prompts

"What's the load balancer DNS name from the web-frontend workflow?"

"List all outputs of the data-platform stack."

list_workflow_artifacts

Lists the files a workflow's runs saved from their workspace, such as plan output, generated configuration files and tfstate.json. It returns names and folders only, never the file contents.

Input	Description
Workflow (required)	As found with search_workflows.
Folder	Only list files under this folder.
Maximum files	Default 200, maximum 1,000. Longer lists come in pages.

Example prompts

"What artifacts did the eks-cluster workflow produce?"

get_workflow_artifact

Returns a temporary download link, valid for about 60 minutes, for one artifact file.

The tool never reads the file into the conversation. Artifact files, especially Terraform state, plans and .tfvars files, often contain secrets in plain text. Instead you get a link to open in your own browser session.

For the workflow's outputs file, the tool doesn't give a link to the unmasked copy. Use get_workflow_outputs instead.

Input	Description
Workflow (required)	As found with search_workflows.
File (required)	The file name exactly as list_workflow_artifacts returned it.

Example prompts

"Give me a download link for the Terraform state of eks-cluster."

create_workflow_run

Runs an existing workflow, the same as clicking Run in the dashboard. This executes infrastructure code against the workflow's cloud connector.

Choosing the action

There is no default action. Your assistant must ask you which one to run, every time, and name the workflow it's about to run.

Action	What it does
plan	Preview the changes. Nothing is changed. A good place to start.
plan-destroy	Preview a teardown. Nothing is changed.
plan-without-policy	Preview the changes without evaluating policies.
refresh	Update the state from real infrastructure. No changes are applied.
apply	Apply the changes for real.
destroy	Tear down every resource the workflow manages. Irreversible, and requires an extra explicit confirmation.
none	Required for Custom workflows, which run their step pipeline instead of a Terraform action. Terraform actions are refused on Custom workflows, and none is refused on Terraform and OpenTofu workflows.

Options for this run

You can change a few things for this run only. The workflow's stored settings stay as they are.

Option	Description
Input values	Override template or variable inputs. Only the values you name change; the rest keep their stored values.
Environment variables	Add or override variables by name. Variables you don't mention are kept.
Context tags	Labels for this run. Runs don't inherit context tags from the workflow.
CPU and memory	One-off container sizing, for example to retry a run that ran out of memory.
Workflow chaining	Turn off chaining to other workflows for this run. Notifications still go out.
Schedule	Start the run at a future time instead of now.
Deactivate after destroy	With destroy or plan-destroy: after a successful destroy, mark the workflow inactive to free an active-workflow slot. Standalone Terraform and OpenTofu workflows only.

Everything else, including the connector, runner, approvals and Terraform settings, comes from the workflow. Those can only be changed with update_workflow, so a single run can't bypass the workflow's approval gate.

After the run starts

The tool returns as soon as the platform accepts the run. It doesn't wait for the run to finish. The response tells you whether the run started now, was queued behind a run already in progress, or was scheduled. Where available, it includes a link to the run in the dashboard.

Your assistant then checks the run's status until it completes, fails or is cancelled. The response includes polling instructions, which may use the search index; get_workflow_run reads directly from the platform when current status matters. If the run stops to wait for approval, the assistant tells you rather than approving it.

The tool never creates a workflow. If the name doesn't match an existing workflow, you get an error naming it.

Running an inactive workflow reactivates it, which uses one of your plan's active-workflow slots. The response warns you when this happens.

Example prompts

"Run a plan on the staging-vpc workflow."

"Apply payments-api in the production group, with instance_count set to 4 for this run only."

"Destroy the demo-sandbox workflow and deactivate it afterwards."

control_workflow_run

Acts on a run that's already in progress. This changes what real infrastructure does: approving a run releases it to apply.

The assistant must ask you which action to take, and show you which run it is and what will happen when it resumes. It must never approve a run on its own just because the run was waiting.

Action	What it does	Confirmation
approve	Record your approval. Once all required approvals are in, the run resumes and applies.	Required
reject	Refuse the approval. The run is cancelled; start a new run to try again.	Required
revoke	Withdraw an approval you gave earlier. The run keeps waiting. The only action that can be undone.	Not needed
cancel	Stop a run that's queued, scheduled, pending or running.	Required

Input	Description
Run (required)	As found with search_workflow_runs.
Action (required)	One of the actions above.
Message	A comment recorded with your decision: up to 255 characters for approve or reject, up to 500 for revoke.
Specific approvals	Answer only some of the pending approvals, for example one policy gate, up to 50 per call. By default the tool answers the approvals assigned to you. If the run has several gates with different approvers, it answers only your own gates.

Good to know

• You can only approve or reject if you're one of the run's approvers. The tool refuses otherwise.
• If other approvers are still needed after yours, the response tells you who the run is waiting on.
• Cancelling a run that's waiting for approval is carried out as a rejection. It's recorded against you, with your message as the reason, so you must be allowed to answer that approval. The response reports both the action you asked for and the one performed.
• A run that's already executing moves to CANCELLING first and stops part-way. This can leave partially created infrastructure.
• A paused run can't be cancelled through the API.
• Runs waiting on an external approval system can't be approved or rejected with this tool.

Example prompts

"Which runs are waiting for my approval? Show me what the payments-api run will change."

"Approve the pending run of payments-api with the comment 'Reviewed plan, LGTM'."

"Cancel the queued run of staging-vpc."