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

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, 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, 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:

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():

// 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 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 – 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 – 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 – Provides the complete reference catalog for all streaming event types emitted during the agentic workflow.
• 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. 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.

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