copilot-sdk-python-distilled

name	copilot-sdk-python-distilled
description	Use when building Python agents with the GitHub Copilot SDK, especially for programmatic agent creation, skills, goals, tools, hooks, and MCP integration.

GitHub Copilot SDK for Python (distilled)

Use this skill when you need to create Copilot-powered Python agents programmatically, attach tools, assign skills, encode goals, and orchestrate multi-agent workflows.

Core concepts

• The GitHub Copilot SDK exposes a production-tested agent runtime behind the Copilot CLI.
• In Python, the main entry points are CopilotClient, create_session(), and a session object with send_and_wait(), send(), on(), and lifecycle helpers.
• The SDK supports tools, hooks, MCP servers, custom agents, skills, streaming events, memory, providers, and telemetry.

Installation

pip install github-copilot-sdk

Optional telemetry support:

pip install "github-copilot-sdk[telemetry]"

Authentication and runtime

Basic client example:

import asyncio
from copilot import CopilotClient
from copilot.session import PermissionHandler

async def main():
    client = CopilotClient()
    await client.start()

    session = await client.create_session(
        on_permission_request=PermissionHandler.approve_all,
        model="gpt-5",
    )

    response = await session.send_and_wait("What is 2 + 2?")
    print(response.data.content)

    await client.stop()

asyncio.run(main())

Streaming events

from copilot import CopilotClient
from copilot.session_events import SessionEventType

client = CopilotClient()
await client.start()

session = await client.create_session(
    on_permission_request=PermissionHandler.approve_all,
    model="gpt-5",
    streaming=True,
)


def handle_event(event):
    if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA:
        print(event.data.delta_content, end="", flush=True)
    elif event.type == SessionEventType.SESSION_IDLE:
        print()

session.on(handle_event)
await session.send_and_wait("Tell me a short joke")
await client.stop()

Tools

from pydantic import BaseModel, Field
from copilot import CopilotClient, define_tool
from copilot.session import PermissionHandler

class LookupIssueParams(BaseModel):
    id: str = Field(description="Issue identifier")

@define_tool(description="Fetch issue details from our tracker")
async def lookup_issue(params: LookupIssueParams) -> str:
    return f"Issue {params.id} resolved"

async def main():
    async with CopilotClient() as client:
        async with await client.create_session(
            on_permission_request=PermissionHandler.approve_all,
            model="gpt-5",
            tools=[lookup_issue],
        ) as session:
            await session.send("Look up issue #123")

asyncio.run(main())

Hooks

async def on_pre_tool_use(input_data, invocation):
    print(f"About to run tool: {input_data['toolName']}")
    return {"permissionDecision": "allow"}

session = await client.create_session(
    on_permission_request=PermissionHandler.approve_all,
    model="gpt-5",
    hooks={"on_pre_tool_use": on_pre_tool_use},
)

MCP servers

MCP servers can be attached to a session either as a remote HTTP endpoint or as a local stdio process. Pick the form that matches where your server runs.

Remote HTTP example:

session = await client.create_session(
    on_permission_request=PermissionHandler.approve_all,
    model="gpt-5",
    mcp_servers={
        "github": {
            "type": "http",
            "url": "https://api.githubcopilot.com/mcp/",
            "tools": ["*"],
        }
    },
)

Local stdio example:

session = await client.create_session(
    on_permission_request=PermissionHandler.approve_all,
    model="gpt-5",
    mcp_servers={
        "local-tools": {
            "type": "stdio",
            "command": "python",
            "args": ["-m", "my_mcp_server"],
            "tools": ["read_file", "write_file"],
        }
    },
)

Use the smallest tool list that you need, and pass any required auth, environment variables, or startup arguments through the server configuration.

Custom agents

session = await client.create_session(
    on_permission_request=PermissionHandler.approve_all,
    model="gpt-4.1",
    custom_agents=[
        {
            "name": "researcher",
            "display_name": "Research Agent",
            "description": "Explores codebases and answers questions using read-only tools",
            "tools": ["grep", "glob", "view"],
            "prompt": "You are a research assistant. Analyze code and answer questions. Do not modify any files.",
        },
        {
            "name": "editor",
            "display_name": "Editor Agent",
            "description": "Makes targeted code changes",
            "tools": ["view", "edit", "bash"],
            "prompt": "You are a code editor. Make minimal, surgical changes to files as requested.",
        },
    ],
)

Skills

Skills are reusable prompt modules loaded from directories containing SKILL.md files.

session = await client.create_session(
    on_permission_request=PermissionHandler.approve_all,
    model="gpt-4.1",
    skill_directories=["./skills"],
)

Assign skills to agents with skills:

session = await client.create_session(
    on_permission_request=PermissionHandler.approve_all,
    model="gpt-4.1",
    skill_directories=["./skills"],
    custom_agents=[
        {
            "name": "security-auditor",
            "description": "Security-focused code reviewer",
            "prompt": "Focus on OWASP Top 10 vulnerabilities.",
            "skills": ["security-scan", "dependency-check"],
        }
    ],
)

Goals and goal-driven agents

The SDK does not define a special goal field. Encode goals in the agent prompt or in system_message.

async def build_agent(goal: str, tools: list | None = None):
    client = CopilotClient()
    await client.start()
    session = await client.create_session(
        on_permission_request=PermissionHandler.approve_all,
        model="gpt-4.1",
        system_message={
            "mode": "append",
            "content": f"You are a goal-driven agent. Goal: {goal}",
        },
        tools=tools or [],
    )
    return client, session

Programmatic agent factory pattern

async def make_specialist_agent(name: str, goal: str, skills: list[str] | None = None):
    client = CopilotClient()
    await client.start()

    session = await client.create_session(
        on_permission_request=PermissionHandler.approve_all,
        model="gpt-4.1",
        skill_directories=["./skills"],
        system_message={
            "mode": "append",
            "content": f"Goal: {goal}",
        },
        custom_agents=[
            {
                "name": name,
                "display_name": name.replace("-", " ").title(),
                "description": f"Specialist agent for: {goal}",
                "prompt": f"You are a specialist agent focused on {goal}.",
                "skills": skills or [],
            }
        ],
        agent=name,
    )
    return client, session

Practical guidance

• Keep each agent focused on one responsibility.
• Restrict tools with tools=[...] to enforce least privilege.
• Assign skills explicitly.
• Encode goals in the prompt or system message.
• Use hooks for auditing and approval.
• Prefer custom agents over one giant monolithic session when roles differ.