Epic: Copilot SDK Integration for Advanced Agentic Workflows

[Mossaka]

Overview

The GitHub Copilot SDK (announced Jan 14, 2026) represents a fundamental shift from invocation-based to library-based AI integration. While the current Copilot CLI integration excels at simple, linear workflows, the SDK enables sophisticated agentic patterns that are currently impossible.

Background

Current State (Copilot CLI):

• External process invocation via GitHub Actions
• One-way command execution (request → response)
• File-based logs, no programmatic access to session state
• MCP servers via JSON config files
• Limited to single-pass execution
• Post-execution analysis only

SDK Capabilities:

• Language-native libraries (Node.js, Python, Go, .NET)
• JSON-RPC bidirectional communication with CLI in server mode
• Multi-turn conversation management with persistent state
• Custom tool execution with callbacks
• Real-time event streaming
• Programmatic lifecycle control

Why This Matters

The SDK unblocks 8 critical scenarios for gh-aw:

1. Long-Running Agentic Workflows - Multi-day operations with pause/resume
2. Conversational PR Reviews - Iterative review based on developer responses
3. Adaptive Test Generation - Generate, run, refine based on coverage
4. Human-in-the-Loop Approvals - Security scans with graduated permissions
5. Multi-Agent Collaboration - Specialist agents working together
6. Intelligent CI/CD - Smart test selection and flaky test handling
7. Cross-Repository Operations - Synchronized changes across microservices
8. Cost-Aware Execution - Real-time budget controls and throttling

Architecture Comparison

Current (CLI):

GitHub Actions → Copilot CLI (black box) → Logs

Proposed (SDK):

GitHub Actions → SDK Library → JSON-RPC → Copilot CLI (server mode)
                    ↓
            Application Logic
            - Session management
            - Event handling
            - Custom tools
            - Control flow

Implementation Approach

Three potential paths forward:

1. Hybrid Model - CLI for simple workflows, SDK for advanced
2. SDK-First Migration - New engine implementation with CLI fallback
3. Graduated Adoption - Phased rollout starting with specific features

Success Criteria

• SDK engine implementation in pkg/workflow/copilot_sdk_engine.go
• Support for multi-turn conversations with state retention
• Custom inline tool definitions with callbacks
• Real-time event streaming and handling
• Backward compatibility with existing CLI workflows
• Documentation and migration guide
• Example workflows demonstrating SDK capabilities

Child Issues

This epic tracks the following implementation work:

• Design session state management for SDK workflows #10155 - Prototype Copilot SDK integration POC
• Implement custom inline tool integration for SDK #10156 - Design session state management for SDK workflows
• Add real-time event handling and streaming support #10157 - Implement custom inline tool integration for SDK
• Enable multi-agent orchestration and collaboration #10158 - Add real-time event handling and streaming support
• Create documentation and migration guide for SDK workflows #10159 - Enable multi-agent orchestration and collaboration
• Build testing and validation framework for SDK workflows #10160 - Implement Copilot SDK engine in gh-aw compiler
• Make all fields optional in missing_data safe output tool #10161 - Create documentation and migration guide for SDK workflows
• Update security-fix-pr workflow to use camelCase parameter for GitHub MCP server #10162 - Build testing and validation framework for SDK workflows

References

• Copilot SDK Announcement
• Copilot SDK Repository
• Community Request (Issue #321)

---

Status: 🔍 Research complete, ready for implementation
Priority: High - Enables next-generation agentic workflows
Complexity: High - Requires architectural changes and backward compatibility
Estimated Effort: 8-12 weeks total

[pelikhan]

issue monster: ignore this issue and sub issue. it's not ready.