How to Embed GitHub Copilot Agentic Workflows in Applications

You can embed GitHub Copilot agentic workflows by instantiating a CopilotClient that manages the CLI process lifecycle, configuring sessions with custom tools and permission handlers, and reacting to streamed events like session.idle and assistant.turn_start to drive application logic.

The GitHub Copilot SDK (github/copilot-sdk) exposes the same agent runtime that powers the Copilot CLI, allowing you to integrate LLM-driven tool-use loops directly into your applications. By leveraging JSON-RPC communication between your code and the bundled Copilot CLI binary, you can orchestrate complex agentic workflows across Node.js, Python, Go, .NET, Java, or Rust environments.

Understanding the Agent Runtime Architecture

The Copilot SDK manages the CLI process lifecycle and communicates with it over JSON-RPC, as documented in [README.md](https://github.com/github/copilot-sdk/blob/main/README.md#L46-L55) (lines 46-55). The architecture follows this data flow:

Your Application
        ↓
   SDK client
        ↓ JSON-RPC
   Copilot CLI (server mode)
        ↓
   LLM (e.g. GPT-4.1)

The CLI runs the tool-use loop (the "agent loop"), detailed in [docs/features/agent-loop.md](https://github.com/github/copilot-sdk/blob/main/docs/features/agent-loop.md#L21-L30) (lines 21-30).

1. session.send({ prompt }) transmits a user message.
2. The CLI sends the full conversation history to the LLM.
3. If the LLM requests tools, the CLI executes them, feeds results back, and repeats.
4. When the loop ends, the CLI emits session.idle; optionally, session.task_complete may be emitted if the model signals task completion (lines 12-18).

The LLM decides whether to continue looping or return a final answer, while your application reacts to the resulting events.

Implementation Steps to Embed Agentic Workflows

To implement a workflow according to the github/copilot-sdk source code:

1. Choose a language SDK – Node.js/TypeScript, Python, Go, .NET, Java, or Rust.
2. Create a CopilotClient and start the CLI – Most SDKs bundle the binary automatically.
3. Configure a session – Specify the model, custom agents, tools, and permission handlers.
4. Send a prompt – Use send for streaming or sendAndWait to block until session.idle.
5. Listen to events – React to assistant.turn_start, tool.execution_*, subagent.*, and session.idle.

The SDK supports custom agents (specialized sub-agents with distinct prompts and tool sets) and orchestration via Fleet mode for parallel execution, as described in [docs/features/custom-agents.md](https://github.com/github/copilot-sdk/blob/main/docs/features/custom-agents.md#L1-L4) (lines 1-4).

Code Examples by Language

Node.js / TypeScript

Reference nodejs/docs/agent-author.md for the programming model:

import { CopilotClient, defineTool, approveAll } from "@github/copilot-sdk";
import { z } from "zod";

const client = new CopilotClient();
await client.start();   // launches the bundled Copilot CLI

// Optional custom tool
const grepTool = defineTool("grep", {
  description: "Searches files using a regex pattern",
  parameters: z.object({ pattern: z.string() }),
  handler: async ({ pattern }) => {
    // Your implementation – e.g., spawn `git grep`
    return { matches: [] };
  },
});

const session = await client.createSession({
  model: "gpt-4.1",
  tools: [grepTool],
  onPermissionRequest: approveAll,
});

const response = await session.sendAndWait({
  prompt: "Explain how the authentication flow works in this repo",
});
console.log("Final answer:", response.data.content);

Python

As shown in [python/README.md](https://github.com/github/copilot-sdk/blob/main/python/README.md):

import asyncio
from copilot import CopilotClient, PermissionDecisionApproveOnce

async def main():
    client = CopilotClient()
    await client.start()          # starts bundled Copilot CLI

    # Create a session with a permission handler that auto‑approves once

    session = await client.create_session(
        model="gpt-4.1",
        on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),
    )

    # Send a prompt and wait for the agent to finish

    response = await session.send_and_wait(
        "Generate a README for this project"
    )
    print("Agent reply:", response.content)

asyncio.run(main())

Go

From [go/README.md](https://github.com/github/copilot-sdk/blob/main/go/README.md):

package main

import (
	"context"
	"fmt"
	copilot "github.com/github/copilot-sdk/go"
	"github.com/github/copilot-sdk/go/rpc"
)

func main() {
	ctx := context.Background()
	client := copilot.NewClient(nil)
	client.Start(ctx)

	session, err := client.CreateSession(ctx, &copilot.SessionConfig{
		Model: "gpt-4.1",
		OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (rpc.PermissionDecision, error) {
			return &rpc.PermissionDecisionApproveOnce{}, nil
		},
	})
	if err != nil {
		panic(err)
	}

	resp, err := session.SendAndWait(ctx, copilot.MessageOptions{
		Prompt: "Write a function that validates JWT tokens",
	})
	if err != nil {
		panic(err)
	}
	fmt.Println("Agent output:", resp.Content)
}

.NET (C#)

From [dotnet/README.md](https://github.com/github/copilot-sdk/blob/main/dotnet/README.md):

using System;
using System.Threading.Tasks;
using GitHub.Copilot;
using GitHub.Copilot.Rpc;

await using var client = new CopilotClient();
await client.StartAsync();

var session = await client.CreateSessionAsync(new SessionConfig
{
    Model = "gpt-4.1",
    OnPermissionRequest = PermissionHandler.ApproveAll,
});

var response = await session.SendAndWaitAsync(new MessageOptions
{
    Prompt = "Create a unit test for the AuthService class"
});

Console.WriteLine($"Agent says: {response.Content}");

Java

From [java/README.md](https://github.com/github/copilot-sdk/blob/main/java/README.md):

import com.github.copilot.CopilotClient;
import com.github.copilot.rpc.*;

try (var client = new CopilotClient()) {
    client.start().get();

    var session = client.createSession(
        new SessionConfig()
            .setModel("gpt-4.1")
            .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
    ).get();

    var response = session.sendAndWait(
        new MessageOptions().setPrompt("Summarize the security model of this repository")
    ).get();

    System.out.println("Agent reply: " + response.getContent());
}

Summary

• The Copilot SDK exposes the same agent runtime as the Copilot CLI via JSON-RPC communication with a managed CLI process.
• The tool-use loop handles LLM conversation, tool execution, and emits session.idle when complete.
• You can embed GitHub Copilot agentic workflows by creating a CopilotClient, configuring sessions with models and permission handlers, and subscribing to events.
• Support for custom agents and Fleet mode enables complex orchestration and parallel execution.
• All major languages (Node.js, Python, Go, .NET, Java) follow the same pattern: start client, create session, send prompts, handle events.

Frequently Asked Questions

What is the Copilot agent runtime?

The Copilot agent runtime is the same execution environment that powers the Copilot CLI, exposed through the SDKs. It manages the lifecycle of LLM conversations, handles the tool-use loop, and coordinates between your application and underlying models like GPT-4.1 via JSON-RPC.

How does the tool-use loop work?

According to [docs/features/agent-loop.md](https://github.com/github/copilot-sdk/blob/main/docs/features/agent-loop.md), the tool-use loop begins when you call session.send(). The CLI sends the conversation history to the LLM, which may request tool executions. The CLI executes these tools, feeds results back to the model, and repeats until the model stops requesting tools, finally emitting session.idle or session.task_complete.

Can I define custom agents?

Yes. As documented in [docs/features/custom-agents.md](https://github.com/github/copilot-sdk/blob/main/docs/features/custom-agents.md), you can define specialized sub-agents with their own prompts and tool sets. The SDK also supports Fleet mode for orchestrating multiple agents in parallel.

How do I handle permissions?

The SDK requires explicit permission handlers via OnPermissionRequest (or language-specific equivalents like on_permission_request). You can implement custom logic or use built-in helpers like approveAll (TypeScript), PermissionDecisionApproveOnce (Python/Go), or PermissionHandler.APPROVE_ALL (Java) to automatically approve tool executions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}