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

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")

azure/durable_functions/openai_agents/orchestrator_generator.py

@@ -0,0 +1,67 @@
+#  Copyright (c) Microsoft Corporation. All rights reserved.
+#  Licensed under the MIT License.
+from functools import partial
+from typing import Optional
+from agents import ModelProvider, ModelResponse
+from agents.run import set_default_agent_runner
+from azure.durable_functions.models.DurableOrchestrationContext import DurableOrchestrationContext
+from azure.durable_functions.models.RetryOptions import RetryOptions
+from .model_invocation_activity import DurableModelActivityInput, ModelInvoker
+from .task_tracker import TaskTracker
+from .runner import DurableOpenAIRunner
+from .context import DurableAIAgentContext
+from .event_loop import ensure_event_loop
+from .usage_telemetry import UsageTelemetry
+
+
+async def durable_openai_agent_activity(input: str, model_provider: ModelProvider) -> str:
+    """Activity logic that handles OpenAI model invocations."""
+    activity_input = DurableModelActivityInput.from_json(input)
+
+    model_invoker = ModelInvoker(model_provider=model_provider)
+    result = await model_invoker.invoke_model_activity(activity_input)
+
+    # Use safe/public Pydantic API when possible. Prefer model_dump_json if result is a BaseModel
+    # Otherwise handle common types (str/bytes/dict/list) and fall back to json.dumps.
+    import json as _json
+
+    if hasattr(result, "model_dump_json"):
+        # Pydantic v2 BaseModel
+        json_str = result.model_dump_json()
+    else:
+        if isinstance(result, bytes):
+            json_str = result.decode()
+        elif isinstance(result, str):
+            json_str = result
+        else:
+            # Try the internal serializer as a last resort, but fall back to json.dumps
+            try:
+                json_bytes = ModelResponse.__pydantic_serializer__.to_json(result)
+                json_str = json_bytes.decode()
+            except Exception:
+                json_str = _json.dumps(result)
+
+    return json_str
+
+
+def durable_openai_agent_orchestrator_generator(
+        func,
+        durable_orchestration_context: DurableOrchestrationContext,
+        model_retry_options: Optional[RetryOptions],
+        activity_name: str,
+):
+    """Adapts the synchronous OpenAI Agents function to an Durable orchestrator generator."""
+    # Log versions the first time this generator is invoked
+    UsageTelemetry.log_usage_once()
+
+    ensure_event_loop()
+    task_tracker = TaskTracker(durable_orchestration_context)
+    durable_ai_agent_context = DurableAIAgentContext(
+        durable_orchestration_context, task_tracker, model_retry_options
+    )
+    durable_openai_runner = DurableOpenAIRunner(
+        context=durable_ai_agent_context, activity_name=activity_name)
+    set_default_agent_runner(durable_openai_runner)
+
+    func_with_context = partial(func, durable_ai_agent_context)
+    return task_tracker.execute_orchestrator_function(func_with_context)

azure/durable_functions/openai_agents/runner.py

