Agent step

An agent step runs an application agent with a prompt. Use agents for investigation, triage, and proposed fixes.

Shape

- id: investigate
  type: agent
  agent: developer
  prompt: |
    CI failed for {{workflow.name}} on {{head_branch}}.
    Failed jobs: {{failed_jobs}}
    Run: {{run.url}}

    Explore the checkout first: find the workflow under .github/workflows/,
    read the failing job definition, then inspect the code it exercises.
  repository: "{{repo.full_name}}"
  branch: "{{head_branch}}"
  onFailure:
    - type: notify
      title: Agent could not finish
      body: See run for details.

Field	Required	Description
`agent`	yes	Agent alias (preferred, e.g. `developer`), display name, or id. Aliases are stable and shown in Settings → Agents.
`prompt`	yes	Template string (`{{variables}}` allowed)
`repository`	no	Interpolated repo hint (`owner/name`). Prefer event vars like `{{repo.full_name}}`.
`branch`	no	Interpolated checkout branch (for example `{{head_branch}}`)
`onFailure`	no	Steps if the agent step fails

Always set repository and branch from the trigger when those fields exist so the agent gets a real checkout. Instruct the agent to search and read repo files (CI definitions, package scripts, related source) before proposing a fix.

Outcomes

Agent steps record summary and outcome for later variables when the agent marks a task complete (steps.<id>.summary, steps.<id>.outcome). Link to the conversation from the run detail when a thread was created.