# Agents (https://www.shipfox.io/docs/understand/agents)

Description: Understand when work needs an agent step, what the agent can see and do, and why a separate check must judge its result.

An **agent step** gives a coding agent a goal inside the job's checkout. It fits
work where nobody can write the exact steps in advance. Examples are an
investigation, a review, a plan, or a change that depends on the code.

The workflow still sets the limits. It chooses the prompt, the harness, the
model, the tools, the repository access, and the check that follows. The agent
chooses how to work inside those limits.

A run step follows a known command. A tool step makes one known integration
call. An agent step chooses its path from what it finds.

## When to use an agent step [#when-to-use-an-agent-step]

The three step kinds make different tradeoffs.

| Step       | Fits                                               | Tradeoff                                                       |
| ---------- | -------------------------------------------------- | -------------------------------------------------------------- |
| Run step   | A known command with a repeatable procedure.       | Predictable, fast, and easy to compare.                        |
| Tool step  | One known integration operation with known inputs. | Deterministic and free of model cost, but limited to one call. |
| Agent step | A goal that needs investigation or judgment.       | Flexible, but slower, more costly, and less predictable.       |

Use the most predictable step that can finish the work. Tests, builds,
formatting tools, and deploy scripts belong in run steps. Posting a message or
reading a ticket with known values belongs in a tool step. Root-cause
analysis, code review, and open-ended edits often need an agent.

A long or complex command is still a command. Use an agent only when the
workflow can't choose the path before it reads the code or the event.

## The parts of an agent step [#the-parts-of-an-agent-step]

Several parts work together. Each one controls a different thing.

| Part                | Role                                                                            |
| ------------------- | ------------------------------------------------------------------------------- |
| Harness             | Runs the agent loop and provides its native tools.                              |
| Provider            | Sends model requests to a configured model service.                             |
| Model               | Produces the reasoning and the responses.                                       |
| Native tools        | Read files, edit the checkout, and run local commands, as the harness allows.   |
| Integration tools   | Perform selected operations through an integration connection in the workspace. |
| Checkout permission | Controls authenticated Git access for the whole job.                            |

A workspace sets defaults for the harness, provider, and model. A step can
select another supported combination. [Model
providers](https://www.shipfox.io/docs/reference/model-providers) and the [Agent step
reference](https://www.shipfox.io/docs/reference/workflow-schema#agent-step-fields) list the accepted
values and the resolution order.

The parts are independent on purpose. A different model doesn't grant a GitHub
tool. A GitHub tool doesn't change the checkout credential. A different
checkout permission doesn't expose the integration credential.

## What the agent knows [#what-the-agent-knows]

The agent's context comes from the prompt and the checkout. The prompt can
include the event that started the run, outputs from earlier jobs, and later
events. The checkout
gives the agent the code of the current job.

Together they are stronger than either one alone. The event explains why the
work exists. The repository lets the agent check that report against real code.
An output can pass a small fact from earlier work without sharing another job's
files or logs. A [named session](https://www.shipfox.io/docs/understand/agent-sessions) can pass an
earlier agent's whole conversation to a later agent step, again without its
files.

Context can also be malicious. An issue body or a review comment can contain
instructions written for the agent. Treat external text in the prompt as data,
not as instructions. Give the step only the authority it needs, so a misleading
field can't extend its reach.

## What the agent can change [#what-the-agent-can-change]

Native tools act inside the runner. Integration tools reach an external system
through an integration connection. Shipfox gives the agent the selected
operation, not the stored credential of the integration connection.

Choose read access and write access on purpose. Select the smallest tool family
and repository scope that can finish the task. When possible, put an external
write after an objective check.

Repository permission applies to the whole job, because every step uses the
same checkout. Integration tools apply to one step. When a workflow needs local
edits and one external write, put the write on a later step, not on the step
that edits. A tool step fits when the workflow knows the exact call. An agent
step with a write tool fits when the agent must decide what to write.

[Agent access](https://www.shipfox.io/docs/how-to/author-workflows/use-integration-tools) shows the setup
task. [Integrations, integration connections, and
tools](https://www.shipfox.io/docs/understand/integrations-connections-and-tools) explains the credential
boundary.

## Check the result independently [#check-the-result-independently]

The agent's final response records what the agent believes it did. It is useful
for people. It doesn't prove that the code compiles or that the tests pass. It
doesn't prove that an external system reached the intended state either.

Use an independent check for every claim that matters.

* A test or type check for code behavior.
* A formatting tool or linter for a mechanical rule.
* A read-back operation for an external write.
* A person for a judgment that no reliable check can replace.

A [feedback loop](https://www.shipfox.io/docs/understand/feedback-loops) can send failed evidence back to
the agent. Keep the check separate from the agent's own assessment, so the
decision to stop stays objective.

## What the run records [#what-the-run-records]

Agent messages, tool activity, outputs, and attempts stay with the run. The
final response is for people. A typed output is for later workflow logic.

This split keeps prose from becoming an accidental API. When later work needs a
value, declare it as an output instead of parsing the agent's final message.

Use [Add an agent
step](https://www.shipfox.io/docs/how-to/author-workflows/add-agent-steps) for the authoring task. [Context
and templating](https://www.shipfox.io/docs/understand/data-and-templating) explains how typed results move
to later work.