agent-framework-github-copilot 2.0.0__tar.gz → 2.0.2__tar.gz

{agent_framework_github_copilot-2.0.0 → agent_framework_github_copilot-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-framework-github-copilot
-Version: 2.0.0
+Version: 2.0.2
 Summary: GitHub Copilot integration for Microsoft Agent Framework.
 Author-email: Microsoft <af-support@microsoft.com>
 Requires-Python: >=3.11
@@ -15,8 +15,8 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 License-File: LICENSE
-Requires-Dist: agent-framework-core>=1.15.0,<2
-Requires-Dist: github-copilot-sdk==1.0.11; python_version >= '3.11'
+Requires-Dist: agent-framework-core>=1.21.0,<2
+Requires-Dist: github-copilot-sdk>=1.0.16,<2.0; python_version >= '3.11'
 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

{agent_framework_github_copilot-2.0.0 → agent_framework_github_copilot-2.0.2}/agent_framework_github_copilot/_agent.py

@@ -9,7 +9,17 @@ import json
 import logging
 import sys
 import warnings
-from collections.abc import AsyncIterable, Awaitable, Callable, Mapping, MutableMapping, Sequence
+import weakref
+from collections.abc import (
+    AsyncGenerator,
+    AsyncIterable,
+    Awaitable,
+    Callable,
+    Collection,
+    Mapping,
+    MutableMapping,
+    Sequence,
+)
 from pathlib import Path
 from typing import Any, ClassVar, Generic, Literal, TypedDict, cast, overload
 from urllib.parse import urlparse
@@ -23,6 +33,7 @@ from agent_framework import (
     BaseAgent,
     Content,
     ContextProvider,
+    FunctionInvocationContext,
     HistoryProvider,
     Message,
     ResponseStream,
@@ -181,6 +192,21 @@ async def _resolve_function_approval(
 
 logger = logging.getLogger("agent_framework.github_copilot")
 
+
+def _provider_service_session_state_keys(agent: object, client: object | None) -> frozenset[str]:
+    """Return provider-owned session-state keys declared by the Copilot agent or client."""
+    keys: set[str] = set()
+    for owner in (agent, client):
+        declared = getattr(owner, "service_session_state_keys", ())
+        if isinstance(declared, (list, tuple, set, frozenset)):
+            keys.update(key for key in cast(Collection[Any], declared) if isinstance(key, str))
+    return frozenset(keys)
+
+
+# One lock per (CopilotClient, service session ID), shared across agents that share a client.
+# Entries disappear once no run holds or awaits the lock.
+_SESSION_RUN_LOCKS: weakref.WeakValueDictionary[tuple[int, str], asyncio.Lock] = weakref.WeakValueDictionary()
+
 _MCP_TOOL_MESSAGE = (
     "MCP server '{name}' cannot be passed to GitHubCopilotAgent as a tool: the Copilot SDK "
     "connects to MCP servers itself, so a framework-managed MCPTool would keep none of its "
@@ -813,6 +839,7 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
         session: AgentSession | None = None,
         middleware: Sequence[AgentMiddlewareTypes] | None = None,
         options: OptionsT | None = None,
+        function_invocation_kwargs: Mapping[str, Any] | None = None,
         **kwargs: Any,
     ) -> Awaitable[AgentResponse]: ...
 
@@ -825,6 +852,7 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
         session: AgentSession | None = None,
         middleware: Sequence[AgentMiddlewareTypes] | None = None,
         options: OptionsT | None = None,
+        function_invocation_kwargs: Mapping[str, Any] | None = None,
         **kwargs: Any,
     ) -> ResponseStream[AgentResponseUpdate, AgentResponse]: ...
 
@@ -836,6 +864,7 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
         session: AgentSession | None = None,
         middleware: Sequence[AgentMiddlewareTypes] | None = None,
         options: OptionsT | None = None,
+        function_invocation_kwargs: Mapping[str, Any] | None = None,
         **kwargs: Any,
     ) -> Awaitable[AgentResponse] | ResponseStream[AgentResponseUpdate, AgentResponse]:
         """Get a response from the agent.
@@ -854,6 +883,9 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
                 compatibility; pass middleware via :class:`GitHubCopilotAgent` which
                 forwards it through :class:`AgentTelemetryLayer`.
             options: Runtime options (model, timeout, etc.).
+            function_invocation_kwargs: Keyword arguments forwarded to tool invocations.
+                Tools receive them through ``FunctionInvocationContext.kwargs`` when they
+                declare a ``FunctionInvocationContext`` parameter.
             kwargs: Additional keyword arguments for compatibility with the shared agent
                 interface (e.g. compaction_strategy, tokenizer). Not used by this agent.
 
@@ -887,11 +919,22 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
                 return AgentResponse.from_updates(updates)
 
             return ResponseStream(
-                self._stream_updates(messages=messages, session=session, options=options, _ctx_holder=ctx_holder),
+                self._stream_updates(
+                    messages=messages,
+                    session=session,
+                    options=options,
+                    function_invocation_kwargs=function_invocation_kwargs,
+                    _ctx_holder=ctx_holder,
+                ),
                 finalizer=_finalize,
                 result_hooks=[_after_run_hook],
             )
-        return self._run_impl(messages=messages, session=session, options=options)
+        return self._run_impl(
+            messages=messages,
+            session=session,
+            options=options,
+            function_invocation_kwargs=function_invocation_kwargs,
+        )
 
     @staticmethod
     def _parse_usage_details_from_copilot(data: AssistantUsageData) -> UsageDetails | None:
@@ -920,6 +963,7 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
         *,
         session: AgentSession | None = None,
         options: OptionsT | None = None,
+        function_invocation_kwargs: Mapping[str, Any] | None = None,
     ) -> AgentResponse:
         """Non-streaming implementation of run."""
         if not self._started:
@@ -952,7 +996,6 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
             existing = list(opts.get("tools") or [])
             opts["tools"] = existing + list(session_context.tools)
 
-        copilot_session = await self._get_or_create_session(session, streaming=False, runtime_options=opts)
         usage_details: UsageDetails | None = None
         finish_reason: str | None = None
         model: str | None = None
@@ -986,14 +1029,20 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
             prompt = "\n".join(session_context.instructions) + "\n" + prompt
         attachments = self._prepare_attachments_for_copilot(context_messages)
 
-        unsubscribe = copilot_session.on(usage_event_handler)
-        try:
-            mark_feature_used(FeatureIndex.GITHUB_COPILOT)
-            response_event = await copilot_session.send_and_wait(prompt, attachments=attachments, timeout=timeout)
-        except Exception as ex:
-            raise AgentException(f"GitHub Copilot request failed: {ex}") from ex
-        finally:
-            unsubscribe()
+        async with self._session_run_scope(
+            session,
+            streaming=False,
+            runtime_options=opts,
+            function_invocation_kwargs=function_invocation_kwargs,
+        ) as copilot_session:
+            unsubscribe = copilot_session.on(usage_event_handler)
+            try:
+                mark_feature_used(FeatureIndex.GITHUB_COPILOT)
+                response_event = await copilot_session.send_and_wait(prompt, attachments=attachments, timeout=timeout)
+            except Exception as ex:
+                raise AgentException(f"GitHub Copilot request failed: {ex}") from ex
+            finally:
+                unsubscribe()
 
         response_messages: list[Message] = []
         response_id: str | None = None
@@ -1032,6 +1081,7 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
         *,
         session: AgentSession | None = None,
         options: OptionsT | None = None,
+        function_invocation_kwargs: Mapping[str, Any] | None = None,
         _ctx_holder: dict[str, Any] | None = None,
     ) -> AsyncIterable[AgentResponseUpdate]:
         """Internal method to stream updates from GitHub Copilot.
@@ -1042,6 +1092,7 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
         Keyword Args:
             session: The conversation session associated with the message(s).
             options: Runtime options (model, timeout, etc.).
+            function_invocation_kwargs: Keyword arguments forwarded to tool invocations.
             _ctx_holder: Internal dict populated with session_context and session
                 so that the caller (via a ResponseStream result_hook) can run
                 after_run providers without duplicating the updates buffer.
@@ -1081,12 +1132,6 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
             existing = list(opts.get("tools") or [])
             opts["tools"] = existing + list(session_context.tools)
 
-        copilot_session = await self._get_or_create_session(session, streaming=True, runtime_options=opts)
-
-        if _ctx_holder is not None:
-            _ctx_holder["session_context"] = session_context
-            _ctx_holder["session"] = session
-
         # Build the prompt from the full session context so provider-injected messages are included.
         context_messages = session_context.get_messages(include_input=True)
         prompt = "\n".join([message.text for message in context_messages])
@@ -1172,18 +1217,28 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
                 error_msg = error_data.message or "Unknown error"
                 queue.put_nowait(AgentException(f"GitHub Copilot session error: {error_msg}"))
 
-        unsubscribe = copilot_session.on(event_handler)
+        async with self._session_run_scope(
+            session,
+            streaming=True,
+            runtime_options=opts,
+            function_invocation_kwargs=function_invocation_kwargs,
+        ) as copilot_session:
+            if _ctx_holder is not None:
+                _ctx_holder["session_context"] = session_context
+                _ctx_holder["session"] = session
 
-        try:
-            mark_feature_used(FeatureIndex.GITHUB_COPILOT)
-            await copilot_session.send(prompt, attachments=attachments)
+            unsubscribe = copilot_session.on(event_handler)
 
-            while (item := await queue.get()) is not None:
-                if isinstance(item, Exception):
-                    raise item
-                yield item
-        finally:
-            unsubscribe()
+            try:
+                mark_feature_used(FeatureIndex.GITHUB_COPILOT)
+                await copilot_session.send(prompt, attachments=attachments)
+
+                while (item := await queue.get()) is not None:
+                    if isinstance(item, Exception):
+                        raise item
+                    yield item
+            finally:
+                unsubscribe()
 
     async def _run_before_providers(
         self,
@@ -1301,40 +1356,77 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
     def _prepare_tools(
         self,
         tools: Sequence[ToolTypes | CopilotTool],
+        *,
+        agent_session: AgentSession | None = None,
+        function_invocation_kwargs: Mapping[str, Any] | None = None,
     ) -> list[CopilotTool]:
         """Convert Agent Framework tools to Copilot SDK tools.
 
         Args:
             tools: List of Agent Framework tools.
 
+        Keyword Args:
+            agent_session: The conversation session, exposed to tools through their
+                ``FunctionInvocationContext``.
+            function_invocation_kwargs: Keyword arguments forwarded to tool invocations.
+
         Returns:
             List of Copilot SDK tools.
         """
         copilot_tools: list[CopilotTool] = []
+        parent_service_session_state_keys = _provider_service_session_state_keys(self, self._client)
 
         for tool in tools:
             if isinstance(tool, CopilotTool):
                 copilot_tools.append(tool)
             elif isinstance(tool, FunctionTool):
-                copilot_tools.append(self._tool_to_copilot_tool(tool))
+                copilot_tools.append(
+                    self._tool_to_copilot_tool(
+                        tool,
+                        agent_session=agent_session,
+                        function_invocation_kwargs=function_invocation_kwargs,
+                        parent_service_session_state_keys=parent_service_session_state_keys,
+                    )
+                )
             elif isinstance(tool, MutableMapping):
                 copilot_tools.append(tool)  # type: ignore[arg-type]
             # Note: Other tool types (e.g., dict-based hosted tools) are skipped
 
         return copilot_tools
 
-    def _tool_to_copilot_tool(self, ai_func: FunctionTool) -> CopilotTool:
+    def _tool_to_copilot_tool(
+        self,
+        ai_func: FunctionTool,
+        *,
+        agent_session: AgentSession | None = None,
+        function_invocation_kwargs: Mapping[str, Any] | None = None,
+        parent_service_session_state_keys: frozenset[str] = frozenset(),
+    ) -> CopilotTool:
         """Convert an FunctionTool to a Copilot SDK tool.
 
+        Each invocation receives a ``FunctionInvocationContext`` carrying the run's
+        ``function_invocation_kwargs`` and ``agent_session``, so tools that declare a
+        ``FunctionInvocationContext`` parameter can read them the same way they do
+        with a chat-client-backed agent.
+
         Approval for tools declared with ``approval_mode="always_require"`` is normally
         enforced by the Copilot SDK's native ``on_pre_tool_use`` hook (see
         :meth:`_build_session_hooks`). When the deprecated ``on_function_approval``
         callback is configured instead, approval is enforced inside this handler for
         backward compatibility. (``on_function_approval`` and ``on_pre_tool_use`` are
         mutually exclusive, so only one mechanism is ever active.)
+
+        Args:
+            ai_func: Agent Framework function tool to convert.
+
+        Keyword Args:
+            agent_session: Parent agent session passed to the tool.
+            function_invocation_kwargs: Runtime keyword arguments forwarded to the tool.
+            parent_service_session_state_keys: Provider-owned state declared by the parent agent and client.
         """
         approval_handler = self._function_approval_handler
         enforce = approval_handler is not None and ai_func.approval_mode == "always_require"
+        runtime_kwargs = dict(function_invocation_kwargs) if function_invocation_kwargs is not None else {}
 
         async def handler(invocation: ToolInvocation) -> ToolResult:
             args: dict[str, Any] = invocation.arguments or {}
@@ -1353,11 +1445,22 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
                         result_type="failure",
                         error="approval_denied",
                     )
+                context = FunctionInvocationContext(
+                    function=ai_func,
+                    arguments=args,
+                    session=agent_session,
+                    kwargs=runtime_kwargs,
+                    parent_service_session_state_keys=parent_service_session_state_keys,
+                )
                 if ai_func.input_model:
                     args_instance = ai_func.input_model(**args)
-                    result = await ai_func.invoke(arguments=args_instance)
+                    result = await ai_func.invoke(
+                        arguments=args_instance, context=context, tool_call_id=invocation.tool_call_id or None
+                    )
                 else:
-                    result = await ai_func.invoke(arguments=args)
+                    result = await ai_func.invoke(
+                        arguments=args, context=context, tool_call_id=invocation.tool_call_id or None
+                    )
                 rich = [c for c in result if c.type in ("data", "uri")]
                 if rich:
                     logger.warning(
@@ -1471,11 +1574,73 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
 
         return {"on_pre_tool_use": default_pre_tool_use}
 
+    def _session_run_lock(self, service_session_id: str) -> asyncio.Lock:
+        """Return the lock that serializes runs on one Copilot service session."""
+        key = (id(self._client), service_session_id)
+        lock = _SESSION_RUN_LOCKS.get(key)
+        if lock is None:
+            lock = asyncio.Lock()
+            _SESSION_RUN_LOCKS[key] = lock
+        return lock
+
+    @contextlib.asynccontextmanager
+    async def _session_run_scope(
+        self,
+        agent_session: AgentSession,
+        *,
+        streaming: bool,
+        runtime_options: dict[str, Any],
+        function_invocation_kwargs: Mapping[str, Any] | None,
+    ) -> AsyncGenerator[CopilotSession]:
+        """Open the Copilot session for one run and hold it exclusively until the run ends.
+
+        The Copilot SDK keeps a single session object per service session ID and
+        re-registers tools on it on every resume, dispatching tool calls by session ID.
+        Tool handlers capture the run's ``function_invocation_kwargs`` and session, so
+        an overlapping resume would let one run's tool calls execute with another run's
+        context. Runs on the same service session are therefore serialized.
+
+        Args:
+            agent_session: The conversation session.
+
+        Keyword Args:
+            streaming: Whether to enable streaming for the session.
+            runtime_options: Runtime options from run that take precedence.
+            function_invocation_kwargs: Keyword arguments forwarded to tool invocations.
+
+        Yields:
+            The created or resumed CopilotSession.
+        """
+        lock: asyncio.Lock | None = None
+        service_session_id = agent_session.service_session_id
+        if isinstance(service_session_id, str):
+            resume_lock = self._session_run_lock(service_session_id)
+            await resume_lock.acquire()
+            lock = resume_lock
+        try:
+            copilot_session = await self._get_or_create_session(
+                agent_session,
+                streaming=streaming,
+                runtime_options=runtime_options,
+                function_invocation_kwargs=function_invocation_kwargs,
+            )
+            if lock is None:
+                # A newly created service session ID is not known to any other run yet,
+                # so this acquire never waits.
+                create_lock = self._session_run_lock(copilot_session.session_id)
+                await create_lock.acquire()
+                lock = create_lock
+            yield copilot_session
+        finally:
+            if lock is not None:
+                lock.release()
+
     async def _get_or_create_session(
         self,
         agent_session: AgentSession,
         streaming: bool = False,
         runtime_options: dict[str, Any] | None = None,
+        function_invocation_kwargs: Mapping[str, Any] | None = None,
     ) -> CopilotSession:
         """Get an existing session or create a new one for the session.
 
@@ -1483,6 +1648,7 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
             agent_session: The conversation session.
             streaming: Whether to enable streaming for the session.
             runtime_options: Runtime options from run that take precedence.
+            function_invocation_kwargs: Keyword arguments forwarded to tool invocations.
 
         Returns:
             A CopilotSession instance.
@@ -1500,9 +1666,20 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
                     raise AgentException(
                         "GitHubCopilotAgent expects a string service_session_id for session resumption."
                     )
-                return await self._resume_session(service_session_id, streaming, runtime_options)
+                return await self._resume_session(
+                    service_session_id,
+                    streaming,
+                    runtime_options,
+                    agent_session=agent_session,
+                    function_invocation_kwargs=function_invocation_kwargs,
+                )
 
-            session = await self._create_session(streaming, runtime_options)
+            session = await self._create_session(
+                streaming,
+                runtime_options,
+                agent_session=agent_session,
+                function_invocation_kwargs=function_invocation_kwargs,
+            )
             agent_session.service_session_id = session.session_id
             return session
         except Exception as ex:
@@ -1533,6 +1710,9 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
         self,
         streaming: bool,
         runtime_options: dict[str, Any] | None,
+        *,
+        agent_session: AgentSession | None = None,
+        function_invocation_kwargs: Mapping[str, Any] | None = None,
     ) -> dict[str, Any]:
         """Assemble keyword arguments for ``create_session`` / ``resume_session``.
 
@@ -1551,6 +1731,11 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
             streaming: Whether to enable streaming for the session.
             runtime_options: Runtime options that take precedence over default_options.
 
+        Keyword Args:
+            agent_session: The conversation session, exposed to tools through their
+                ``FunctionInvocationContext``.
+            function_invocation_kwargs: Keyword arguments forwarded to tool invocations.
+
         Returns:
             The keyword arguments to splat into the SDK session factory.
         """
@@ -1565,7 +1750,15 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
         # and flattens tool-collection wrappers, which can otherwise hide an MCPTool.
         all_tools = normalize_tools(list(self._tools or []) + list(kwargs.get("tools") or []))
         _reject_mcp_tools(all_tools)
-        kwargs["tools"] = self._prepare_tools(all_tools) if all_tools else None
+        kwargs["tools"] = (
+            self._prepare_tools(
+                all_tools,
+                agent_session=agent_session,
+                function_invocation_kwargs=function_invocation_kwargs,
+            )
+            if all_tools
+            else None
+        )
 
         kwargs["streaming"] = streaming
         # model may already be present from per-run options (merged above); otherwise fall
@@ -1606,23 +1799,40 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
         self,
         streaming: bool,
         runtime_options: dict[str, Any] | None = None,
+        *,
+        agent_session: AgentSession | None = None,
+        function_invocation_kwargs: Mapping[str, Any] | None = None,
     ) -> CopilotSession:
         """Create a new Copilot session.
 
         Args:
             streaming: Whether to enable streaming for the session.
             runtime_options: Runtime options that take precedence over default_options.
+
+        Keyword Args:
+            agent_session: The conversation session, exposed to tools.
+            function_invocation_kwargs: Keyword arguments forwarded to tool invocations.
         """
         if not self._client:
             raise RuntimeError("GitHub Copilot client not initialized. Call start() first.")
 
-        return await self._client.create_session(**self._build_session_kwargs(streaming, runtime_options))
+        return await self._client.create_session(
+            **self._build_session_kwargs(
+                streaming,
+                runtime_options,
+                agent_session=agent_session,
+                function_invocation_kwargs=function_invocation_kwargs,
+            )
+        )
 
     async def _resume_session(
         self,
         session_id: str,
         streaming: bool,
         runtime_options: dict[str, Any] | None = None,
+        *,
+        agent_session: AgentSession | None = None,
+        function_invocation_kwargs: Mapping[str, Any] | None = None,
     ) -> CopilotSession:
         """Resume an existing Copilot session by ID.
 
@@ -1630,11 +1840,23 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
             session_id: The session ID to resume.
             streaming: Whether to enable streaming for the session.
             runtime_options: Runtime options that take precedence over default_options.
+
+        Keyword Args:
+            agent_session: The conversation session, exposed to tools.
+            function_invocation_kwargs: Keyword arguments forwarded to tool invocations.
         """
         if not self._client:
             raise RuntimeError("GitHub Copilot client not initialized. Call start() first.")
 
-        return await self._client.resume_session(session_id, **self._build_session_kwargs(streaming, runtime_options))
+        return await self._client.resume_session(
+            session_id,
+            **self._build_session_kwargs(
+                streaming,
+                runtime_options,
+                agent_session=agent_session,
+                function_invocation_kwargs=function_invocation_kwargs,
+            ),
+        )
 
 
 class GitHubCopilotAgent(  # type: ignore[misc]

{agent_framework_github_copilot-2.0.0 → agent_framework_github_copilot-2.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ description = "GitHub Copilot integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.11"
-version = "2.0.0"
+version = "2.0.2"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -22,8 +22,8 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.15.0,<2",
-    "github-copilot-sdk==1.0.11; python_version >= '3.11'",
+    "agent-framework-core>=1.21.0,<2",
+    "github-copilot-sdk>=1.0.16,<2.0; python_version >= '3.11'",
 ]
 
 [tool.uv]