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 do not need the service to be deployed. A repo brought in with Agentic Develop is not running anything until you deploy it, and every agent feature on this page still works on it. To see the same work grouped by the pull request it belongs to, use the Develop tab next to it.
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.
Every session can also read the platform state of the service it works on: deployment status, the latest build, build logs and runtime logs. These are the same read-only tools the MCP integration exposes, scoped to that one service, so the agent can check why a deploy failed or what the running service logged before it changes code. The sandbox never receives a credential for this. Requests are answered by the platform over the session's own control channel.
- 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.
Develop
Develop is its own tab, next to Code Reviews. It lists every pull request on the linked repository down the left side, newest selected by default, with an activity summary per PR so you can see at a glance which ones agents have touched.
Above the list are a search box and a state filter. Search matches a PR number or any part of a title, the filter narrows to Open, Merged or Closed, and both run against the whole repository rather than the rows already on screen. Both live in the address bar, so a filtered view can be shared or bookmarked.
Pick a PR and the right side shows everything the platform did for it, split across four tabs:
- Overview - the composer for starting an agent on this PR, plus code reviews that ran against it, its preview environment with URL and pod state, and every job the PR produced
- Agent runs - the sessions and sandbox coder runs that worked on the branch
- Custom agent runs - custom agents this PR triggered, or that opened it
- Workflow runs - agent workflow runs it triggered
Use it when you want the whole story of a change rather than one slice of it. Selecting a different PR keeps you on the same tab.
Pull requests appear as soon as they are opened, and a PR the platform opens itself (a coder session, a custom agent finalizing with a branch and PR) shows up right away. Agent workflow runs are listed only for merged pull requests, because that is when a pull request trigger fires.
Putting agents to work on a pull request
Both ways of starting work use the PR's branch rather than the service default:
- The composer at the top of Overview starts a session with the PR's branch pinned. The agent commits straight onto that branch, so the work lands on this pull request instead of opening another one.
- Custom agent runs > Run agent picks one of your enabled custom agents and runs it against the PR.
Running from here retargets an agent at the pull request. It does not change what the agent is allowed to do: an agent set up to commit commits to the PR branch, and a report-only agent still only reads. To change that, edit the agent's workflow step on the Agents tab.
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.