---
title: "Coding agents"
description: "How an agent that opens pull requests keeps its context small over a long task, and where it runs the tests for the code it changes."
canonical_url: "https://github-tools.com/learn/coding-agents"
---
# Coding agents

> How an agent that opens pull requests keeps its context small over a long task, and where it runs the tests for the code it changes.

An agent that changes code and opens pull requests needs two things beyond its GitHub tools: a way to keep its context small across a task that can run for dozens of tool calls, and somewhere to run the code it changed. `@github-tools/sdk` calls the GitHub API and runs no code, so the tests run either in your CI or in a sandbox the agent's runtime provides. We recommend both: a sandbox for fast checks while the agent works, and CI as the final check on the pull request.

## Where the context goes

Each tool result stays in the conversation, and the model reads the whole conversation again on every call. In a coding task, most of it comes from file contents, diffs, and CI logs, and from the tool list itself, which is sent with every call.

The tools already keep their results small:

<table>
<thead>
  <tr>
    <th>
      Cost
    </th>
    
    <th>
      What the tools do
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Rewriting a file to change a few lines
    </td>
    
    <td>
      <code>
        editFiles
      </code>
      
       replaces exact text, so the model sends the lines it changes and not the whole file. It can create the branch and open the pull request in the same call
    </td>
  </tr>
  
  <tr>
    <td>
      Several reads to understand one pull request or failure
    </td>
    
    <td>
      <code>
        getPullRequestContext
      </code>
      
       and <code>
        getCiFailureContext
      </code>
      
       return what a review or a CI diagnosis needs in one call. See <a href="https://github-tools.com/context">
        Context
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Long job logs
    </td>
    
    <td>
      <code>
        getWorkflowJobLogs
      </code>
      
       returns the last 200 lines without timestamps, unless the model asks for more
    </td>
  </tr>
  
  <tr>
    <td>
      Long lists
    </td>
    
    <td>
      List tools return one page and <code>
        hasMore
      </code>
      
      , so the model fetches the next page only when it needs it
    </td>
  </tr>
  
  <tr>
    <td>
      The tool list
    </td>
    
    <td>
      A <a href="https://github-tools.com/presets">
        preset
      </a>
      
       lists only the tools a job needs, and <code>
        preset: 'auto'
      </code>
      
       picks them from the request
    </td>
  </tr>
</tbody>
</table>

The rest depends on how you build the agent:

