> ## Documentation Index
> Fetch the complete documentation index at: https://www.shipfox.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure and Use AI Agent Steps in Shipfox Workflows

> Run AI models inline in your Shipfox workflows using agent steps. Set model, thinking level, and provider, or mix agent and shell steps in a single job.

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](/guides/model-providers)).

```yaml theme={null}
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:

```yaml theme={null}
- model: gpt-5.5-pro
  provider: openai
  prompt: Review the recent changes for security issues.
```

Some supported combinations to get you started:

| Provider         | `provider` ID | Example `model`          |
| ---------------- | ------------- | ------------------------ |
| Anthropic        | `anthropic`   | `claude-opus-4-8`        |
| OpenAI           | `openai`      | `gpt-5.5-pro`            |
| DeepSeek         | `deepseek`    | `deepseek-v4-pro`        |
| xAI              | `xai`         | `grok-4.3`               |
| Google AI Studio | `google`      | `gemini-3.1-pro-preview` |

See the [Model Providers](/guides/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.

```yaml theme={null}
- 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.

```yaml theme={null}
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](/guides/gate-and-retry) guide for full details.

## Agent step rules

<Warning>
  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.
</Warning>

## Next steps

* [Gate & Retry](/guides/gate-and-retry) — build self-correcting loops with gate conditions.
* [Model Providers](/guides/model-providers) — add API keys and configure your default provider.