Scope with Presets

The SDK ships a large tool catalog so you can build almost any GitHub agent. Presets are how you keep that catalog out of the model's context: each preset exposes only the tools for one workflow. Start with the smallest preset that fits; use maintainer or omit preset when you need the full surface.

Compose agents around presets

Apply a single preset

Use a preset to restrict the tools to a specific capability domain. For example, a code review agent only needs pull request and commit tools:

import { createGithubTools } from '@github-tools/sdk'

const tools = createGithubTools({
  preset: 'code-review',
})

Focused operator workflows:

import { createGithubTools } from '@github-tools/sdk'

const tools = createGithubTools({
  preset: 'security-audit',
})

import { createGithubTools } from '@github-tools/sdk'

const tools = createGithubTools({
  preset: 'pr-author',
})

Combine multiple presets

When a workflow spans multiple domains, pass an array. This agent can both review PRs and manage issues:

import { createGithubTools } from '@github-tools/sdk'

const tools = createGithubTools({
  preset: ['code-review', 'issue-triage'],
})

Let the agent pick presets

When one agent handles open-ended requests, use preset: 'auto':

import { createGithubAgent } from '@github-tools/sdk'

const agent = createGithubAgent({
  model: 'anthropic/claude-opus-5.5',
  preset: 'auto',
})

await agent.generate({ prompt: 'Why is CI failing on main?' })
// runs with the ci-ops tools and system prompt

On each call, a fast evaluation model reads the latest user message and rates how likely it is to need each preset. The agent then exposes only the tools of the chosen presets, and uses the preset's system prompt when exactly one is chosen. The full catalog is never exposed:

1. Presets rated at or above 0.7 are used, most likely first, up to two per call.
2. The read-only repo-explorer preset is only used when no other preset qualifies, since every other preset already has the read tools its task needs.
3. When none reaches 0.7, the single most likely preset is used. When nothing stands out, as with "hello", that is repo-explorer.

preset: 'auto' is available on createGithubAgent and needs ai 7.0.105 or later. To tune it, use evaluation: { minPresetProbability, maxPresets, model }. The default model is Jev from TypeSafe AI. If the evaluation call fails (model not enabled on AI Gateway, no credits, outage), the call uses read-only repo-explorer and logs a github_tools.EVALUATION_FAILED warning through console.warn.

Pick the right preset

Pair presets with token scopes

Each preset maps to specific GitHub token permissions:

• repo-explorer: read-only token, no write permissions needed (add discussions: read for the discussion tools)
• code-review: add pull_requests: write only if comments or reviewer requests are needed
• issue-triage: add issues: write (also covers reactions)
• ci-ops: add actions: write for triggering, cancelling, and re-running workflows
• security-audit: read-only token, plus issues: write to report findings
• release-manager: add contents: write for creating releases, actions: write if triggering release pipelines
• discussion-moderator: add discussions: write and issues: write for cross-linking replies
• notification-inbox: repository read scopes plus a user PAT with the "Notifications" account permission (not available on Connect installation tokens)
• pr-author: add contents: write and pull_requests: write
• maintainer: all write scopes, always paired with approval control; notification tools additionally need a PAT with the "Notifications" account permission

External references

• Principle of least privilege (OWASP)
• Manager agent with scoped sub-agents