# How to build a GitHub agent with eve and GitHub Tools **Author:** Hugo Richard, Ben Sabic --- GitHub agents need three things: a durable runtime, tools that call the GitHub API, and credentials for those calls. [eve](https://eve.dev/) provides the runtime as a filesystem-first TypeScript framework, [GitHub Tools](https://github-tools.com/) provides pre-built, typed tools for pull requests, issues, and repositories, and [Vercel Connect](https://vercel.com/docs/connect) mints short-lived GitHub tokens at runtime so no personal access token lives in your environment. Vercel Connect also manages the GitHub App for you, which means you never register an app or handle a private key. The result is an agent that reviews pull requests, triages issues, and answers `@mentions` on GitHub, with human approval gating every risky write. ## Overview In this guide, you'll learn how to: - Scaffold an eve agent and link it to a Vercel project - Create a GitHub connector in Vercel Connect and install its managed GitHub App - Register all GitHub tools in your agent from a single file with `@github-tools/sdk/eve` - Gate write operations behind durable human-in-the-loop approval - Connect the eve GitHub channel through Vercel Connect so the agent replies to `@mentions` in issues and pull requests - Run the agent locally and send it work ## Prerequisites Before you begin, make sure you have: - Node.js 24 or newer - A [Vercel account](https://vercel.com/signup) and the [Vercel CLI](https://vercel.com/docs/cli) installed (`npm i -g vercel`) - A GitHub organization or personal account where you can install a GitHub App ## How it works Every deployment on Vercel carries an [OIDC identity](https://vercel.com/docs/oidc). When your agent needs GitHub access, the `@vercel/connect` SDK presents that identity to Vercel Connect, which checks that your project is linked to the GitHub connector and returns a short-lived token issued through its managed GitHub App installation. GitHub Tools uses that token for its API calls. The token is cached in-process and refreshed automatically as it approaches expiry, so there is no long-lived secret to rotate, leak, or copy between environments. ## Steps ### 1\. Scaffold the eve agent Create a new eve app. The `init` command scaffolds the project, installs dependencies, and initializes Git: `npx eve@latest init github-agent` Stop the dev server it starts with `Ctrl+C`, then link the directory to a Vercel project and pull your environment variables: `cd github-agent vercel link vercel env pull` `vercel env pull` writes a `.env.local` file containing a short-lived `VERCEL_OIDC_TOKEN`. Both the [AI Gateway](https://vercel.com/ai-gateway) and the `@vercel/connect` SDK use this token to authenticate requests, so there is no API key to configure. Re-run `vercel env pull` if you see authentication errors during local development. In production, the token is injected and refreshed for you. ### 2\. Create the GitHub connector Create a connector for GitHub from the linked project directory: `vercel connect create github --name github-agent` Vercel opens your browser to complete the setup: Vercel Connect creates a GitHub App named after your connector, and GitHub prompts you to pick the organization or account and the repositories the app can access. Because Vercel creates and holds the app, you don't register an OAuth client or manage a private key; the credentials stay server-side with Vercel Connect. Choose the connector name deliberately, because it's also the name people will `@mention` to talk to your agent. Then attach the connector to your project so it can request tokens: `vercel connect attach github/github-agent` By default, `attach` links every environment. Use `-e production -e development` to restrict it. The connector's uid is `github/github-agent`, which is the string your code passes to `getToken`. ### 3\. Install GitHub Tools and the Connect SDK The eve scaffold already includes `eve`, `ai`, and `zod`. Add the GitHub Tools SDK and the Vercel Connect SDK: `npm install @github-tools/sdk @vercel/connect` The `@github-tools/sdk/eve` subpath requires `ai` v7 as a peer dependency, which eve v0.19 and later already uses. If your install resolves an older `ai` version, update it before continuing. ### 4\. Register the GitHub tools Create `agent/tools/github.ts`. This single file registers every tool in the presets you choose, mints a GitHub token through Vercel Connect, and configures approval for write operations: `import { getToken } from "@vercel/connect"; import { createGithubTools } from "@github-tools/sdk/eve"; const token = await getToken("github/github-agent", { subject: { type: "app" }, }); export default createGithubTools({ token, preset: ["code-review", "issue-triage"], requireApproval: { mergePullRequest: true, createIssue: "once", addPullRequestComment: false, }, });` A few things happen here: - `getToken` requests an app-subject token from the `github/github-agent` connector. The token acts as the GitHub App installation, scoped to the repositories you selected in step 2. Because the connector has one installation, you can omit `installationId`; pass it when one connector serves several organizations. - `createGithubTools` returns a dynamic tool set that eve resolves when a session starts. The model sees each tool by name, such as `listPullRequests` and `createIssue`. - The `preset` array merges the `code-review` and `issue-triage` tool sets. Other presets include `repo-explorer`, `ci-ops`, and `maintainer`. `requireApproval` is where eve improves on the plain AI SDK surface: `true` pauses the session durably until a person approves every call, `'once'` asks the first time in a session and then auto-allows, and `false` skips approval. You can also pass a predicate that inspects the tool input, for example to require approval only for writes outside your own organization. Any write tool you don't list keeps the fail-safe default of always requiring approval, and read tools never require it. ### 5\. Write the agent's instructions Replace the contents of `agent/instructions.md`: `You are a GitHub assistant for our team. Use the GitHub tools to inspect repositories, pull requests, and issues. Summarize findings before acting. Ask before merging, closing, or deleting anything.` Optionally, change the model in `agent/agent.ts`. The scaffold's default works as-is: `import { defineAgent } from "eve"; export default defineAgent({ model: "anthropic/claude-sonnet-5", });` ### 6\. Run the agent Start the dev server and its terminal UI: `npm run dev` Type a prompt such as: `List the open pull requests in vercel-labs/github-tools and summarize the oldest one.` The agent calls `listPullRequests`, reads the results, and replies with a summary. Read calls run without interruption. Now ask it to act: `Open an issue in my-org/my-repo titled "Flaky CI on main" with a short description.` Because `createIssue` is set to `'once'`, eve pauses the turn and asks you to approve the call. Approve it in the terminal UI, and the tool runs. For the rest of the session, `createIssue` calls proceed without asking again. That pause is durable: the session survives restarts and resumes exactly where it left off once approval arrives. ### 7\. Add the GitHub channel The [eve GitHub channel](https://eve.dev/docs/channels/github) lets people `@mention` the agent in issues, pull requests, and review comments, and the agent replies in the thread with the PR diff already in context. The same connector powers it: `connectGitHubCredentials` from `@vercel/connect/eve` supplies the channel's installation token in function form and verifies Connect-forwarded webhooks with Vercel OIDC, so the channel skips its native GitHub App JWT exchange and webhook-secret check entirely. Create `agent/channels/github.ts`: `import { githubChannel } from "eve/channels/github"; import { connectGitHubCredentials } from "@vercel/connect/eve"; export default githubChannel({ botName: "github-agent", credentials: connectGitHubCredentials("github/github-agent"), });` Vercel Connect created the GitHub App under your connector's name, so set `botName` to the name you chose in step two. Comments that mention `@` kickoff a turn. Then register the channel's route as a trigger destination so Connect forwards GitHub webhooks to it: `vercel connect attach github/github-agent --triggers --trigger-path /eve/v1/github` Vercel Connect verifies each incoming GitHub webhook against the app's webhook secret, which it holds server-side, then forwards the event to `/eve/v1/github` on your latest deployment with a Vercel OIDC token attached. The channel's verifier validates that token instead of GitHub's signature. Trigger forwarding delivers to deployed URLs only, so mention-driven turns need a deployment. While testing locally, you can use both the terminal UI and the HTTP API. ### 8\. Deploy to Vercel Deploy the agent to the linked project: `eve deploy` The deployed agent authenticates to Vercel Connect with its own OIDC identity, so no environment variables need to move. Confirm the connector is attached to the environment you deployed to; a production deployment can only mint tokens if the project link includes the production environment. Your agent is now reachable over eve's HTTP API at `/eve/v1/session`, and you can drive it remotely with `npx eve dev https://`. Now try the channel. Open an issue in a repository the app can access and comment: `@github-agent summarize this issue and suggest labels.` The channel adds an eyes reaction to your comment, runs the turn, and replies in the thread. Write actions still pause for approval, which the channel posts as a comment prompt you answer by replying. ## Troubleshooting ### Token requests fail with `ConnectorNotFoundError` or `ClientNotLinkedToProjectError` The connector uid in `getToken` doesn't match a connector on your team, or the project isn't linked to it. Run `vercel connect list` to confirm the uid, then `vercel connect attach github/github-agent` from the project directory. ### Authentication errors during local development The `VERCEL_OIDC_TOKEN` in `.env.local` is short-lived. Run `vercel env pull` again to refresh it. ### The GitHub token goes stale in a long-running process GitHub Tools currently accepts the token as a static string, minted when eve loads the tool file. The Connect SDK refreshes cached tokens automatically on each `getToken` call, but a token already handed to `createGithubTools` is not re-minted until the module reloads. Restart the dev server if GitHub calls start returning 401 errors after a long local session. Per-session tokens through eve connections are on the GitHub Tools roadmap. ### Mentions on GitHub don't start a turn Confirm the connector is attached with `--triggers` and `--trigger-path /eve/v1/github`, and that `botName` matches the GitHub App slug on your connector. Trigger forwarding delivers only to deployments, so mentions never reach a local dev server. ### Peer dependency conflicts on `ai` eve v0.19 and later requires `ai` v7, and so does `@github-tools/sdk/eve`. If your lockfile pins `ai` v6, update it and reinstall. ## Resources and next steps - Dispatch on more GitHub events with the [eve GitHub channel's opt-in hooks](https://eve.dev/docs/channels/github). `onIssue`, `onPullRequest`, and CI hooks such as `onCheckSuite` let the agent react when an issue opens, or a check suite fails, without anyone mentioning it. - Tune write safety with predicates and per-tool policies in [Control write safety](https://github-tools.com/guide/approval-control). - Browse every available tool in the [GitHub Tools catalog](https://github-tools.com/api/tools-catalog). - Understand connectors, installations, and token scoping in [Vercel Connect concepts](https://vercel.com/docs/connect/concepts). - Explore [eve tools](https://eve.dev/docs/tools) to add your own typed tools alongside the GitHub set. --- [View full KB sitemap](/kb/sitemap.md)