Build Your First Agent-Native Tool with the GitHub Copilot SDK

At Microsoft Build 2026, GitHub dropped something quietly transformative: the GitHub Copilot SDK is now generally available in Node.js/TypeScript, Python, Go, .NET, Rust, and Java. This is not a wrapper around chat completions. It is the same agentic runtime that powers the Copilot app, the CLI, cloud automations, and partner-built agent apps — and for the first time, you can build on it directly.

If you have ever wished your internal tools could understand context, take actions across repositories, and plug into the same agent ecosystem your developers already use, this is the SDK that makes it possible. No bespoke orchestration. No fragile prompt engineering. One runtime, your own surface.

Here is how to get started, what the SDK actually gives you, and how to build something useful in an afternoon.

What the Copilot SDK Actually Is

The Copilot SDK exposes three layers:

Agent runtime — the loop that plans, executes tools, observes results, and iterates. This is the same loop running inside GitHub Copilot Agent mode, the Copilot app, and cloud agents.
Context system — automatic access to repository files, issues, pull requests, and commit history, scoped to what the agent actually needs.
Tool registry — a pluggable surface where you register custom capabilities as typed functions the agent can discover and invoke.

What makes this different from calling a model API is the orchestration layer. You do not write prompts that say "please read this file and then edit that one." You define a tool, register it, and the agent runtime decides when to call it, what arguments to pass, and how to recover when something goes wrong.

The result is a tool that behaves like a first-class citizen in the Copilot ecosystem — not a side script you have to remember to run.

What You Can Build

Before diving into code, here are the kinds of tools teams are already shipping with the SDK:

Custom code review agents that enforce your organization's style, security, and architecture rules beyond what Copilot's built-in review covers.
Release note generators that scan merged PRs, read commit messages, and draft formatted release notes with links to issues and contributors.
Internal documentation agents that watch for API changes and update your docs repo automatically.
Support workflow agents that read support tickets, search your codebase for relevant modules, and suggest fixes or escalate with context.
Deployment safety agents that analyze a PR's blast radius, check for missing tests, and flag risky changes before merge.

The common thread: these are not chatbots. They are workers that understand your codebase, follow your policies, and take action with accountability.

Getting Started: The TypeScript Quickstart

The fastest path to a working tool is TypeScript, but the patterns are nearly identical across all six languages. Here is the skeleton.

1. Install the SDK

npm install @github/copilot-sdk

2. Define Your Tool

A tool is a typed function with a description, parameters, and an implementation. The description matters — it is how the agent runtime decides when to invoke your tool.

import { defineTool } from "@github/copilot-sdk";

export const analyzeBlastRadius = defineTool({
  name: "analyzeBlastRadius",
  description:
    "Analyze a pull request to identify which modules, APIs, and consumers are affected by the proposed changes. Returns a risk score and a list of affected files.",
  parameters: {
    type: "object",
    properties: {
      prNumber: {
        type: "number",
        description: "The pull request number to analyze",
      },
      depth: {
        type: "string",
        enum: ["shallow", "deep"],
        description:
          "Shallow checks direct file changes only; deep follows call chains and dependency graphs",
      },
    },
    required: ["prNumber"],
  },
  async execute({ prNumber, depth = "shallow" }, context) {
    // context.repo gives you the current repository
    // context.octokit is an authenticated GitHub API client
    const pr = await context.octokit.rest.pulls.get({
      owner: context.repo.owner,
      repo: context.repo.repo,
      pull_number: prNumber,
    });

    const files = await context.octokit.rest.pulls.listFiles({
      owner: context.repo.owner,
      repo: context.repo.repo,
      pull_number: prNumber,
    });

    // Your custom logic here: map files to modules,
    // trace dependencies, calculate risk scores
    const affectedModules = files.data.map((f) => inferModule(f.filename));
    const riskScore = calculateRisk(affectedModules, depth);

    return {
      riskScore,
      affectedModules,
      changedFiles: files.data.length,
      recommendation:
        riskScore > 7
          ? "Recommend additional review and integration tests"
          : "Standard review process sufficient",
    };
  },
});

The context object is the bridge between your tool and the Copilot ecosystem. It includes the authenticated GitHub client, repository metadata, workspace file access, and the agent's current session state. You do not manage tokens or repository URLs yourself.

3. Register and Run

import { createAgent } from "@github/copilot-sdk";
import { analyzeBlastRadius } from "./tools/blast-radius";

const agent = createAgent({
  name: "deploy-guardian",
  description:
    "A safety agent that reviews pull requests for deployment risk before merge",
  tools: [analyzeBlastRadius],
});

// Run locally for development
agent.start({ mode: "local" });

In local mode, the agent runs on your machine with access to your local repository and your GitHub credentials. It is the fastest way to iterate.

4. Connect to GitHub Copilot

Once you are ready to share the tool with your team, publish it as a Copilot extension:

agent.publish({
  scope: "organization", // or "repository" or "public"
});

After publishing, anyone with access can invoke your agent through Copilot Chat by mentioning it — @deploy-guardian analyze PR #482 — and the runtime handles the rest.

Patterns That Work