- Send wide reads to a [subagent](https://github-tools.com/guides/multi-agent). It can read twenty files or a whole test run in its own context and return only its conclusion.
- Trim what your own tools return. Test output is as long as a CI log: return the failing tests and their errors, not every passing line.
- Keep the plan outside the conversation, in the pull request description or a file in the sandbox. The agent can then pick up the task after the conversation is compacted or restarted.

## Where the tests run

<table>
<thead>
  <tr>
    <th>
      
    </th>
    
    <th>
      CI only
    </th>
    
    <th>
      Sandbox only
    </th>
    
    <th>
      Sandbox and CI
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Runs the code
    </td>
    
    <td>
      Your GitHub Actions workflows
    </td>
    
    <td>
      An isolated machine the agent runs commands in
    </td>
    
    <td>
      Both
    </td>
  </tr>
  
  <tr>
    <td>
      One check takes
    </td>
    
    <td>
      A push and a full workflow run
    </td>
    
    <td>
      One command
    </td>
    
    <td>
      One command, then one workflow run at the end
    </td>
  </tr>
  
  <tr>
    <td>
      You set up
    </td>
    
    <td>
      Nothing new
    </td>
    
    <td>
      The sandbox and its access to the repository
    </td>
    
    <td>
      The sandbox
    </td>
  </tr>
  
  <tr>
    <td>
      Catches
    </td>
    
    <td>
      Everything CI tests
    </td>
    
    <td>
      What the sandbox can run: typecheck, lint, unit tests
    </td>
    
    <td>
      Both
    </td>
  </tr>
</tbody>
</table>

### CI only

The agent commits with `editFiles`, ideally to a draft pull request, and reads the result with `getCiFailureContext`. When a check fails, it fixes the code with another `editFiles` call on the same branch. `editFiles` is in the `pr-author` preset and the CI tools are in `ci-ops`, so mount both with `preset: ['pr-author', 'ci-ops']`.

This needs nothing beyond the tools, and it tests the change in the environment that decides whether it merges. It also has three costs:

- Every fix is a new commit and a full workflow run, including any preview deployment. A change that takes five attempts leaves five commits on the pull request.
- The agent can't wait for CI cheaply. Polling `listCheckRuns` adds a tool call to the conversation each time. Start a new turn when a `workflow_run` event reports that the run finished instead, as in [Fix failing CI](https://github-tools.com/guides/fix-failing-ci#faq).
- A workflow that runs on a branch pushed to the repository itself gets the repository's secrets. GitHub withholds them from pull requests opened from a fork, but not from branches the agent pushes to the base repository. Review which workflows run on `push` and `pull_request` before you let an agent push.

### Sandbox

A sandbox gives the agent a shell: it can install dependencies, run one test, and read the error a few seconds later, without a commit. In [eve](https://github-tools.com/integrations/eve), the built-in `bash`, `read_file`, `write_file`, and `edit_file` tools run in the [agent's sandbox](https://eve.dev/docs/sandbox). With the AI SDK, write your own tool around [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) or a container you run.

Three details decide whether a sandbox can test your repository:

- **It has to run native processes.** eve's [default sandbox](https://eve.dev/docs/sandbox/default) is Vercel Sandbox on Vercel and Docker when a Docker daemon is running. Otherwise `eve dev` falls back to just-bash, which runs no native processes, so `pnpm test` doesn't run there.
- **Installing takes time.** Put the install in the environment's `prepare` callback. eve runs it once and starts each session's sandbox from the result.
- **Clone access is a credential.** A sandbox that clones a private repository needs a token. On Vercel Sandbox, a [network policy](https://eve.dev/docs/sandbox/vercel#network-policy) can add the token at the network boundary, so the token never enters the sandbox process. Give that token read access only.

Let the sandbox test and the GitHub tools write. After the checks pass in the sandbox, the agent commits the same edits with `editFiles` instead of running `git push`. The commit then goes through the tool's [approval](https://github-tools.com/approval), uses the [commit author](https://github-tools.com/commits) you configured, and uses a token limited to the tools you selected, and the sandbox never holds a token that can write. The model sends its edits twice, once in the sandbox and once to `editFiles`, and `find` and `replace` keep the second copy short.

### Sandbox and CI

Run the fast checks in the sandbox while the agent works: typecheck, lint, and the tests for the code it changed. Open the pull request as a draft once they pass, and let CI run what the sandbox can't, such as the full test matrix, tests that need secrets, and preview deployments. The agent marks the pull request ready with `updatePullRequest` once CI passes.

Most failures then show up in the sandbox in seconds, while the model still has its attempt in context, and CI runs once or twice per pull request instead of once per attempt.

In eve, the two parts are a sandbox file and an extension mount:

```ts [agent/sandbox.ts]
import { DefaultSandbox, defineSandbox } from 'eve/sandbox'

export const environment = DefaultSandbox.environment()
export default defineSandbox(() => environment.open())
```

```ts [agent/extensions/github.ts]
import githubExtension from '@github-tools/eve-extension'

export default githubExtension({
  connector: 'github/my-connector',
  preset: ['pr-author', 'ci-ops'],
})
```

Write the clone and install steps for your repository in the agent's instructions, or in `prepare` for the dependencies every session shares. [Software Factory](https://github.com/vercel-labs/eve-software-factory-template) is a complete eve agent that ends each task with a reviewed draft pull request.


## Sitemap

See the full [sitemap](https://github-tools.com/sitemap.md) for all pages.
