Add an Agent Step

An agent step gives a task to an AI agent. Use an agent step when the work needs judgment, such as a review or an investigation. Use a run step when one fixed command does the work.

To make an agent step, add a prompt to a step. The prompt is the text that tells the agent what to do.

The agent works in the same place as the other steps of the job:

• The agent runs on the same runner.
• The agent reads and changes the same copy of the repository.

This guide uses one example. In the example, an agent writes a summary of a repository. For other work, such as a review, a triage, or a fix, keep the step and change only the prompt.

Add the agent stepCopy Anchor Link

Create .shipfox/workflows/summarize-repository.yml. This is a complete workflow. It uses the workspace's default harness, provider, and model:

# yaml-language-server: $schema=https://www.shipfox.io/docs/workflow.schema.json
name: Summarize the repository
runner: shipfox

triggers:
  manual:
    source: manual

jobs:
  summarize:
    steps:
      - prompt: |
          Read this repository and summarize its purpose in three sentences.
          Name the main entry point and one command a contributor should know.
          Do not change any files.

To reuse this step in your own workflow, change only the prompt. A good prompt has three parts:

• The task. State what the agent must find, decide, or change.
• The shape of the answer. Specify a form that is easy to check: three sentences or one named command.
• The limits. Say what the agent must not do, such as changing files.

Commit and push the file to the project's default branch. Wait for Summarize the repository to appear in the project's Workflows tab.

Split a prompt into partsCopy Anchor Link

Several steps can use the same text in their prompts. To share that text, write prompt as a list. Each item of the list is one part.

Shipfox joins the parts into one prompt. It puts one blank line between two parts. It also removes the line breaks at the end of each part.

A YAML anchor gives a name to one part. Another step can then use that part again by its name. The example below is a complete workflow. The first step gives the name &rules to the shared rules. The second step uses the rules again with *rules:

# yaml-language-server: $schema=https://www.shipfox.io/docs/workflow.schema.json
name: Review the repository
runner: shipfox

triggers:
  manual:
    source: manual

jobs:
  review:
    steps:
      - prompt:
          - Read this repository and list three risks in its error handling.
          - &rules |
            Answer in a numbered list.
            Name the file for each item.
            Do not change any files.
      - prompt:
          - Read this repository and list three gaps in its tests.
          - *rules

Keep these rules in mind when you write your own parts:

• A part is a string or a file. A list cannot contain another list, so an anchor must hold one part.
• A ${{ }} expression must start and end in the same part.
• A prompt has a maximum number of parts. See Workflow document.

Keep a prompt in a fileCopy Anchor Link

A part can also come from a file in the repository. Use a file when the text is long, or when several workflows use the same text. In the prompt, write a file reference in place of the text. This fragment changes the second step of the example above:

      - prompt:
          - Read this repository and list three gaps in its tests.
          - file: ./.shipfox/prompts/review-rules.md

The path starts with ./ and is relative to the root of the repository. The whole file is the part. A file cannot include another file.

A prompt file is a part of the workflow. Shipfox reads the file from the repository, not from the files of the job. The table below shows which commit Shipfox reads. If a step changes the file during a run, the agent does not get the change.

This rule has three results:

• A pull request that edits a prompt file does not change the runs that the pull request starts. Those runs use the text on the default branch until the pull request merges. The workflow YAML behaves the same way.
• A commit to the default branch that changes only a prompt file updates the workflow.
• To test an edit to a prompt file, push your branch, then start a dev run from that branch. See Run a workflow before you push.

If a prompt file is missing, empty, not UTF-8 text, or too large, the sync fails with prompt-file-invalid. The error names the step and the file. The workflow keeps its previous version. See Find why a workflow did not sync.

Adapt the step to your taskCopy Anchor Link

Start from the example and change one thing at a time:

Verify the agent resultCopy Anchor Link

Select Run and open the new run.

1. Confirm that the job starts on the expected runner.
2. Open the agent step and follow its messages and tool activity.
3. Check that the final response has the shape the prompt asked for. In the example, it has three sentences.
4. Check the answer against the repository. In the example, it names a real entry point and a real command.

The result should match the code in the commit that started the run.

If the step cannot resolve a model or provider, check Set the default agent model.