Skip to main content
Shipfox agent steps let you run an AI model as a native workflow step — no glue code, no webhooks. An agent step specifies a model, a prompt, and optionally a thinking level and provider. The step executes inline within the job, the model has full access to the repository, and its output appears in the run log alongside any shell step output.

​
Basic agent step

At a minimum, an agent step requires a prompt. When no model or provider is specified, Shipfox uses the workspace default provider and model (see Model Providers). 
jobs:
  fix:
    steps:
      - name: ask-claude
        model: claude-opus-4-8
        prompt: Read the repository and summarize what it does in three sentences.
The optional name field labels the step in the dashboard. To reference a step from a restart_from gate, give it a key: — keys identify steps; names are display-only.

​
Choosing a model

The model field accepts the model ID used by the provider. The provider field accepts a provider ID (e.g. openai, deepseek). When provider is omitted, Shipfox resolves the model against your workspace default provider. To use a non-default provider, specify both fields: 
- model: gpt-5.5-pro
  provider: openai
  prompt: Review the recent changes for security issues.
Some supported combinations to get you started:
Providerprovider IDExample model
Anthropicanthropicclaude-opus-4-8
OpenAIopenaigpt-5.5-pro
DeepSeekdeepseekdeepseek-v4-pro
xAIxaigrok-4.3
Google AI Studiogooglegemini-3.1-pro-preview
See the Model Providers guide for the complete list of supported providers and their model IDs.

​
Thinking level

The thinking field controls the model’s reasoning depth before it produces output. Valid values are off, minimal, low, medium, high, and xhigh. The default is high. Higher thinking levels increase reasoning depth and token usage. Use low for straightforward summarization or simple generation tasks. Use high or xhigh for complex code review, multi-file debugging, or any task where accuracy matters more than speed. 
- model: claude-opus-4-8
  thinking: xhigh
  prompt: >
    Trace the root cause of the failing integration test. Check all code paths
    that touch the payment module and propose a fix.

​
Combining run and agent steps

Agent steps and shell steps can be mixed freely within a job. This is the foundation of Shipfox’s self-fixing loops: an agent edits the source, a run step verifies the result, and a gate retries from the top if verification fails. 
jobs:
  fix-and-verify:
    steps:
      - key: install
        run: npm ci
      - model: claude-opus-4-8
        prompt: The tests are failing. Edit the source code to fix them.
      - run: npm test
        gate:
          success_if: exit_code == 0
          on_failure:
            restart_from: install
On each iteration, the agent reads the updated codebase and attempts another fix. The gate evaluates npm test’s exit code — if the test run still fails, execution jumps back to the install step and the loop begins again. See the Gate & Retry guide for full details.

​
Agent step rules

Keep these constraints in mind when authoring agent steps:
  • env is not valid on agent steps — it is supported only on run steps.
  • run and any of prompt, model, thinking, or provider cannot appear on the same step.
  • prompt is required on every agent step — a step with model but no prompt will be rejected.
  • The agent: key is reserved and will be rejected with an explicit error message.

​
Next steps

  • Gate & Retry — build self-correcting loops with gate conditions.
  • Model Providers — add API keys and configure your default provider.