Working Context and Composites
Agents burn tokens on repeated owner / repo args, multi-hop reads, and fat payloads (full PR diffs, long issue bodies, entire files). The SDK ships three levers that work together: a working context, composite tools, and lean defaults.
Working context
Pass context to createGithubTools, createGithubAgent, or createDurableGithubAgent to default owner, repo, pullNumber, issueNumber, and/or ref on matching tool inputs. Matching schema fields become optional and fill from context when omitted. Agents also get a short system-prompt block describing the context:
import { createGithubTools, createGithubAgent } from '@github-tools/sdk'
const tools = createGithubTools({
preset: 'code-review',
context: { owner: 'vercel', repo: 'ai', pullNumber: 42 },
})
const agent = createGithubAgent({
model: 'anthropic/claude-sonnet-4.6',
preset: 'code-review',
context: { owner: 'vercel', repo: 'ai', pullNumber: 42 },
})
The same option is available on the eve extension via context in the mount config.
Composite tools
Prefer one composite call over chaining several reads:
| Tool | Returns |
|---|---|
getPullRequestContext | PR details + files + reviews (+ optional CI checks). filesHasMore / reviewsHasMore when those lists continue |
getIssueContext | Issue + labelNames + recent comments. commentsHasMore when more comments exist |
getReleaseContext | Release + previous release + tag comparison |
getCiFailureContext | Combined status, failing checks, failed workflow jobs/steps |
Call independent follow-up reads in the same step when you already know the arguments (for example getIssueContext and listIssues together).
Lean payload defaults
| Default | Behavior | Override |
|---|---|---|
detail: 'summary' | Truncates long bodies (~500 chars) on getPullRequest, getIssue, getDiscussion, and release getters | detail: 'full' |
getIssueContext | Defaults to detail: 'full' (one-shot) and returns labelNames (strings), not full label objects | detail: 'summary'; use listLabels for descriptions; use listIssueComments to paginate beyond the embedded comments |
includePatch: false | Omits diff patches on listPullRequestFiles, getCommit, compareCommits | includePatch: true; optionally filenames on listPullRequestFiles |
| File ranges | Prefer startLine / endLine / maxLines on getFileContent | Omit ranges only for small files |
| Paged lists | REST list tools return { items, hasMore, page, nextPage } (or add those fields next to checkRuns / runs / …). Default is one page. | When hasMore, call with nextPage or set maxPages to combine pages. Do not repeat the same page. Filter listCommits with path / author / since / until |
getRepositoryTree | Optional path prefix; model output caps at 200 entries | Prefer path over recursive: true; if truncated, narrow path |
| Text-match fragments | searchCode truncates each snippet to ~300 chars | None — fetch the file with getFileContent for full context |
listDiscussions | Returns 20 discussions per call, cursor-paginated | Raise perPage, or pass the returned endCursor as after |
getWorkflowJobLogs | Returns the last 200 log lines with per-line timestamps stripped | Raise maxLines (up to 2000) when the error is higher up |
listPullRequestReviewThreads | Returns unresolved threads only, comment bodies truncated (~500 chars), cursor-paginated | status: 'all' for resolved threads; detail: 'full' for complete bodies; pass endCursor as after |
listNotifications | Returns 20 unread threads per call (max 50) | all: true to include read threads; raise perPage; when hasMore, pass nextPage |
Example: code review bootstrap
import { createGithubAgent } from '@github-tools/sdk'
const agent = createGithubAgent({
model: 'anthropic/claude-sonnet-4.6',
preset: 'code-review',
context: { owner: 'vercel-labs', repo: 'github-tools', pullNumber: 39 },
})
// Prefer getPullRequestContext first, then listPullRequestFiles with
// includePatch + filenames for only the files you need to inspect.
await agent.generate({ prompt: 'Summarize this PR and list two review findings. Read-only.' })
See the tools catalog for the full list and the API reference for context on createGithubTools.