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.

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, using the request that triggered it — a shell prompt becomes an approval for that prompt's command identifiers, an MCP prompt an approval for that server and tool, a URL prompt an approval for that URL's domain, 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. 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), the decision is downgraded to a single-use approval and a warning is logged. Pass an explicit approval= or domain= when you want to approve something other than the request being handled — 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.

Metadata

Release files for agent-framework-github-copilot 2.1.1

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.1
File Size Uploaded Provenance Actions
agent_framework_github_copilot-2.1.1.tar.gz 26.8 kB Without provenance Details for agent_framework_github_copilot-2.1.1.tar.gz

Built distribution (wheel)

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

Total release size: 52.7 kB

Release files / agent_framework_github_copilot-2.1.1.tar.gz

Download URL agent_framework_github_copilot-2.1.1.tar.gz
Size 26.8 kB
Tags Source
SHA-256 checksum
How to use checksums
1b1bdcf69e926e8a62bffc952ce288b810750cf4b458790210718de068a71adf
BLAKE2b-256 checksum
How to use checksums
5006be1ab3680c223ab49a5acc0ac519bc5541d58837f1942c48155e038c3964
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.1-py3-none-any.whl

Download URL agent_framework_github_copilot-2.1.1-py3-none-any.whl
Size 26.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8abd0c7da6424ba5d7214b5b8d8f4dda31be14b0c682b9ff81d13c605562e94d
BLAKE2b-256 checksum
How to use checksums
382204a33b298a95052f1a975a260cba1168ad82b16d449f53963a47d1ccdff7
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.1

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.1 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