Workflows: describe the whole agent run in one YAML file

Running the agent is the easy part. The work around it — preparing the environment, creating a branch, committing, opening a pull request, cleaning up afterwards — is different in every project, and it is exactly the part that used to be hardcoded in adapter logic. Workflow mode moves all of it into a single declarative YAML file versioned in your repository, next to the code it operates on.

The adapter then does only one thing well: it loads the workflow, runs the steps in order, and reports every step back to the task timeline. The agent is no longer a special citizen — it is just one step among others, usually the one called “Run agent”.

One file in .agentis/workflows

A workflow is a list of bash steps with shared environment, tokens like [%WORKDIR%] and [%BRANCH%] interpolated from the task context, and per-step conditions. The default.yaml in your repo describes a full task run; project.yaml runs against the whole project without git; named workflows like merge.yaml power followup actions.

version: 1
extends: _base
workflow:
  executor: local
  steps:
    - name: Prepare environment
      run: |
        mkdir -p .agentis/outputs
        test -d .venv && printf 'true' > .agentis/outputs/env-ready || true
      outputs:
        - type: var
          name: ENV_READY
          valueFrom: .agentis/outputs/env-ready
    - name: Create virtualenv
      if: ENV_READY != 'true'
      run: python3.13 -m venv .venv
    - name: Run agent
      run: agentiscode --prompt "$AGENTIS_PROMPT_FILE"
    - name: Create pull request
      if: GITHUB_REPO
      run: gh pr create --base "$BASE_BRANCH" --head "$BRANCH" --fill

Steps talk through outputs, not side effects

Steps communicate with the platform through declared output files. A var output becomes a variable for later if conditions and step environments. An agent_comment output becomes the completion comment on the task. Artifacts, links and session ids ride along the same way — and everything is applied to Agentis in one shot after the run finishes.

• var — workflow variables that drive if conditions, like skipping virtualenv creation when the environment is warm.
• agent_comment — the task completion comment and target status, written by the step that knows the result.
• artifact, url, text — files and links attached to the comment, surviving long after the run.
• session_id — stored on the run so a followup message can resume the same agent session.

Kubernetes Jobs or local processes — same file

Where steps physically run is a one-line decision. The kubernetes executor turns every step into a batch Job with images, volumes and resource limits; the local executor runs the same steps as bash processes on the host. Teams typically develop a workflow locally and switch the executor in production without touching a single step.

Failure is part of the pipeline

Real pipelines fail halfway. A step can declare retries for flaky operations, continueOnError when it is best-effort, or always: true to run even after an earlier step died — that is how cleanup and failure reporting work. An always step sees AGENTIS_WORKFLOW_STATUS and the name of the failed step, so it can post an honest failure comment to the ticket instead of leaving the task silent.

“Outputs of successful steps are applied even when the workflow as a whole fails. The ticket always learns what happened — including the bad news.”

Followups close the loop

The followups section of the workflow defines the action buttons offered in the completion comment — “Git merge”, “Close environment” — and each button simply starts another named workflow. A followup can be conditional on the run’s own outputs: the merge button only appears when the run actually created a pull request. The whole lifecycle, from environment to merged branch, is described in files your team can read, review and version like any other code.