# What Are Agentic Workflows in GitHub Copilot? Understanding the SDK's Autonomous Loop

> Discover agentic workflows in GitHub Copilot. Learn how the SDK enables autonomous loops for LLMs to plan, use tools, and complete tasks.

- Repository: [GitHub/copilot-sdk](https://github.com/github/copilot-sdk)
- Tags: deep-dive
- Published: 2026-06-06

---

**Agentic workflows in GitHub Copilot are autonomous thinking-and-acting loops where the LLM plans, invokes tools, inspects results, and re-plans until completing a task, orchestrated by the Copilot CLI and exposed through the SDK as discrete events.**

Agentic workflows form the execution backbone of the `github/copilot-sdk`, enabling applications to delegate complex multi-step tasks to an autonomous agent. Unlike simple chat completions, these workflows allow the model to iteratively call tools, process results, and refine its approach without manual orchestration. This article examines how the agentic loop functions at the architectural level and how developers interact with it through the SDK's session management API.

## The Architecture of Agentic Workflows in GitHub Copilot

### The Four-Step Thinking-and-Acting Loop

According to the source code in [`docs/features/agent-loop.md`](https://github.com/github/copilot-sdk/blob/main/docs/features/agent-loop.md), when your application sends a prompt to a Copilot session, the SDK forwards the request to the Copilot CLI over JSON-RPC. The CLI then executes an agentic tool-use loop consisting of four distinct phases:

1. **LLM Call**: The model receives the full conversation history, including the system prompt, user message, and previous tool results, then generates a response.
2. **Tool Request Evaluation**: If the response contains a `toolRequests` payload, the CLI executes the requested tools such as `read_file`, `git.diff`, or custom tools defined by your application.
3. **Result Integration**: The tool results are appended to the conversation context and fed back into the next LLM call.
4. **Iteration**: Steps 2-3 repeat until the model stops requesting tools and emits a final text response.

### Turns and Event Emission

Each iteration of this loop constitutes a **turn**—a single LLM API call exposed through the SDK as `assistant.turn_start` and `assistant.turn_end` events. The workflow concludes with a `session.idle` event, signaling that the agent has finished processing the current user message. As implemented in [`nodejs/src/session.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/session.ts), these events allow your application to track progress, display tool execution status, or implement custom logging.

## Implementing Agentic Workflows with the Copilot SDK

Your code does not implement the loop itself. Instead, you create a session using `CopilotClient` and let the CLI handle the orchestration while listening to streaming events for visibility.

### Basic Implementation with sendAndWait

The simplest approach uses `session.sendAndWait()` to block until the agentic workflow completes:

```typescript
import { CopilotClient } from '@github/copilot-sdk';

// Create client and session
const client = new CopilotClient();
const session = await client.createSession({ model: 'gpt-4' });

// Send prompt and await autonomous completion
const msg = await session.sendAndWait({
  prompt: `Refactor the function in src/utils.ts to be async`,
});
console.log('Assistant answer:', msg?.data.content);

await session.disconnect();

```

### Streaming Events for Real-Time Feedback

For applications requiring progress visibility, subscribe to events before calling `session.send()`:

```typescript
// Listen to tool execution lifecycle
session.on('tool.execution_start', e => {
  console.log('Tool started:', e.data.toolName);
});
session.on('tool.execution_complete', e => {
  console.log('Tool finished, result size:', e.data.result.length);
});

// Stream partial responses
session.on('assistant.message', e => {
  console.log('Partial reply:', e.data.content);
});

await session.send({ prompt: 'Explain the GitHub Copilot architecture' });

```

Key event types defined in [`docs/features/streaming-events.md`](https://github.com/github/copilot-sdk/blob/main/docs/features/streaming-events.md) include:

- `assistant.turn_start` / `assistant.turn_end`: Mark the beginning and end of each LLM turn.
- `tool.execution_start` / `tool.execution_complete`: Signal when tools begin and finish executing.
- `session.idle`: Indicates the agentic workflow has concluded and the session is ready for new input.

## Key Source Files for Agentic Workflow Implementation

Understanding the agentic workflow requires familiarity with these specific files in the `github/copilot-sdk` repository:

- **[`docs/features/agent-loop.md`](https://github.com/github/copilot-sdk/blob/main/docs/features/agent-loop.md)** – Contains the high-level architectural documentation including the mermaid diagram that visualizes the tool-use loop and the flow of individual turns.
- **[`nodejs/src/session.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/session.ts)** – Implements the concrete SDK methods including `send()`, `sendAndWait()`, event handling logic, and the emission of the `session.idle` completion signal.
- **[`docs/features/streaming-events.md`](https://github.com/github/copilot-sdk/blob/main/docs/features/streaming-events.md)** – Provides the complete reference catalog for all streaming event types emitted during the agentic workflow.
- **[`nodejs/src/generated/rpc.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/generated/rpc.ts)** – Defines the JSON-RPC method signatures used by the SDK to communicate with the Copilot CLI, such as `session.send` and `session.abort`.

## Summary

- Agentic workflows in GitHub Copilot implement an autonomous loop where the LLM iteratively plans, executes tools, and re-plans based on results until reaching a final answer.
- The **Copilot CLI** serves as the orchestrator running the loop, while the **SDK** acts as a thin transport layer forwarding messages over JSON-RPC and surfacing events.
- Each iteration is called a **turn**, exposed via `assistant.turn_start` and `assistant.turn_end` events, with `session.idle` marking workflow completion.
- Developers interact with workflows through `client.createSession()`, `session.sendAndWait()`, or `session.send()` with event listeners, without manually orchestrating tool calls.
- Session persistence is supported via `client.resumeSession()`, allowing agentic workflows to continue across application restarts.

## Frequently Asked Questions

### What triggers a tool request in an agentic workflow?

A tool request triggers when the LLM response contains a `toolRequests` payload. The Copilot CLI detects this payload during the agentic loop and executes the specified tools—such as `read_file` or `git.diff`—before feeding the results back into the next LLM call. This process continues until the model produces a final response without tool requests.

### How does the SDK communicate with the Copilot CLI?

The SDK communicates with the Copilot CLI over JSON-RPC, as defined in [`nodejs/src/generated/rpc.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/generated/rpc.ts). The SDK forwards session creation requests, prompts, and abort signals to the CLI, which then manages the actual agentic loop execution and streams events back through the same RPC connection.

### What is the difference between send() and sendAndWait()?

`session.sendAndWait()` blocks execution until the entire agentic workflow completes and returns the final message containing the assistant's response. In contrast, `session.send()` initiates the workflow but returns immediately, requiring you to listen to streaming events—such as `assistant.message` and `session.idle`—to capture the response and completion status.

### Can agentic sessions be resumed across application restarts?

Yes, the SDK supports session persistence through `client.resumeSession()`. Session state remains on disk after calling `session.disconnect()`, allowing you to resume an existing agentic workflow later by referencing the session ID while maintaining conversation context and tool execution history.