GitHub Copilot integration for Microsoft Agent Framework

Common errors

• Copilot coding agent tasks may fail because the agent runtime will be unable to communicate with GitHub systems.

  cause Network configuration changes for the Copilot coding agent (effective February 27, 2026) mean it connects to new, plan-specific hostnames. If your network (e.g., for self-hosted runners) doesn't allow these, communication will fail.
  fix Update your network configuration (firewalls, proxy settings, etc.) to allow outgoing connections to the new GitHub Copilot hostnames: `api.business.githubcopilot.com`, `api.enterprise.githubcopilot.com`, and `api.individual.githubcopilot.com`, depending on the Copilot plan(s) in use.

• ModuleNotFoundError: No module named 'agent_framework.github'

  cause The `agent-framework-github-copilot` package, or the encompassing `agent-framework` package, has not been installed correctly, or the Python environment is not configured to find it.
  fix Ensure the package is installed using `pip install agent-framework-github-copilot`. If you intend to use the full framework, `pip install agent-framework` installs all sub-packages, including the GitHub Copilot integration.

• Visual Studio: 'parts of my existing code get unexpectedly deleted, and the output is often incomplete — leaving the file in a broken, unbuildable state.'

  cause The GitHub Copilot Agent in Visual Studio can sometimes interfere with existing code, resulting in incomplete outputs or corrupted file structures during code generation or editing, which leads to build errors.
  fix While a direct fix for this behavior is not yet available, it is a known issue. It is recommended to save your work frequently, use version control to track changes, and meticulously review any code generated or modified by the Copilot Agent in Visual Studio. If issues occur, manually revert or correct the code.

Warnings

• breaking Version 1.0.0 introduced breaking changes related to `ToolInvocation` and `ToolResult` types, requiring updates to agent implementations. Additionally, dependency floors now mandate released `>=1.0.0,<2` packages, breaking compatibility with older Release Candidate (RC) installs.
  Fix: Review the official migration guide for Agent Framework 1.0.0 to adapt agent code to the new `ToolInvocation` and `ToolResult` types. Ensure all Agent Framework related packages are updated to their stable 1.x versions.
• gotcha The GitHub Copilot CLI must be installed and authenticated separately for the `agent-framework-github-copilot` to function. This is a crucial prerequisite for utilizing the library's features.
  Fix: Follow the official GitHub Copilot CLI installation and authentication guides. This typically involves installing the CLI and logging in via `gh auth login` or similar commands, potentially configuring environment variables for authentication tokens.
• breaking Effective February 27, 2026, the Copilot coding agent will use subscription-based network routing, connecting to different hostnames (e.g., `api.business.githubcopilot.com`, `api.enterprise.githubcopilot.com`, `api.individual.githubcopilot.com`). Self-hosted runners or those with Azure private networking need to allow these new hostnames.
  Fix: Identify repositories using Copilot coding agent with affected runner types (check `.github/workflows/copilot-setup-steps.yml`). Review and update network configurations to ensure connectivity to the new, plan-specific Copilot hostnames by the specified date.
• gotcha The Copilot Agent may struggle to obtain results from shell commands that have longer execution times, potentially limiting its effectiveness for complex or time-consuming tasks.
  Fix: For tasks involving long-running shell commands, consider breaking them down into smaller, quicker steps, or use alternative methods for result capture if the agent's direct execution proves unreliable. Be mindful of this limitation when designing agent workflows.
• gotcha Users have reported issues in Visual Studio where the GitHub Copilot Agent can cause code loss or introduce build-breaking errors due to incomplete or improperly applied code generation/editing.
  Fix: Exercise caution when using the Copilot Agent for extensive code modifications or refactoring in Visual Studio. Regularly commit changes, use version control, and carefully review agent-generated or edited code before saving. This issue is acknowledged by Microsoft and is under investigation.

Install

• pip install agent-framework-github-copilot Install package

Imports

• GitHubCopilotAgent

  from agent_framework.github import GitHubCopilotAgent

• GitHubCopilotOptions

  from agent_framework.github import GitHubCopilotOptions

Quickstart

This quickstart demonstrates how to initialize and run a basic GitHub Copilot Agent. It requires the GitHub Copilot CLI to be installed and authenticated separately. The agent is created with default options and then used to process a simple query.

import asyncio
import os
from agent_framework.github import GitHubCopilotAgent, GitHubCopilotOptions

async def main():
    # Ensure GitHub Copilot CLI is installed and authenticated.
    # For this example, we assume authentication is handled externally or via environment variables.
    # Replace with your actual authentication token or method if needed.
    # os.environ['GITHUB_TOKEN'] = os.environ.get('GITHUB_TOKEN', 'YOUR_GITHUB_TOKEN')
    
    options = GitHubCopilotOptions()
    agent = GitHubCopilotAgent(options)

    print("Asking the GitHub Copilot Agent: What is a Python list comprehension?")
    response = await agent.run_async("What is a Python list comprehension?")
    print(f"Agent Response: {response.output}")

if __name__ == "__main__":
    asyncio.run(main())