Skip to main content

Get Started with Microsoft Agent Framework GitHub Copilot

Please install this package via pip:

pip install agent-framework-github-copilot

GitHub Copilot Agent

The GitHub Copilot agent enables integration with GitHub Copilot, allowing you to interact with Copilot's agentic capabilities through the Agent Framework.

Context providers and function middleware

Context providers can contribute messages, instructions, and tools to a run. GitHubCopilotAgent supports agent middleware, but the SDK owns its tool-calling loop and does not run Agent Framework function middleware. If a context provider contributes function middleware through SessionContext.extend_middleware(), the run raises MiddlewareException before creating or resuming an SDK session or registering its tools. This applies to both response modes and to RawGitHubCopilotAgent.

Use Agent with a chat client when provider-contributed function middleware is required.

Tool approval (approval_mode="always_require")

The GitHub Copilot SDK owns the tool-calling loop for this provider, so approval for custom function tools is enforced through the SDK's native pre-execution hook rather than the standard Agent Framework approval round-trip.

When you register a FunctionTool declared with approval_mode="always_require" and you do not supply your own on_pre_tool_use hook, GitHubCopilotAgent installs a default on_pre_tool_use hook that returns "ask" for that tool and defers (None) for all other tools. The "ask" decision routes to your on_permission_request handler, where you approve or deny the call. Other session hooks, such as on_post_tool_use or on_session_start, are preserved alongside this default approval hook:

from agent_framework import tool
from agent_framework.github import GitHubCopilotAgent, GitHubCopilotOptions
from copilot.session import PermissionHandler


@tool(approval_mode="always_require")
def delete_file(path: str) -> str:
    """Delete a file."""
    ...


agent = GitHubCopilotAgent(
    tools=[delete_file],
    # The "ask" decision is routed here; approve or deny the call.
    default_options=GitHubCopilotOptions(on_permission_request=PermissionHandler.approve_all),
)

⚠️ If you provide your own on_pre_tool_use hook, it takes precedence and the agent does not install its default approval hook. In that case you are fully responsible for enforcing approval — including for any approval_mode="always_require" tool (e.g. by returning a "deny" or "ask" decision). The agent logs a warning naming any approval-required tool that your hook must handle.

Note: with the default (deny-all) permission handler, an always_require tool is denied unless you wire an approving on_permission_request.

Approving for the rest of the session

PermissionDecisionApproveForSession scopes its approval with either an approval (tool prompts) or a domain (URL prompts). Both are optional, so a bare PermissionDecisionApproveForSession() carries no scope at all and the Copilot CLI cannot interpret it.

GitHubCopilotAgent therefore scopes such a decision automatically when the request provides a structured session approval — a shell prompt becomes an approval for that prompt's command identifiers, an MCP prompt an approval for that server and tool, and so on:

from copilot.generated.rpc import PermissionDecisionApproveForSession


def on_permission_request(request, invocation):
    # Scoped to `request` automatically; approves that kind of call for the whole session.
    return PermissionDecisionApproveForSession()

The decision is only ever narrowed, never widened. A bare decision for a URL prompt is downgraded to a single-use approval because the framework cannot safely infer the Copilot CLI's exact URL permission scope. The same downgrade occurs when the prompt reports that it cannot offer session-scoped approval (can_offer_session_approval=False), or the request kind has no session-scoped approval at all (such as a hook prompt). A warning is logged in each case. Pass an explicit approval= or domain= when you want to approve a specific scope for the session — decisions that already specify a scope are forwarded unchanged.

Deprecated: on_function_approval

The on_function_approval callback is deprecated. It still works (and is still enforced inside the tool handler for backward compatibility), but it emits a DeprecationWarning and will be removed in a future version. Migrate to the on_pre_tool_use + on_permission_request model described above. When on_function_approval is set, it gates always_require tools and the default ask-hook is not installed. It is mutually exclusive with on_pre_tool_use — setting both (whether at construction or per run) raises ValueError.

Workspace-driven session options

on_permission_request and on_pre_tool_use gate tool calls. They do not cover configuration the CLI picks up from the working directory it runs in, which is a separate mechanism with its own switches.

So that a session behaves the same way in every checkout, GitHubCopilotAgent leaves the following off by default:

Option Default Effect when enabled
enable_file_hooks False The CLI loads file hooks from the working directory's .github/hooks/ and runs the commands they define, independently of the tool-approval path.

Opt in per agent or per run when your workflow needs the checkout to drive the session:

agent = GitHubCopilotAgent(
    default_options=GitHubCopilotOptions(enable_file_hooks=True),
)

Only enable these for a working directory whose contents you trust to act on the host.

To make the default visible rather than silent, the agent logs a warning through the agent_framework.github_copilot logger the first time it starts a session in a working directory that defines hooks it is not loading. See github_copilot_with_file_hooks.py for a runnable example.

MCP configuration and session lifetime

Constructor default_options provide SDK session defaults. Per-run options override the corresponding defaults for that request, including mcp_servers. Reusing an AgentSession with a service_session_id resumes SDK/CLI-owned service-session state. Forwarding a narrower MCP configuration, such as changing a server's tools from ["*"] to [], is not an authorization or revocation guarantee for capabilities already resident in that session. Enforce authorization at the MCP service/tool boundary.

Use a fresh service session when narrowing configured capabilities: create fresh_session = agent.create_session(), then pass it to await agent.run("Start a new conversation", session=fresh_session, options=restricted_options), where restricted_options contains the narrowed mcp_servers configuration. The new session has no service_session_id; do not copy the previous service-session state or reuse its SDK session_id in constructor or per-run options. A fresh session starts a new conversation rather than continuing the previous one.

Metadata

Release files for agent-framework-github-copilot 2.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agent-framework-github-copilot 2.1.2
File Size Uploaded Provenance Actions
agent_framework_github_copilot-2.1.2.tar.gz 27.5 kB Without provenance Details for agent_framework_github_copilot-2.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agent-framework-github-copilot 2.1.2
File Interpreter ABI Platform Actions
agent_framework_github_copilot-2.1.2-py3-none-any.whl Python 3 none any Details for agent_framework_github_copilot-2.1.2-py3-none-any.whl

Total release size: 53.6 kB

Release files / agent_framework_github_copilot-2.1.2.tar.gz

Download URL agent_framework_github_copilot-2.1.2.tar.gz
Size 27.5 kB
Tags Source
SHA-256 checksum
How to use checksums
0ab9bccd8bcb59218809efe5ebca1947801fbe14365749f9ab2918697004918d
BLAKE2b-256 checksum
How to use checksums
dd0d26c661044c857539d2fef6c4f2178d8c7f25ab6b438bd2a47df3d6137f68
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via RestSharp/106.13.0.0

Release files / agent_framework_github_copilot-2.1.2-py3-none-any.whl

Download URL agent_framework_github_copilot-2.1.2-py3-none-any.whl
Size 26.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fad02edb73c86e8ceba63deb61a52911af2710a02f902492b8ada324e078a154
BLAKE2b-256 checksum
How to use checksums
ea8a09708d68a8f4ed2cc306310386fb5e10eb4619352438dc1e9e938b4b4f60
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via RestSharp/106.13.0.0

Security for agent-framework-github-copilot 2.1.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.1.2 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page