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_usehook, 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 anyapproval_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_requiretool is denied unless you wire an approvingon_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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.