@@ -0,0 +1,103 @@
+#  Copyright (c) Microsoft Corporation. All rights reserved.
+#  Licensed under the MIT License.
+import json
+from dataclasses import replace
+from typing import Any, Union
+
+from agents import (
+    Agent,
+    RunConfig,
+    RunResult,
+    RunResultStreaming,
+    TContext,
+    TResponseInputItem,
+)
+from agents.run import DEFAULT_AGENT_RUNNER, DEFAULT_MAX_TURNS, AgentRunner
+from pydantic_core import to_json
+
+from .context import DurableAIAgentContext
+from .model_invocation_activity import DurableActivityModel
+
+
+class DurableOpenAIRunner:
+    """Runner for OpenAI agents using Durable Functions orchestration."""
+
+    def __init__(self, context: DurableAIAgentContext, activity_name: str) -> None:
+        self._runner = DEFAULT_AGENT_RUNNER or AgentRunner()
+        self._context = context
+        self._activity_name = activity_name
+
+    def _prepare_run_config(
+        self,
+        starting_agent: Agent[TContext],
+        input: Union[str, list[TResponseInputItem]],
+        **kwargs: Any,
+    ) -> tuple[Union[str, list[TResponseInputItem]], RunConfig, dict[str, Any]]:
+        """Prepare and validate the run configuration and parameters for agent execution."""
+        # Avoid https://github.com/pydantic/pydantic/issues/9541
+        normalized_input = json.loads(to_json(input))
+
+        run_config = kwargs.get("run_config") or RunConfig()
+
+        model_name = run_config.model or starting_agent.model
+        if model_name and not isinstance(model_name, str):
+            raise ValueError(
+                "For agent execution in Durable Functions, model name in run_config or "
+                "starting_agent must be a string."
+            )
+
+        updated_run_config = replace(
+            run_config,
+            model=DurableActivityModel(
+                model_name=model_name,
+                task_tracker=self._context._task_tracker,
+                retry_options=self._context._model_retry_options,
+                activity_name=self._activity_name,
+            ),
+        )
+
+        run_params = {
+            "context": kwargs.get("context"),
+            "max_turns": kwargs.get("max_turns", DEFAULT_MAX_TURNS),
+            "hooks": kwargs.get("hooks"),
+            "previous_response_id": kwargs.get("previous_response_id"),
+            "session": kwargs.get("session"),
+        }
+
+        return normalized_input, updated_run_config, run_params
+
+    def run_sync(
+        self,
+        starting_agent: Agent[TContext],
+        input: Union[str, list[TResponseInputItem]],
+        **kwargs: Any,
+    ) -> RunResult:
+        """Run an agent synchronously with the given input and configuration."""
+        normalized_input, updated_run_config, run_params = self._prepare_run_config(
+            starting_agent, input, **kwargs
+        )
+
+        return self._runner.run_sync(
+            starting_agent=starting_agent,
+            input=normalized_input,
+            run_config=updated_run_config,
+            **run_params,
+        )
+
+    def run(
+        self,
+        starting_agent: Agent[TContext],
+        input: Union[str, list[TResponseInputItem]],
+        **kwargs: Any,
+    ) -> RunResult:
+        """Run an agent asynchronously. Not supported in Durable Functions."""
+        raise RuntimeError("Durable Functions do not support asynchronous runs.")
+
+    def run_streamed(
+        self,
+        starting_agent: Agent[TContext],
+        input: Union[str, list[TResponseInputItem]],
+        **kwargs: Any,
+    ) -> RunResultStreaming:
+        """Run an agent with streaming. Not supported in Durable Functions."""
+        raise RuntimeError("Durable Functions do not support streaming.")

azure/durable_functions/openai_agents/task_tracker.py

