Metadata-Version: 2.5
Name: agent-framework-github-copilot
Version: 2.1.2
Summary: GitHub Copilot integration for Microsoft Agent Framework.
Author-email: Microsoft <af-support@microsoft.com>
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Classifier: License :: OSI Approved :: MIT License
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Typing :: Typed
License-File: LICENSE
Requires-Dist: agent-framework-core>=1.22.0,<2
Requires-Dist: github-copilot-sdk>=1.0.16,<2.0
Project-URL: homepage, https://aka.ms/agent-framework
Project-URL: issues, https://github.com/microsoft/agent-framework/issues
Project-URL: release_notes, https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true
Project-URL: source, https://github.com/microsoft/agent-framework/tree/main/python
Import-Name: agent_framework_github_copilot

# Get Started with Microsoft Agent Framework GitHub Copilot

Please install this package via pip:

```bash
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:

```python
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:

```python
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:

```python
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`](../../samples/02-agents/providers/github_copilot/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.

