Agents
Run coding and research agents on your repository in an isolated cloud sandbox
The Agents tab on any repo service runs AI agents against your repository. Each session gets its own cloud sandbox with a checkout of the service branch, so nothing runs on your machine and nothing touches your running app.
The tab has four sub-tabs:
- Agent runs - interactive sessions and recent custom agent runs
- Custom agents - reusable agents you define once and run on demand or from a workflow
- Instructions - standing rules every coding agent follows on this service
- Agent workflows - custom agents bound to service events, see Workflows
Agents need AI budget left in the period. See AI budget and spend, and Settings > AI to check what is left or to turn AI features off. If the tab is greyed out with "Available for beta testers", the coder agent is not enabled on your instance yet.
Starting a Session
- Open a repo service and go to Agents > Agent runs
- Click New session
- Describe the task, then pick the agent type and model
- Press send
Two agent types:
| Type | What it does |
|---|---|
| Coder | Edits the checkout, pushes a branch, and opens a pull request |
| Research | Read-only. Explores the repository and reports back without changing anything |
Type @ in the composer to mention a file from the repository and pin the agent to the right place. The branch the sandbox checks out is shown next to the agent type.
Model choice
The model picker lists the models available to your organization. Leave it alone to use the default, which is picked for a good balance of speed and capability. Heavier models cost more AI budget per run.
Working With a Running Session
The session view streams the agent's transcript as it works: its reasoning, the tools it calls, and the files it touches.
- Changed files - a running count of files modified in the session. Click it for a side-by-side diff of everything so far, or open the diff on a single step
- Stop - interrupts the current turn. The sandbox and the work done so far stay
- Reply - keep talking to the agent in the same session, with the same workspace and context
- Follow-up - when an agent hands off (a research agent proposing an implementation, for example), start a new session pre-briefed with the handoff
A coder session pushes a branch and opens a pull request when it finishes its work. From there the normal flow applies: the PR gets a preview environment and an AI code review if those workflows are enabled.
Session states
| State | Meaning |
|---|---|
provisioning | Sandbox is starting |
active | Sandbox is up, agent is working or waiting for you |
suspended | Idle. The workspace is snapshotted and the sandbox released. Replying restores it |
error | The session failed. Start a new one |
closed | Ended by you or after a long idle period |
Close a session when you are done with it. Deleting a session removes its transcript and sandbox, not the branch or pull request it pushed.
Instructions
The Instructions sub-tab holds standing rules for coding agents on this service. Every session and every agent run on the service gets them, so this is where conventions live: which package manager to use, what to never touch, how to name branches.
- Open Agents > Instructions
- Click Add instruction
- Write one rule per instruction, in plain language
- Toggle an instruction off to retire it without losing the text
Keep instructions short and specific. "Use Bun, never npm" works. "Write good code" does not.
Code review agents have their own separate list, see Learnings.
Custom Agents
A custom agent is a reusable definition: a prompt, a set of tools, and a model. Define it once, then run it by hand from the Custom agents sub-tab or bind it to a service event with an agent workflow.
Only an organization owner can create, edit, delete, or enable custom agents. Any member can run an enabled one.
Creating one
- Open Agents > Custom agents
- Click New agent
- Fill in the definition and click Create
| Field | What it controls |
|---|---|
| Name | Shown in lists and workflow pickers |
| Description | What the agent is for |
| Prompt | Instructions the agent follows on every run |
| Platform tools | Which platform data the agent may read: deployment status, latest build, build logs, runtime logs. Plus Trigger workflow for handoffs. Baseline file and shell tools are always available |
| Check out the service repository | On for agents that read or change code. Turn it off for agents that only read platform data. Required for anything that commits or opens a pull request |
| Model | Which model the agent runs on |
| Share across the organization | Available in every project. Leave off to scope it to this project. Set at creation time |
Running one
Click Run now on an agent card. The run appears in the Sessions list next to interactive sessions, and its detail view shows the transcript, tool calls, and result. Disabled agents cannot be run.
Each run is also a custom-agent-run job in the Jobs tab, where it can be cancelled or retried.
Other Ways to Reach Agents
- From a code review - hand findings to a coding agent that fixes them on the PR branch. See Code Reviews
- From your own agent - the
task_agentand*_agent_sessionMCP tools start and steer sessions from Cursor, Claude Code, or any MCP client. See MCP Integration - On service events - agent workflows run custom agents on push, PR merge, deployment, or build outcomes. See Workflows
Cost and Limits
Every agent run spends AI budget. Settings > AI shows what is left this period and breaks spend down by model, feature, and project. When the included budget and any purchased top-up are exhausted, new runs are refused until the period resets or you top up. Heavier models cost more per run.