After reviewing the SDK documentation and early community examples, here are the patterns that separate useful tools from abandoned experiments.

Be Specific About What Your Tool Does

The agent runtime decides whether to call your tool based on its name and description. Vague descriptions lead to missed invocations or irrelevant calls. A good description includes:

What input it expects
What action it performs
What output it returns
When it should be used instead of alternatives

Compare these two descriptions:

Vague: "Checks code quality."

Specific: "Analyzes a pull request's changed files for breaking API changes, missing test coverage, and undocumented public methods. Returns a structured report with severity levels and file-level annotations. Use this when a PR touches public APIs or core modules."

The second description gives the runtime enough signal to invoke your tool at the right time and ignore it when irrelevant.

Return Structured Data, Not Prose

The agent runtime consumes your tool's output and feeds it into subsequent reasoning steps. Structured JSON with clear fields is far more useful than a paragraph of text. Include:

success: boolean
summary: a one-line human-readable result
details: structured data the agent can reference
confidence: a 0-10 score when the result involves judgment

This lets the agent chain your tool with others — for example, calling your blast-radius analyzer, then conditionally calling a test generator only if the risk score is high.

Handle Failures Gracefully

Your tool will be called in contexts you did not anticipate. A PR might not exist. A file might be binary. The GitHub API might rate-limit you. Every tool should return a coherent result even on failure:

try {
  const result = await expensiveAnalysis();
  return { success: true, summary: "Analysis complete", details: result };
} catch (err) {
  return {
    success: false,
    summary: `Analysis failed: ${err.message}`,
    details: { errorType: err.name, recoverable: isRecoverable(err) },
    confidence: 0,
  };
}

The agent runtime uses this structure to decide whether to retry, escalate, or surface the issue to the user.

Use Memory When Context Matters

The Copilot SDK includes a memory system that persists across sessions. If your tool needs to learn from previous runs — for example, tracking which modules historically cause regressions — store that context:

import { useMemory } from "@github/copilot-sdk";

const memory = useMemory("deploy-guardian:historical-risks");
const pastRisks = await memory.get(repoFullName);
const updatedRisks = updateWithCurrentRun(pastRisks, currentResult);
await memory.set(repoFullName, updatedRisks);

Memory is scoped to your tool and optionally shared across your organization, so institutional knowledge accumulates without manual bookkeeping.

The Bigger Picture: One Runtime, Many Surfaces

The power of the Copilot SDK is not any single tool. It is the fact that the same runtime spans every surface your developers already use.

VS Code and Visual Studio: Your tool shows up as a Copilot Chat participant with inline annotations and code lenses.
Copilot CLI: Developers can invoke your tool from the terminal with natural language.
Copilot App: Your tool appears as a canvas extension where agents and humans collaborate on shared work surfaces.
GitHub.com: Your tool runs in the background on issues and pull requests, adding labels, comments, and checks.
Cloud automations: Your tool runs on schedules or GitHub events, filing issues and opening pull requests without human intervention.

You write the tool once. The runtime handles the rest.

This is why the SDK is generically available in six languages, not just TypeScript. Teams with Python-heavy data science workflows, Go-based infrastructure, or Java enterprise stacks can all participate without rewriting their logic in JavaScript.

What Is Still Missing

The SDK is GA, but it is early. Here are the gaps to plan around:

Local sandboxing is not yet automatic. If your tool runs untrusted code or executes shell commands, you need to bring your own isolation. Cloud sandboxes are coming, but for local development, assume your tool runs with your user privileges.
Multi-agent orchestration is manual. You can compose multiple tools, but orchestrating multiple independent agents with shared state requires building that coordination yourself. The Copilot app does this natively; custom tools do not yet.
Pricing is consumption-based. Tool invocations count against Copilot Credits. For high-frequency automations, this adds up. Monitor usage and set rate limits for event-driven triggers.

None of these are blockers. They are simply the boundaries of the current release.

A Practical Weekend Project

If you want to build something real this weekend, here is a complete project idea:

The Dependency Health Agent

Build a tool that:

Scans a repository's dependency files (package.json, requirements.txt, Cargo.toml, etc.).
Checks each dependency for known CVEs using the GitHub Advisory Database.
Identifies outdated major versions.
Generates a weekly report as a GitHub issue with severity badges, recommended upgrade paths, and estimated effort.
Optionally opens a pull request with updated lockfiles for low-risk bumps.

This uses the SDK's file access, GitHub API integration, structured output, and cloud automation features — and it solves a problem every engineering team has.

The Bottom Line

The GitHub Copilot SDK turns GitHub from a code host into an agent platform. You are no longer limited to the features GitHub ships. You can build your own agent-native tools, publish them to your organization, and plug them into the same runtime that powers Copilot itself.

For teams that have been waiting for a clean, supported way to extend AI assistance into their internal workflows, this is it. The SDK is GA, the documentation is solid, and the patterns are settling. The best time to build your first tool is this weekend. The second best time is Monday morning.

Happy building.

Sources: GitHub Copilot SDK documentation, GitHub Blog — "GitHub Copilot app: The agent-native desktop experience," Microsoft Build 2026 sessions, GitHub Changelog — Copilot CLI updates