@@ -0,0 +1,171 @@
+#  Copyright (c) Microsoft Corporation. All rights reserved.
+#  Licensed under the MIT License.
+import json
+import inspect
+from typing import Any
+
+from azure.durable_functions.models.DurableOrchestrationContext import (
+    DurableOrchestrationContext,
+)
+from azure.durable_functions.models.history.HistoryEventType import HistoryEventType
+from azure.durable_functions.models.RetryOptions import RetryOptions
+
+from .exceptions import YieldException
+
+
+class TaskTracker:
+    """Tracks activity calls and handles task result processing for durable AI agents."""
+
+    def __init__(self, context: DurableOrchestrationContext):
+        self._context = context
+        self._activities_called = 0
+        self._tasks_to_yield = []
+
+    def _get_activity_result_or_raise(self, task):
+        """Return the activity result if available; otherwise raise ``YieldException`` to defer.
+
+        The first time an activity is scheduled its result won't yet exist in the
+        orchestration history, so we raise ``YieldException`` with the task so the
+        orchestrator can yield it. On replay, once the corresponding TASK_COMPLETED
+        history event is present, we capture the result and queue the task for a
+        later yield (to preserve ordering) while returning the deserialized value.
+        """
+        self.record_activity_call()
+
+        histories = self._context.histories
+        completed_tasks = [
+            entry for entry in histories
+            if entry.event_type == HistoryEventType.TASK_COMPLETED
+        ]
+        if len(completed_tasks) < self._activities_called:
+            # Result not yet available in history -> raise to signal a yield now
+            raise YieldException(task)
+        # Result exists (replay). Queue task to be yielded after returning value.
+        #
+        # We cannot just yield it now because this method can be called from
+        # deeply nested code paths that we don't control (such as the
+        # OpenAI Agents SDK internals), and yielding here would lead to
+        # unintended behavior. Instead, we queue the task to be yielded
+        # later and return the result recorded in the history, so the
+        # code invoking this method can continue executing normally.
+        self._tasks_to_yield.append(task)
+
+        result_json = completed_tasks[self._activities_called - 1].Result
+        result = json.loads(result_json)
+        return result
+
+    def get_activity_call_result(self, activity_name, input: Any):
+        """Call an activity and return its result or raise ``YieldException`` if pending."""
+        task = self._context.call_activity(activity_name, input)
+        return self._get_activity_result_or_raise(task)
+
+    def get_activity_call_result_with_retry(
+        self, activity_name, retry_options: RetryOptions, input: Any
+    ):
+        """Call an activity with retry and return its result or raise YieldException if pending."""
+        task = self._context.call_activity_with_retry(activity_name, retry_options, input)
+        return self._get_activity_result_or_raise(task)
+
+    def record_activity_call(self):
+        """Record that an activity was called."""
+        self._activities_called += 1
+
+    def _yield_and_clear_tasks(self):
+        """Yield all accumulated tasks and clear the tasks list."""
+        for task in self._tasks_to_yield:
+            yield task
+        self._tasks_to_yield.clear()
+
+    def execute_orchestrator_function(self, func):
+        """Execute the orchestrator function with comprehensive task and exception handling.
+
+        The orchestrator function can exhibit any combination of the following behaviors:
+        - Execute regular code and return a value or raise an exception
+        - Invoke get_activity_call_result or get_activity_call_result_with_retry, which leads to
+          either interrupting the orchestrator function immediately (because of YieldException),
+          or queueing the task for later yielding while continuing execution
+        - Invoke DurableAIAgentContext.call_activity or call_activity_with_retry (which must lead
+          to corresponding record_activity_call invocations)
+        - Yield tasks (typically produced by DurableAIAgentContext methods like call_activity,
+          wait_for_external_event, etc.), which may or may not interrupt orchestrator function
+          execution
+        - Mix all of the above in any combination
+
+        This method converts both YieldException and regular yields into a sequence of yields
+        preserving the order, while also capturing return values through the generator protocol.
+        For example, if the orchestrator function yields task A, then queues task B for yielding,
+        then raises YieldException wrapping task C, this method makes sure that the resulting
+        sequence of yields is: (A, B, C).
+
+        Args
+        ----
+            func: The orchestrator function to execute (generator or regular function)
+
+        Yields
+        ------
+            Tasks yielded by the orchestrator function and tasks wrapped in YieldException
+
+        Returns
+        -------
+            The return value from the orchestrator function
+        """
+        if inspect.isgeneratorfunction(func):
+            gen = iter(func())
+            try:
+                # prime the subiterator
+                value = next(gen)
+                yield from self._yield_and_clear_tasks()
+                while True:
+                    try:
+                        # send whatever was sent into us down to the subgenerator
+                        yield from self._yield_and_clear_tasks()
+                        sent = yield value
+                    except GeneratorExit:
+                        # ensure the subgenerator is closed
+                        if hasattr(gen, "close"):
+                            gen.close()
+                        raise
+                    except BaseException as exc:
+                        # forward thrown exceptions if possible
+                        if hasattr(gen, "throw"):
+                            value = gen.throw(type(exc), exc, exc.__traceback__)
+                        else:
+                            raise
+                    else:
+                        # normal path: forward .send (or .__next__)
+                        if hasattr(gen, "send"):
+                            value = gen.send(sent)
+                        else:
+                            value = next(gen)
+            except StopIteration as e:
+                yield from self._yield_and_clear_tasks()
+                return TaskTracker._durable_serializer(e.value)
+            except YieldException as e:
+                yield from self._yield_and_clear_tasks()
+                yield e.task
+        else:
+            try:
+                result = func()
+                return TaskTracker._durable_serializer(result)
+            except YieldException as e:
+                yield from self._yield_and_clear_tasks()
+                yield e.task
+            finally:
+                yield from self._yield_and_clear_tasks()
+
+    @staticmethod
+    def _durable_serializer(obj: Any) -> str:
+        # Strings are already "serialized"
+        if type(obj) is str:
+            return obj
+
+        # Serialize "Durable" and OpenAI models, and typed dictionaries
+        if callable(getattr(obj, "to_json", None)):
+            return obj.to_json()
+
+        # Serialize Pydantic models
+        if callable(getattr(obj, "model_dump_json", None)):
+            return obj.model_dump_json()
+
+        # Fallback to default JSON serialization
+        return json.dumps(obj)