azure-functions-durable 1.3.3__py3-none-any.whl → 1.4.0__py3-none-any.whl

azure/durable_functions/__init__.py

@@ -79,3 +79,11 @@ try:
     __all__.append('Blueprint')
 except ModuleNotFoundError:
     pass
+
+# Import OpenAI Agents integration (optional dependency)
+try:
+    from . import openai_agents # noqa
+    __all__.append('openai_agents')
+except ImportError:
+    # OpenAI agents integration requires additional dependencies
+    pass

azure/durable_functions/decorators/durable_app.py

@@ -1,6 +1,8 @@
 #  Copyright (c) Microsoft Corporation. All rights reserved.
 #  Licensed under the MIT License.
-from .metadata import OrchestrationTrigger, ActivityTrigger, EntityTrigger,\
+
+from azure.durable_functions.models.RetryOptions import RetryOptions
+from .metadata import OrchestrationTrigger, ActivityTrigger, EntityTrigger, \
     DurableClient
 from typing import Callable, Optional
 from azure.durable_functions.entity import Entity
@@ -45,6 +47,7 @@ class Blueprint(TriggerApi, BindingApi, SettingsApi):
             New instance of a Durable Functions app
         """
         super().__init__(auth_level=http_auth_level)
+        self._is_durable_openai_agent_setup = False
 
     def _configure_entity_callable(self, wrap) -> Callable:
         """Obtain decorator to construct an Entity class from a user-defined Function.
@@ -250,6 +253,66 @@ class Blueprint(TriggerApi, BindingApi, SettingsApi):
 
         return wrap
 
