agent-framework-orchestrations 1.3.0__tar.gz → 1.3.2__tar.gz

{agent_framework_orchestrations-1.3.0 → agent_framework_orchestrations-1.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: agent-framework-orchestrations
-Version: 1.3.0
+Version: 1.3.2
 Summary: Orchestration patterns for Microsoft Agent Framework. Includes SequentialBuilder, ConcurrentBuilder, HandoffBuilder, GroupChatBuilder, and MagenticBuilder.
 Author-email: Microsoft <af-support@microsoft.com>
 Requires-Python: >=3.10
@@ -14,6 +14,7 @@ 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.19.0,<2
@@ -21,6 +22,7 @@ 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_orchestrations
 
 # Agent Framework Orchestrations
 

{agent_framework_orchestrations-1.3.0 → agent_framework_orchestrations-1.3.2}/agent_framework_orchestrations/_concurrent.py

@@ -18,7 +18,7 @@ from agent_framework._workflows._workflow_context import WorkflowContext
 from typing_extensions import Never
 
 from ._feature_usage import FeatureIndex
-from ._orchestration_request_info import AgentApprovalExecutor
+from ._orchestration_request_info import AgentApprovalExecutor, validate_request_info_filter
 from ._participant_output_config import (
     UNSET,
     _coalesce_output_from,  # pyright: ignore[reportPrivateUsage]
@@ -172,6 +172,10 @@ class _CallbackAggregator(Executor):
             else:
                 ret = await asyncio.to_thread(self._callback, results)
 
+        # Async callable objects and wrappers returning a coroutine are not coroutine functions
+        if inspect.isawaitable(ret):
+            ret = await ret
+
         # If the callback returned a value, finalize the workflow with it
         if ret is not None:
             await ctx.yield_output(ret)
@@ -382,6 +386,11 @@ class ConcurrentBuilder:
             else:
                 raise TypeError(f"Participants must be SupportsAgentRun or Executor instances. Got {type(p).__name__}.")
 
+        if self._request_info_enabled:
+            validate_request_info_filter(
+                self._request_info_filter,
+                [resolve_agent_id(p) for p in participants if not isinstance(p, Executor)],
+            )
         return executors
 
     def build(self) -> Workflow:

{agent_framework_orchestrations-1.3.0 → agent_framework_orchestrations-1.3.2}/agent_framework_orchestrations/_group_chat.py

@@ -51,7 +51,7 @@ from ._base_group_chat_orchestrator import (
     TerminationCondition,
 )
 from ._feature_usage import FeatureIndex
-from ._orchestration_request_info import AgentApprovalExecutor
+from ._orchestration_request_info import AgentApprovalExecutor, validate_request_info_filter
 from ._orchestrator_helpers import clean_conversation_for_handoff, extract_markdown_fence_bodies
 from ._participant_output_config import (
     UNSET,
@@ -519,8 +519,15 @@ class AgentBasedGroupChatOrchestrator(BaseGroupChatOrchestrator):
             # Parse and validate the structured output
             agent_orchestration_output = self._parse_agent_output(agent_response)
 
-            if not agent_orchestration_output.terminate and not agent_orchestration_output.next_speaker:
-                raise ValueError("next_speaker must be provided if not terminating the conversation.")
+            if not agent_orchestration_output.terminate:
+                next_speaker = agent_orchestration_output.next_speaker
+                if not next_speaker:
+                    raise ValueError("next_speaker must be provided if not terminating the conversation.")
+                if next_speaker not in self._participant_registry.participants:
+                    raise ValueError(
+                        f"Orchestrator agent selected unknown participant '{next_speaker}'. "
+                        f"Valid participants: {', '.join(self._participant_registry.participants)}."
+                    )
 
             return agent_orchestration_output
 
@@ -1023,6 +1030,11 @@ class GroupChatBuilder:
                     f"Participants must be SupportsAgentRun or Executor instances. Got {type(participant).__name__}."
                 )
 
+        if self._request_info_enabled:
+            validate_request_info_filter(
+                self._request_info_filter,
+                [resolve_agent_id(p) for p in participants if not isinstance(p, Executor)],
+            )
         return executors
 
     def build(self) -> Workflow:

{agent_framework_orchestrations-1.3.0 → agent_framework_orchestrations-1.3.2}/agent_framework_orchestrations/_handoff.py

@@ -32,6 +32,7 @@ Key properties:
 import inspect
 import json
 import logging
+import re
 import sys
 from collections.abc import Awaitable, Callable, Mapping, Sequence
 from copy import deepcopy
@@ -122,9 +123,17 @@ class HandoffConfiguration:
         return hash(self.target_id)
 
 
+_INVALID_TOOL_NAME_CHARACTERS = re.compile(r"[^a-zA-Z0-9_-]")
+_MAX_TOOL_NAME_LENGTH = 64
+
+
 def get_handoff_tool_name(target_id: str) -> str:
-    """Get the standardized handoff tool name for a given target agent ID."""
-    return f"handoff_to_{target_id}"
+    """Get the standardized handoff tool name for a given target agent ID.
+
+    Characters that model providers reject in tool names, such as spaces, are replaced with underscores,
+    and the name is cut to the 64 characters that providers allow.
+    """
+    return f"handoff_to_{_INVALID_TOOL_NAME_CHARACTERS.sub('_', target_id)}"[:_MAX_TOOL_NAME_LENGTH]
 
 
 HANDOFF_FUNCTION_RESULT_KEY = "handoff_to"
@@ -266,6 +275,9 @@ class HandoffAgentExecutor(AgentExecutor):
             autonomous_mode_prompt: Prompt to provide to the agent when continuing in autonomous mode.
                                     This will guide the agent in the absence of user input.
             autonomous_mode_turn_limit: Maximum number of autonomous turns before requesting user input.
+                                        ``0`` returns control to the user as soon as the agent responds
+                                        without a handoff; the default limit is only used when this is
+                                        left as ``None``.
         """
         self._auto_handoff_middleware = _AutoHandoffMiddleware(handoffs)
         cloned_agent = self._prepare_agent_with_handoffs(agent, handoffs, self._auto_handoff_middleware)
@@ -279,7 +291,9 @@ class HandoffAgentExecutor(AgentExecutor):
         # Autonomous mode members
         self._autonomous_mode = autonomous_mode
         self._autonomous_mode_prompt = autonomous_mode_prompt or _AUTONOMOUS_MODE_DEFAULT_PROMPT
-        self._autonomous_mode_turn_limit = autonomous_mode_turn_limit or _DEFAULT_AUTONOMOUS_TURN_LIMIT
+        self._autonomous_mode_turn_limit = (
+            _DEFAULT_AUTONOMOUS_TURN_LIMIT if autonomous_mode_turn_limit is None else autonomous_mode_turn_limit
+        )
         self._autonomous_mode_turns = 0
 
     def _prepare_agent_with_handoffs(
@@ -372,6 +386,7 @@ class HandoffAgentExecutor(AgentExecutor):
                     f"Handoff tool name '{handoff_tool.name}' conflicts with existing tool."
                     "Please rename the existing tool or modify the target agent ID to avoid conflicts."
                 )
+            existing_names.add(handoff_tool.name)
             new_tools.append(handoff_tool)
 
         if new_tools:
@@ -928,6 +943,8 @@ class HandoffBuilder:
                      in autonomous mode. If not provided, a default prompt will be used.
             turn_limits: Optional mapping of agent identifiers/factory names to maximum number of autonomous turns
                          before returning control to the user. If not provided, a default turn limit will be used.
+                         A limit of ``0`` disables autonomous continuation for that agent instead of falling back
+                         to the default.
         """
         self._autonomous_mode = True
         self._autonomous_mode_prompts = prompts or {}

{agent_framework_orchestrations-1.3.0 → agent_framework_orchestrations-1.3.2}/agent_framework_orchestrations/_magentic.py

@@ -427,8 +427,20 @@ def _extract_json(text: str) -> dict[str, Any]:
             raise ValueError("No JSON object found.")
         depth = 0
         end = None
+        in_string = False
+        escaped = False
         for i, ch in enumerate(text[start:], start=start):
-            if ch == "{":
+            # Braces inside string values, such as code in an instruction, do not count.
+            if in_string:
+                if escaped:
+                    escaped = False
+                elif ch == "\\":
+                    escaped = True
+                elif ch == '"':
+                    in_string = False
+            elif ch == '"':
+                in_string = True
+            elif ch == "{":
                 depth += 1
             elif ch == "}":
                 depth -= 1
@@ -517,7 +529,7 @@ class MagenticManagerBase(ABC):
 
 
 class StandardMagenticManager(MagenticManagerBase):
-    """Standard Magentic manager that performs real LLM calls via a Agent.
+    """Standard Magentic manager that performs real LLM calls via an Agent.
 
     The manager constructs prompts that mirror the original Magentic One orchestration:
     - Facts gathering
@@ -724,21 +736,37 @@ class StandardMagenticManager(MagenticManagerBase):
         # Include full context to help the model decide current stage, with small retry loop
         attempts = 0
         last_error: Exception | None = None
+        unknown_speaker_ledger: MagenticProgressLedger | None = None
         while attempts < self.progress_ledger_retry_count:
             raw = await self._complete([*magentic_context.chat_history, user_message])
             try:
                 ledger_dict = _extract_json(raw.text)
-                return _coerce_model(MagenticProgressLedger, ledger_dict)
+                ledger = _coerce_model(MagenticProgressLedger, ledger_dict)
             except Exception as ex:
                 last_error = ex
-                attempts += 1
-                logger.warning(
-                    f"Progress ledger JSON parse failed (attempt {attempts}/{self.progress_ledger_retry_count}): {ex}"
-                )
-                if attempts < self.progress_ledger_retry_count:
-                    # brief backoff before next try
-                    await asyncio.sleep(0.25 * attempts)
+                unknown_speaker_ledger = None
+            else:
+                next_speaker = ledger.next_speaker.answer
+                if (
+                    ledger.is_request_satisfied.answer
+                    or not isinstance(next_speaker, str)
+                    or next_speaker in agent_names
+                ):
+                    return ledger
+                # Retry an unknown name, but keep the ledger so running out of attempts ends the run
+                # through the orchestrator's invalid speaker handling instead of another reset.
+                unknown_speaker_ledger = ledger
+                last_error = ValueError(f"Unknown next speaker '{next_speaker}'. Valid names: {names_csv}.")
+            attempts += 1
+            logger.warning(
+                f"Progress ledger attempt failed ({attempts}/{self.progress_ledger_retry_count}): {last_error}"
+            )
+            if attempts < self.progress_ledger_retry_count:
+                # brief backoff before next try
+                await asyncio.sleep(0.25 * attempts)
 
+        if unknown_speaker_ledger is not None:
+            return unknown_speaker_ledger
         raise RuntimeError(
             f"Progress ledger parse failed after {self.progress_ledger_retry_count} attempt(s): {last_error}"
         )
@@ -1374,8 +1402,9 @@ class MagenticAgentExecutor(AgentExecutor):
         # Request into related
         self._pending_agent_requests.clear()
         self._pending_responses_to_agent.clear()
+        self._pending_request_order.clear()
         # Reset sessions
-        self._agent_thread = self._agent.create_session()
+        self._session = self._agent.create_session()
 
 
 #  endregion Magentic Agent Executor

{agent_framework_orchestrations-1.3.0 → agent_framework_orchestrations-1.3.2}/agent_framework_orchestrations/_orchestration_request_info.py

@@ -41,6 +41,24 @@ def resolve_request_info_filter(agents: list[str | SupportsAgentRun] | None) ->
     return result
 
 
+def validate_request_info_filter(request_info_filter: set[str] | None, agent_ids: list[str]) -> None:
+    """Raise if the request info filter names an agent that is not a participant.
+
+    Args:
+        request_info_filter: Agent IDs passed to ``with_request_info(agents=...)``. Empty or None means all agents.
+        agent_ids: IDs of the agent participants in the orchestration.
+
+    Raises:
+        ValueError: If a name in the filter does not match any agent participant.
+    """
+    unknown = sorted((request_info_filter or set()) - set(agent_ids))
+    if unknown:
+        raise ValueError(
+            f"with_request_info() names agents that are not agent participants: "
+            f"{', '.join(repr(name) for name in unknown)}. Agent participants: {', '.join(agent_ids)}."
+        )
+
+
 @dataclass
 class AgentRequestInfoResponse:
     """Response containing additional information requested from users for agents.

{agent_framework_orchestrations-1.3.0 → agent_framework_orchestrations-1.3.2}/agent_framework_orchestrations/_sequential.py

@@ -32,7 +32,7 @@ from agent_framework._workflows._workflow import Workflow
 from agent_framework._workflows._workflow_context import WorkflowContext
 
 from ._feature_usage import FeatureIndex
-from ._orchestration_request_info import AgentApprovalExecutor
+from ._orchestration_request_info import AgentApprovalExecutor, validate_request_info_filter
 from ._participant_output_config import (
     UNSET,
     _coalesce_output_from,  # pyright: ignore[reportPrivateUsage]
@@ -230,6 +230,11 @@ class SequentialBuilder:
             else:
                 raise TypeError(f"Participants must be SupportsAgentRun or Executor instances. Got {type(p).__name__}.")
 
+        if self._request_info_enabled:
+            validate_request_info_filter(
+                self._request_info_filter,
+                [resolve_agent_id(p) for p in participants if not isinstance(p, Executor)],
+            )
         return executors
 
     def build(self) -> Workflow:

{agent_framework_orchestrations-1.3.0 → agent_framework_orchestrations-1.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ description = "Orchestration patterns for Microsoft Agent Framework. Includes Se
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.3.0"
+version = "1.3.2"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -20,6 +20,7 @@ classifiers = [
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
   "Typing :: Typed",
 ]
 dependencies = [
@@ -92,5 +93,5 @@ help = "Run the default unit test suite for this package."
 cmd = 'pytest -m "not integration" --cov=agent_framework_orchestrations --cov-report=term-missing:skip-covered -n auto --dist worksteal tests'
 
 [build-system]
-requires = ["flit-core >= 3.11,<4.0"]
+requires = ["flit-core>=3.11,<5.0"]
 build-backend = "flit_core.buildapi"