Agents
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
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
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 and the Agent step reference 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
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 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
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 shows the setup task. Integrations, integration connections, and tools explains the credential boundary.
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 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
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 for the authoring task. Context and templating explains how typed results move to later work.