How to build a GitHub agent with eve and GitHub Tools

GitHub agents need three things: a durable runtime, tools that call the GitHub API, and credentials for those calls. eve provides the runtime as a filesystem-first TypeScript framework, GitHub Tools provides pre-built, typed tools for pull requests, issues, and repositories, and Vercel 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.

Copy link to headingOverview

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

Copy link to headingPrerequisites

Before you begin, make sure you have:

• Node.js 24 or newer
• A Vercel account and the Vercel CLI installed (npm i -g vercel)
• A GitHub organization or personal account where you can install a GitHub App

Copy link to headingHow it works

Every deployment on Vercel carries an OIDC identity.

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.

Copy link to headingSteps

Copy link to heading1. 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 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.

Copy link to heading2. 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.

Copy link to heading3. 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.

Copy link to heading4. 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.

Copy link to heading5. 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",
});

Copy link to heading6. 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.

Copy link to heading7. Add the GitHub channel

The eve GitHub channel 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 @<botName> 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.

Copy link to heading8. 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://<deployment>.

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.

Copy link to headingTroubleshooting

Copy link to headingToken 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.

Copy link to headingAuthentication errors during local development

The VERCEL_OIDC_TOKEN in .env.local is short-lived. Run vercel env pull again to refresh it.

Copy link to headingThe 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.

Copy link to headingMentions 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.

Copy link to headingPeer 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.

Copy link to headingResources and next steps

• Dispatch on more GitHub events with the eve GitHub channel's opt-in hooks. 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.
• Browse every available tool in the GitHub Tools catalog.
• Understand connectors, installations, and token scoping in Vercel Connect concepts.
• Explore eve tools to add your own typed tools alongside the GitHub set.