# How to Embed GitHub Copilot Agentic Workflows in Applications

> Learn to embed GitHub Copilot agentic workflows in your applications. Instantiate CopilotClient, configure sessions with custom tools, and handle events to drive your app logic.

- Repository: [GitHub/copilot-sdk](https://github.com/github/copilot-sdk)
- Tags: how-to-guide
- Published: 2026-06-06

---

**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)](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)](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)](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`](https://github.com/github/copilot-sdk/blob/main/nodejs/docs/agent-author.md) for the programming model:

```typescript
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)](https://github.com/github/copilot-sdk/blob/main/python/README.md):

```python
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)](https://github.com/github/copilot-sdk/blob/main/go/README.md):

```go
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)](https://github.com/github/copilot-sdk/blob/main/dotnet/README.md):

```csharp
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)](https://github.com/github/copilot-sdk/blob/main/java/README.md):

```java
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)](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)](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.