+    def _create_invoke_model_activity(self, model_provider, activity_name):
+        """Create and register the invoke_model_activity function with the provided FunctionApp."""
+
+        @self.activity_trigger(input_name="input", activity=activity_name)
+        async def run_model_activity(input: str):
+            from azure.durable_functions.openai_agents.orchestrator_generator\
+                import durable_openai_agent_activity
+
+            return await durable_openai_agent_activity(input, model_provider)
+
+        return run_model_activity
+
+    def _setup_durable_openai_agent(self, model_provider, activity_name):
+        if not self._is_durable_openai_agent_setup:
+            self._create_invoke_model_activity(model_provider, activity_name)
+            self._is_durable_openai_agent_setup = True
+
+    def durable_openai_agent_orchestrator(
+        self,
+        _func=None,
+        *,
+        model_provider=None,
+        model_retry_options: Optional[RetryOptions] = RetryOptions(
+            first_retry_interval_in_milliseconds=2000, max_number_of_attempts=5
+        ),
+    ):
+        """Decorate Azure Durable Functions orchestrators that use OpenAI Agents.
+
+        Parameters
+        ----------
+        model_provider: Optional[ModelProvider]
+            Use a non-default ModelProvider instead of the default OpenAIProvider,
+            such as when testing.
+        """
+        from agents import ModelProvider
+        from azure.durable_functions.openai_agents.orchestrator_generator\
+            import durable_openai_agent_orchestrator_generator
+
+        if model_provider is not None and type(model_provider) is not ModelProvider:
+            raise TypeError("Provided model provider must be of type ModelProvider")
+
+        activity_name = "run_model"
+
+        self._setup_durable_openai_agent(model_provider, activity_name)
+
+        def generator_wrapper_wrapper(func):
+
+            @wraps(func)
+            def generator_wrapper(context):
+                return durable_openai_agent_orchestrator_generator(
+                    func, context, model_retry_options, activity_name
+                )
+
+            return generator_wrapper
+
+        if _func is None:
+            return generator_wrapper_wrapper
+        else:
+            return generator_wrapper_wrapper(_func)
+
 
 class DFApp(Blueprint, FunctionRegister):
     """Durable Functions (DF) app.

azure/durable_functions/openai_agents/__init__.py

@@ -0,0 +1,13 @@
+#  Copyright (c) Microsoft Corporation. All rights reserved.
+#  Licensed under the MIT License.
+"""OpenAI Agents integration for Durable Functions.
+
+This module provides decorators and utilities to integrate OpenAI Agents
+with Durable Functions orchestration patterns.
+"""
+
+from .context import DurableAIAgentContext
+
+__all__ = [
+    'DurableAIAgentContext',
+]

azure/durable_functions/openai_agents/context.py

@@ -0,0 +1,194 @@
+#  Copyright (c) Microsoft Corporation. All rights reserved.
+#  Licensed under the MIT License.
+import json
+from typing import Any, Callable, Optional, TYPE_CHECKING, Union
+
+from azure.durable_functions.models.DurableOrchestrationContext import (
+    DurableOrchestrationContext,
+)
+from azure.durable_functions.models.RetryOptions import RetryOptions
+
+from agents import RunContextWrapper, Tool
+from agents.function_schema import function_schema
+from agents.tool import FunctionTool
+
+from azure.durable_functions.models.Task import TaskBase
+from .task_tracker import TaskTracker
+
+
+if TYPE_CHECKING:
+    # At type-check time we want all members / signatures for IDE & linters.
+    _BaseDurableContext = DurableOrchestrationContext
+else:
+    class _BaseDurableContext:  # lightweight runtime stub
+        """Runtime stub base class for delegation; real context is wrapped.
+
+        At runtime we avoid inheriting from DurableOrchestrationContext so that
+        attribute lookups for its members are delegated via __getattr__ to the
+        wrapped ``_context`` instance.
+        """
+
+        __slots__ = ()
+
+
+class DurableAIAgentContext(_BaseDurableContext):
+    """Context for AI agents running in Azure Durable Functions orchestration.
+
+    Design
+    ------
+    * Static analysis / IDEs: Appears to subclass ``DurableOrchestrationContext`` so
+      you get autocompletion and type hints (under TYPE_CHECKING branch).
+    * Runtime: Inherits from a trivial stub. All durable orchestration operations
+      are delegated to the real ``DurableOrchestrationContext`` instance provided
+      as ``context`` and stored in ``_context``.
+
+    Consequences
+    ------------
+    * ``isinstance(DurableAIAgentContext, DurableOrchestrationContext)`` is **False** at
+      runtime (expected).
+    * Delegation via ``__getattr__`` works for every member of the real context.
+    * No reliance on internal initialization side-effects of the durable SDK.
+    """
+
+    def __init__(
+        self,
+        context: DurableOrchestrationContext,
+        task_tracker: TaskTracker,
+        model_retry_options: Optional[RetryOptions],
+    ):
+        self._context = context
+        self._task_tracker = task_tracker
+        self._model_retry_options = model_retry_options
+
+    def call_activity(
+        self, name: Union[str, Callable], input_: Optional[Any] = None
+    ) -> TaskBase:
+        """Schedule an activity for execution.
+
+        Parameters
+        ----------
+        name: str | Callable
+            Either the name of the activity function to call, as a string or,
+            in the Python V2 programming model, the activity function itself.
+        input_: Optional[Any]
+            The JSON-serializable input to pass to the activity function.
+
+        Returns
+        -------
+        Task
+            A Durable Task that completes when the called activity function completes or fails.
+        """
+        task = self._context.call_activity(name, input_)
+        self._task_tracker.record_activity_call()
+        return task
+
+    def call_activity_with_retry(
+        self,
+        name: Union[str, Callable],
+        retry_options: RetryOptions,
+        input_: Optional[Any] = None,
+    ) -> TaskBase:
+        """Schedule an activity for execution with retry options.
+
+        Parameters
+        ----------
+        name: str | Callable
+            Either the name of the activity function to call, as a string or,
+            in the Python V2 programming model, the activity function itself.
+        retry_options: RetryOptions
+            The retry options for the activity function.
+        input_: Optional[Any]
+            The JSON-serializable input to pass to the activity function.
+
+        Returns
+        -------
+        Task
+            A Durable Task that completes when the called activity function completes or
+            fails completely.
+        """
+        task = self._context.call_activity_with_retry(name, retry_options, input_)
+        self._task_tracker.record_activity_call()
+        return task
+
+    def create_activity_tool(
+        self,
+        activity_func: Callable,
+        *,
+        description: Optional[str] = None,
+        retry_options: Optional[RetryOptions] = RetryOptions(
+            first_retry_interval_in_milliseconds=2000, max_number_of_attempts=5
+        ),
+    ) -> Tool:
+        """Convert an Azure Durable Functions activity to an OpenAI Agents SDK Tool.
+
+        Args
+        ----
+            activity_func: The Azure Functions activity function to convert
+            description: Optional description override for the tool
+            retry_options: The retry options for the activity function
+
+        Returns
+        -------
+            Tool: An OpenAI Agents SDK Tool object
+
+        """
+        if activity_func._function is None:
+            raise ValueError("The provided function is not a valid Azure Function.")
+
+        if (activity_func._function._trigger is not None
+                and activity_func._function._trigger.activity is not None):
+            activity_name = activity_func._function._trigger.activity
+        else:
+            activity_name = activity_func._function._name
+
+        input_name = None
+        if (activity_func._function._trigger is not None
+                and hasattr(activity_func._function._trigger, 'name')):
+            input_name = activity_func._function._trigger.name
+
+        async def run_activity(ctx: RunContextWrapper[Any], input: str) -> Any:
+            # Parse JSON input and extract the named value if input_name is specified
+            activity_input = input
+            if input_name:
+                try:
+                    parsed_input = json.loads(input)
+                    if isinstance(parsed_input, dict) and input_name in parsed_input:
+                        activity_input = parsed_input[input_name]
+                    # If parsing fails or the named parameter is not found, pass the original input
+                except (json.JSONDecodeError, TypeError):
+                    pass
+
+            if retry_options:
+                result = self._task_tracker.get_activity_call_result_with_retry(
+                    activity_name, retry_options, activity_input
+                )
+            else:
+                result = self._task_tracker.get_activity_call_result(activity_name, activity_input)
+            return result
+
+        schema = function_schema(
+            func=activity_func._function._func,
+            docstring_style=None,
+            description_override=description,
+            use_docstring_info=True,
+            strict_json_schema=True,
+        )
+
+        return FunctionTool(
+            name=schema.name,
+            description=schema.description or "",
+            params_json_schema=schema.params_json_schema,
+            on_invoke_tool=run_activity,
+            strict_json_schema=True,
+        )
+
+    def __getattr__(self, name):
+        """Delegate missing attributes to the underlying DurableOrchestrationContext."""
+        try:
+            return getattr(self._context, name)
+        except AttributeError:
+            raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")
+
+    def __dir__(self):
+        """Improve introspection and tab-completion by including delegated attributes."""
+        return sorted(set(dir(type(self)) + list(self.__dict__) + dir(self._context)))

azure/durable_functions/openai_agents/event_loop.py

@@ -0,0 +1,17 @@
+#  Copyright (c) Microsoft Corporation. All rights reserved.
+#  Licensed under the MIT License.
+import asyncio
+
+
+def ensure_event_loop():
+    """Ensure an event loop is available for sync execution context.
+
+    This is necessary when calling Runner.run_sync from Azure Functions
+    Durable orchestrators, which run in a synchronous context but need
+    an event loop for internal async operations.
+    """
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)

azure/durable_functions/openai_agents/exceptions.py

@@ -0,0 +1,11 @@
+#  Copyright (c) Microsoft Corporation. All rights reserved.
+#  Licensed under the MIT License.
+from azure.durable_functions.models.Task import TaskBase
+
+
+class YieldException(BaseException):
+    """Exception raised when an orchestrator should yield control."""
+
+    def __init__(self, task: TaskBase):
+        super().__init__("Orchestrator should yield.")
+        self.task = task

azure/durable_functions/openai_agents/handoffs.py

@@ -0,0 +1,67 @@
+#  Copyright (c) Microsoft Corporation. All rights reserved.
+#  Licensed under the MIT License.
+"""Handoff conversion utilities for Azure Durable Functions OpenAI agent operations."""
+
+from typing import Any
+
+from agents import Handoff
+from pydantic import BaseModel
+
+
+class DurableHandoff(BaseModel):
+    """Serializable representation of a Handoff.
+
+    Contains only the data needed by the model execution to
+    determine what to handoff to, not the actual handoff invocation.
+    """
+
+    tool_name: str
+    tool_description: str
+    input_json_schema: dict[str, Any]
+    agent_name: str
+    strict_json_schema: bool = True
+
+    @classmethod
+    def from_handoff(cls, handoff: Handoff) -> "DurableHandoff":
+        """Create a DurableHandoff from an OpenAI agent Handoff.
+
+        This method converts OpenAI agent Handoff instances into serializable
+        DurableHandoff objects for use within Azure Durable Functions.
+
+        Parameters
+        ----------
+        handoff : Handoff
+            The OpenAI agent Handoff to convert
+
+        Returns
+        -------
+        DurableHandoff
+            A serializable handoff representation
+        """
+        return cls(
+            tool_name=handoff.tool_name,
+            tool_description=handoff.tool_description,
+            input_json_schema=handoff.input_json_schema,
+            agent_name=handoff.agent_name,
+            strict_json_schema=handoff.strict_json_schema,
+        )
+
+    def to_handoff(self) -> Handoff[Any, Any]:
+        """Create an OpenAI agent Handoff instance from this DurableHandoff.
+
+        This method converts the serializable DurableHandoff back into an
+        OpenAI agent Handoff instance for execution.
+
+        Returns
+        -------
+        Handoff
+            OpenAI agent Handoff instance
+        """
+        return Handoff(
+            tool_name=self.tool_name,
+            tool_description=self.tool_description,
+            input_json_schema=self.input_json_schema,
+            agent_name=self.agent_name,
+            strict_json_schema=self.strict_json_schema,
+            on_invoke_handoff=lambda ctx, input: None,
+        )

azure/durable_functions/openai_agents/model_invocation_activity.py

@@ -0,0 +1,268 @@
+#  Copyright (c) Microsoft Corporation. All rights reserved.
+#  Licensed under the MIT License.
+import enum
+import json
+from typing import Any, AsyncIterator, Optional, Union, cast
+
+from azure.durable_functions.models.RetryOptions import RetryOptions
+from pydantic import BaseModel, Field
+from agents import (
+    AgentOutputSchema,
+    AgentOutputSchemaBase,
+    Handoff,
+    Model,
+    ModelProvider,
+    ModelResponse,
+    ModelSettings,
+    ModelTracing,
+    OpenAIProvider,
+    Tool,
+    TResponseInputItem,
+    UserError,
+)
+from agents.items import TResponseStreamEvent
+from openai.types.responses.response_prompt_param import ResponsePromptParam
+
+from .task_tracker import TaskTracker
+from .tools import (
+    DurableTool,
+    create_tool_from_durable_tool,
+    convert_tool_to_durable_tool,
+)
+from .handoffs import DurableHandoff
+
+
+class DurableAgentOutputSchema(AgentOutputSchemaBase, BaseModel):
+    """Serializable representation of agent output schema."""
+
+    output_type_name: Optional[str] = None
+    output_schema: Optional[dict[str, Any]] = None
+    strict_json_schema: bool
+
+    def is_plain_text(self) -> bool:
+        """Whether the output type is plain text (versus a JSON object)."""
+        return self.output_type_name in (None, "str")
+
+    def name(self) -> str:
+        """Get the name of the output type."""
+        if self.output_type_name is None:
+            raise ValueError("Output type name has not been specified")
+        return self.output_type_name
+
+    def json_schema(self) -> dict[str, Any]:
+        """Return the JSON schema of the output.
+
+        Will only be called if the output type is not plain text.
+        """
+        if self.is_plain_text():
+            raise UserError("Cannot provide JSON schema for plain text output types")
+        if self.output_schema is None:
+            raise UserError("Output schema definition is missing")
+        return self.output_schema
+
+    def is_strict_json_schema(self) -> bool:
+        """Check if the JSON schema is in strict mode.
+
+        Strict mode constrains the JSON schema features, but guarantees valid JSON.
+        See here for details:
+        https://platform.openai.com/docs/guides/structured-outputs#supported-schemas
+        """
+        return self.strict_json_schema
+
+    def validate_json(self, json_str: str) -> Any:
+        """Validate a JSON string against the output type.
+
+        You must return the validated object, or raise a `ModelBehaviorError` if
+        the JSON is invalid.
+        """
+        raise NotImplementedError()
+
+
+class ModelTracingLevel(enum.IntEnum):
+    """Serializable IntEnum representation of ModelTracing for Azure Durable Functions.
+
+    Values must match ModelTracing from the OpenAI SDK. This separate enum is required
+    because ModelTracing is a standard Enum while Pydantic serialization requires IntEnum
+    for proper JSON serialization in activity inputs.
+    """
+
+    DISABLED = 0
+    ENABLED = 1
+    ENABLED_WITHOUT_DATA = 2
+
+
+class DurableModelActivityInput(BaseModel):
+    """Serializable input for the durable model invocation activity."""
+
+    input: Union[str, list[TResponseInputItem]]
+    model_settings: ModelSettings
+    tracing: ModelTracingLevel
+    model_name: Optional[str] = None
+    system_instructions: Optional[str] = None
+    tools: list[DurableTool] = Field(default_factory=list)
+    output_schema: Optional[DurableAgentOutputSchema] = None
+    handoffs: list[DurableHandoff] = Field(default_factory=list)
+    previous_response_id: Optional[str] = None
+    prompt: Optional[Any] = None
+
+    def to_json(self) -> str:
+        """Convert to a JSON string."""
+        try:
+            return self.model_dump_json(warnings=False)
+        except Exception:
+            # Fallback to basic JSON serialization
+            try:
+                return json.dumps(self.model_dump(warnings=False), default=str)
+            except Exception as fallback_error:
+                raise ValueError(
+                    f"Unable to serialize DurableModelActivityInput: {fallback_error}"
+                ) from fallback_error
+
+    @classmethod
+    def from_json(cls, json_str: str) -> 'DurableModelActivityInput':
+        """Create from a JSON string."""
+        return cls.model_validate_json(json_str)
+
+
+class ModelInvoker:
+    """Handles OpenAI model invocations for Durable Functions activities."""
+
+    def __init__(self, model_provider: Optional[ModelProvider] = None):
+        """Initialize the activity with a model provider."""
+        self._model_provider = model_provider or OpenAIProvider()
+
+    async def invoke_model_activity(self, input: DurableModelActivityInput) -> ModelResponse:
+        """Activity that invokes a model with the given input."""
+        model = self._model_provider.get_model(input.model_name)
+
+        # Avoid https://github.com/pydantic/pydantic/issues/9541
+        normalized_input = json.loads(json.dumps(input.input, default=str))
+
+        # Convert durable tools to agent tools
+        tools = [
+            create_tool_from_durable_tool(durable_tool)
+            for durable_tool in input.tools
+        ]
+
+        # Convert handoff descriptors to agent handoffs
+        handoffs = [
+            durable_handoff.to_handoff()
+            for durable_handoff in input.handoffs
+        ]
+
+        return await model.get_response(
+            system_instructions=input.system_instructions,
+            input=normalized_input,
+            model_settings=input.model_settings,
+            tools=tools,
+            output_schema=input.output_schema,
+            handoffs=handoffs,
+            tracing=ModelTracing(input.tracing),
+            previous_response_id=input.previous_response_id,
+            prompt=input.prompt,
+        )
+
+
+class DurableActivityModel(Model):
+    """A model implementation that uses durable activities for model invocations."""
+
+    def __init__(
+        self,
+        model_name: Optional[str],
+        task_tracker: TaskTracker,
+        retry_options: Optional[RetryOptions],
+        activity_name: str,
+    ) -> None:
+        self.model_name = model_name
+        self.task_tracker = task_tracker
+        self.retry_options = retry_options
+        self.activity_name = activity_name
+
+    async def get_response(
+        self,
+        system_instructions: Optional[str],
+        input: Union[str, list[TResponseInputItem]],
+        model_settings: ModelSettings,
+        tools: list[Tool],
+        output_schema: Optional[AgentOutputSchemaBase],
+        handoffs: list[Handoff],
+        tracing: ModelTracing,
+        *,
+        previous_response_id: Optional[str],
+        prompt: Optional[ResponsePromptParam],
+        conversation_id: Optional[str] = None,
+    ) -> ModelResponse:
+        """Get a response from the model."""
+        # Convert agent tools to Durable tools
+        durable_tools = [convert_tool_to_durable_tool(tool) for tool in tools]
+
+        # Convert agent handoffs to Durable handoff descriptors
+        durable_handoffs = [DurableHandoff.from_handoff(handoff) for handoff in handoffs]
+        if output_schema is not None and not isinstance(
+            output_schema, AgentOutputSchema
+        ):
+            raise TypeError(
+                f"Only AgentOutputSchema is supported by Durable Model, "
+                f"got {type(output_schema).__name__}"
+            )
+
+        output_schema_input = (
+            None
+            if output_schema is None
+            else DurableAgentOutputSchema(
+                output_type_name=output_schema.name(),
+                output_schema=(
+                    output_schema.json_schema()
+                    if not output_schema.is_plain_text()
+                    else None
+                ),
+                strict_json_schema=output_schema.is_strict_json_schema(),
+            )
+        )
+
+        activity_input = DurableModelActivityInput(
+            model_name=self.model_name,
+            system_instructions=system_instructions,
+            input=cast(Union[str, list[TResponseInputItem]], input),
+            model_settings=model_settings,
+            tools=durable_tools,
+            output_schema=output_schema_input,
+            handoffs=durable_handoffs,
+            tracing=ModelTracingLevel.DISABLED,  # ModelTracingLevel(tracing.value),
+            previous_response_id=previous_response_id,
+            prompt=prompt,
+        )
+
+        activity_input_json = activity_input.to_json()
+
+        if self.retry_options:
+            response = self.task_tracker.get_activity_call_result_with_retry(
+                self.activity_name,
+                self.retry_options,
+                activity_input_json,
+            )
+        else:
+            response = self.task_tracker.get_activity_call_result(
+                self.activity_name,
+                activity_input_json
+            )
+
+        json_response = json.loads(response)
+        model_response = ModelResponse(**json_response)
+        return model_response
+
+    def stream_response(
+        self,
+        system_instructions: Optional[str],
+        input: Union[str, list[TResponseInputItem]],
+        model_settings: ModelSettings,
+        tools: list[Tool],
+        output_schema: Optional[AgentOutputSchemaBase],
+        handoffs: list[Handoff],
+        tracing: ModelTracing,
+        *,
+        previous_response_id: Optional[str],
+        prompt: Optional[ResponsePromptParam],
+    ) -> AsyncIterator[TResponseStreamEvent]:
+        """Stream a response from the model."""
+        raise NotImplementedError("Durable model doesn't support streams yet")