Agents
Understand when work needs an agent and why separate checks must stay in control.
An agent step gives a coding agent a goal inside a job checkout. It fits work whose path cannot be fixed in advance. Examples include an investigation, a review, a plan, or a change that depends on the code.
The workflow still owns the boundary. It chooses the prompt, runtime, model, tools, repository access, and next check. The agent chooses how to work inside that boundary.
A command follows a known path. An agent chooses a path from the evidence it finds.
Choose judgment only when the task needs it
The two step types make different tradeoffs.
| Step | Best fit | Main tradeoff |
|---|---|---|
| Run step | A known command with a repeatable procedure. | Predictable, fast, and easy to compare. |
| Agent step | A goal that needs investigation or judgment. | Flexible, but slower, more costly, and less deterministic. |
Use the least open-ended step that can finish the work. Tests, builds, formatters, and deploy scripts belong in run steps. Root-cause analysis, code review, and open-ended edits often need an agent.
Complexity alone is not a reason to use an agent. A long command with known inputs is still a command. An agent earns its place when the workflow cannot choose the path before it sees the code or event.
The agent stack has separate choices
Several parts work together, but they control different things.
| Part | Role |
|---|---|
| Harness | Runs the agent loop and exposes its native tools. |
| Provider | Sends model requests to a configured model service. |
| Model | Produces the reasoning and responses. |
| Native tools | Read files, edit the checkout, and run local commands as supported by the harness. |
| Integration tools | Perform selected operations through a workspace integration connection. |
| Checkout permission | Controls authenticated Git access for the whole job. |
A workspace can provide defaults for the harness, provider, and model. A step can select another supported combination. Accepted values and resolution rules belong in Model providers and the Agent step reference.
The separation is useful. Changing the model does not grant a GitHub tool. Granting a GitHub tool does not change the repository checkout credential. Changing checkout permission does not expose the integration credential.
Context gives the goal meaning
The prompt can include the event that started the run. It can also include upstream outputs or later events. The checkout gives the agent the code for the current job.
This combination is stronger than either source alone. Event data explains why the work exists. The repository lets the agent test that report against real code. Outputs can carry a narrow fact from earlier work without sharing another job's files or logs.
Context can also be hostile. An issue body or review comment may contain instructions aimed at the agent. Treat external text as data in the prompt and limit authority so a misleading field cannot expand the step's reach.
Tools are authority, not convenience
Native tools act inside the runner environment. Integration tools cross into an external system through an integration connection. Shipfox gives the agent the selected operation, not the saved integration connection credential.
Read access and write access should be deliberate choices. Select the smallest tool family and repository scope that can finish the task. Put an external write after an objective check when the workflow can do so.
Repository permission is job-wide because all steps use one checkout. Integration tools are step-specific. A workflow may need local edits and one external write. Keep that write tool on the final agent step, not the editing step.
Agent access shows the setup task. Integrations, integration connections, and tools explains the credential boundary.
A response is not proof
The agent's final response records what it believes it achieved. It is useful for people. It does not prove that code compiles or tests pass. It also does not prove that an external system reached the intended state.
Use an independent check for important claims.
- A test or type check for code behavior.
- A formatter or linter for a mechanical rule.
- A read-back operation for an external write.
- A person for a judgment that cannot be reduced to a reliable check.
A feedback loop can send failed evidence back to the agent. Keep the check separate from the agent's self-assessment so the stopping rule remains objective.
The run keeps the evidence
Agent messages, tool activity, outputs, and attempts stay with the run. A final response serves people. A typed output serves later workflow logic.
This distinction 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.