The era of “AI as text” is over. Execution is the new interface.

Building Agentic Workflows with the GitHub Copilot SDK

Why this matters for builders

The GitHub Copilot SDK lets you embed programmable AI execution directly inside your applications, moving beyond chat-style “AI as text” to reliable, agentic workflows that can read, edit, run commands, and complete multi-step tasks on your behalf.

The official GitHub announcement marks a clear transition: execution is the new interface. Instead of copying LLM output into your codebase or terminal, you can now give AI structured tools, context, and permission to act inside your editor, CI pipeline, or custom application. This unlocks repeatable automation that feels like a tireless coworker rather than a suggestion engine.

When to use it

• You want to automate repetitive engineering tasks (refactoring, test generation, documentation updates) inside your own tools
• You are building internal developer platforms or AI-augmented IDE experiences
• You need to create “Copilot Cowork”-style agents that can plan and execute across files, terminals, and build systems
• You are tired of prompt-and-copy loops and want deterministic, auditable AI actions
• You are integrating agentic behavior into enterprise workflows where security, permission boundaries, and observability matter

The full process

Define the goal

Start by writing a one-paragraph outcome statement. Be specific about success criteria.

Example goal:
“Build a VS Code extension called auto-refactor that, when triggered on a TypeScript file, uses the Copilot SDK to (1) identify functions longer than 40 lines, (2) generate a plan to split them, (3) edit the code safely, (4) run existing tests, and (5) create a git commit only if tests pass.”

Write this goal in a README.md or SPEC.md file. This becomes your prompt anchor for every subsequent step.

Shape the spec and prompt strategy

Create a spec.md with these sections:

• Success metrics (e.g., “80% of refactors must pass all tests on first attempt”)
• Permission boundaries (what the agent is allowed to read/write/run)
• Error handling and fallback behavior
• Observability requirements (log every action the agent takes)

Starter prompt template (copy-paste ready):

You are an expert refactoring agent with access to the GitHub Copilot SDK.

Project context: {paste relevant parts of spec.md}

Task: {describe the exact outcome}

Available tools:
- read_file(path)
- edit_file(path, new_content)
- run_terminal_command(cmd, cwd)
- git_commit(message) — only if tests pass

Rules:
1. Always show me the exact plan before executing any edit.
2. Never edit more than one file without confirmation.
3. After every edit, run the relevant test suite.
4. If tests fail, revert the change and explain why.

Begin by outputting a step-by-step execution plan.

Use this template as the system prompt when you interact with any coding assistant (Claude, Cursor, Copilot Chat, etc.).

Scaffold the project

mkdir copilot-agent-demo && cd copilot-agent-demo
npm init -y
npm install @github/copilot-sdk vscode
mkdir src
touch src/extension.ts
touch spec.md
touch agent-plan.md

Add the following to package.json (adjust according to current Copilot SDK requirements—check official docs for latest):

{
  "name": "copilot-agent-demo",
  "activationEvents": ["onCommand:agent.refactor"],
  "contributes": {
    "commands": [{
      "command": "agent.refactor",
      "title": "Refactor with Copilot Agent"
    }]
  }
}

Implement carefully

Here is the skeleton for src/extension.ts:

import * as vscode from 'vscode';
import { CopilotSDK, ToolCall } from '@github/copilot-sdk';

export function activate(context: vscode.ExtensionContext) {
  const sdk = new CopilotSDK({
    // Authentication and permission settings — check official docs
  });

  const disposable = vscode.commands.registerCommand('agent.refactor', async () => {
    const editor = vscode.window.activeTextEditor;
    if (!editor) return;

    const filePath = editor.document.uri.fsPath;
    const content = editor.document.getText();

    // Send context and goal to Copilot SDK
    const response = await sdk.execute({
      goal: "Refactor this file by splitting oversized functions",
      context: {
        filePath,
        language: "typescript",
        content
      },
      tools: ["read_file", "edit_file", "run_terminal_command", "run_tests"],
      maxSteps: 15
    });

    // Process the agentic execution trace
    for (const step of response.steps) {
      vscode.window.showInformationMessage(`Agent: ${step.description}`);
      
      if (step.tool === 'edit_file') {
        const success = await safeEdit(step.parameters.path, step.parameters.newContent);
        if (!success) {
          await revertChanges(step.parameters.path);
          break;
        }
      }
    }

    vscode.window.showInformationMessage('Agent execution finished.');
  });

  context.subscriptions.push(disposable);
}

async function safeEdit(path: string, newContent: string): Promise<boolean> {
  // Implement backup + atomic write logic here
  return true; // placeholder
}

async function revertChanges(path: string) {
  // git checkout or backup restore
}

Pro tip: Keep the agent’s reasoning visible. Always ask the SDK to return a structured trace with description, tool, parameters, reasoning, and confidence.

Validate

Run this checklist after every major change:

• Agent outputs a clear plan before any file modification
• Every edit is preceded by a git stash or backup
• Relevant tests are executed after each edit
• Failures trigger automatic revert
• All agent actions are logged to an agent-trace.log file
• Human confirmation gate exists for high-risk operations (delete, large refactors)
• Extension works in a clean VS Code instance with only your extension enabled

Create a test-fixtures/ folder with deliberately messy functions and verify the agent can improve them without breaking behavior.

Ship it safely

1. Publish the extension to the VS Code Marketplace as an internal extension first (use Azure DevOps or GitHub Packages).
2. Add a COPILOT_AGENT_MODE=review environment variable that forces every edit to open a diff for human approval.
3. Implement usage telemetry (anonymized) so you can measure success rate and common failure modes.
4. Document permission model clearly in the README. Users must understand exactly what the agent is allowed to do.
5. Create a rollback plan: include a “Disable Agent” command that removes all agent-generated changes from the last 24 hours.

Pitfalls and guardrails

What if the agent gets stuck in a loop?

Set a hard maxSteps (recommended: 12–18) and add a timeout. In the prompt, explicitly say: “If you cannot make progress in 3 consecutive steps, stop and ask the human for guidance.”

What if the agent makes a destructive change?

Always implement safeEdit() with a backup. Use vscode.workspace.applyEdit() with proper undo support. Never allow rm or git reset --hard without explicit human confirmation.

What if tests are flaky?

Require at least two successful test runs before considering the change “green.” Add a testRetry: 2 parameter to your test runner tool.

What if the Copilot SDK response is non-deterministic?

Seed the request with a sessionId and store the full execution trace. For production use cases, consider temperature=0 and add a validation layer that checks whether the output matches the original plan.

What if I don’t have access to the Copilot SDK yet?

The SDK is currently rolling out to select partners and enterprise customers. Check the official GitHub documentation and join the waitlist if necessary. Many of the patterns above still work with Cursor, Claude Projects, or custom tool-calling wrappers while you wait.

What to do next

• Ship v0.1 of your agent extension to 5 internal users this week
• Measure task completion rate and average steps per task
• Add one new capability (e.g., “add unit tests” or “update API client after OpenAPI change”)
• Convert your best agent prompts into reusable “skills” that other developers can discover
• Explore multi-agent collaboration (planner agent + executor agent)

The era of copy-pasting AI output is ending. Builders who learn to design reliable execution interfaces today will ship dramatically faster tomorrow.

Sources

• Original announcement: https://github.blog/ai-and-ml/github-copilot/the-era-of-ai-as-text-is-over-execution-is-the-new-interface/
• Microsoft and Anthropic Copilot Cowork partnership coverage
• GitHub Copilot SDK documentation (check for latest authentication and tool definitions)

(Word count: 1,248)