agentdeck-sdk 3.1.0__py3-none-any.whl

agentdeck/adapters/engines/openai_agents/engine.py

@@ -0,0 +1,321 @@
+"""The openai-agents engine: ``EnginePort`` over ``agents.Runner``.
+
+``spec.native`` is the pre-built ``agents.Agent`` (handoffs and tools included) — this
+adapter only runs it and translates its stream, per ``core/ports/engine.py``. Execution
+state (the SDK session) is engine-private (ADR-D5): the session, not the log, is what
+feeds the model. The log passed in as ``history`` is read for exactly one purpose — the
+turn-start reconciliation in ``reconcile.py``, which repairs a session left behind by a
+crash between the log write and the session write.
+
+Input is multimodal (``_to_sdk_input`` maps ``TextBlock``/``ImageBlock``/``AudioBlock`` onto the
+SDK's own canonical parts); output is not. Nothing in this run loop produces an image or audio
+block — ``_run_completed`` only ever builds ``TextBlock``/``DataBlock`` — so an agent can *see*
+a photo or a voice note and never *return* one. Audio is chat-completions only: at the pinned
+``openai-agents==0.17.0``/``openai==2.32.0``, the Responses API's content list has no audio
+member, so an ``AudioBlock`` under ``use_responses=True`` raises rather than reaching the
+endpoint and coming back as an opaque 400.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+from collections.abc import Callable
+from contextlib import AbstractAsyncContextManager, aclosing, asynccontextmanager, nullcontext
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, ClassVar, cast
+
+from agents import Agent, Runner
+from pydantic import BaseModel
+
+from agentdeck.adapters.engines.openai_agents.reconcile import reconcile
+from agentdeck.adapters.engines.openai_agents.runconfig import RunSettings, build_run_config
+from agentdeck.adapters.engines.openai_agents.sessions import ExecutionStore
+from agentdeck.adapters.engines.openai_agents.translate import translate
+from agentdeck.core.content import AudioBlock, DataBlock, ImageBlock, TextBlock, coerce_input
+from agentdeck.core.control import ControlSignalled
+from agentdeck.core.events import RunCompleted, Usage, UsageReported
+from agentdeck.core.ports import EnginePort
+from agentdeck.errors import ConfigError
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncGenerator, AsyncIterator, Sequence
+
+    from agents.items import TResponseInputItem
+    from agents.memory.session import Session
+    from agents.result import RunResultStreaming
+    from agents.usage import Usage as SDKUsage
+
+    from agentdeck.core.content import ContentBlock, Input
+    from agentdeck.core.context import RunContext
+    from agentdeck.core.events import Event, KnownPayload
+    from agentdeck.core.invocable import InvocableSpec
+
+SandboxScope = Callable[[Agent[Any]], AbstractAsyncContextManager[Any]]
+"""How this engine opens whatever sandbox an agent needs: given the agent, a scope yielding
+the SDK ``sandbox`` handle for its run (or ``None``).
+
+Injected rather than built here because a sandbox is a capability, not an engine concern —
+it becomes a port of its own in the next slice. Unset means no agent in this project needs
+one, which is every code-first caller until it says otherwise."""
+
+
+@dataclass(slots=True)
+class Launch:
+    """One run's SDK handle, plus whether this engine reached its terminal payload.
+
+    ``finished`` exists because nothing on the SDK result can answer that question at the
+    moment it is asked: a run abandoned mid-stream and a run that ended normally both arrive
+    at ``_launch``'s exit already cancelled, so ``is_complete`` is true either way, and
+    ``final_output`` is only *usually* absent from the abandoned one (the SDK's run loop is
+    detached, so it may well have finished while nobody was reading). The engine's own control
+    flow is the authority, and this is how it says so.
+
+    It is the *engine's* view, not the log's, and cannot be made the log's: it is set before the
+    terminal payload is yielded, because the Runtime breaks on that payload and never returns
+    here. So a store that rejects the terminal append leaves this ``True`` while the log ends in
+    ``run.failed`` — an observability span reporting success for a run the log calls failed. The
+    log is the record; a reader reconciling the two believes the log.
+    """
+
+    result: RunResultStreaming
+    finished: bool = False
+
+
+class OpenAIAgentsEngine(EnginePort):
+    """Plays ``spec.native`` (an ``agents.Agent``) through ``Runner.run_streamed``.
+
+    Everything a run is configured with arrives here already resolved — ``sessions`` is the
+    conversation memory (Redis-backed or local), ``settings`` the endpoint and limits, and
+    ``sandbox`` the scope an agent that needs one runs inside. All three default to the
+    SDK's own behavior, so ``OpenAIAgentsEngine()`` still runs an agent that configured
+    itself.
+    """
+
+    engine: ClassVar[str] = "openai-agents"
+
+    def __init__(
+        self,
+        sessions: ExecutionStore | None = None,
+        *,
+        settings: RunSettings | None = None,
+        sandbox: SandboxScope | None = None,
+    ) -> None:
+        self._sessions = sessions or ExecutionStore()
+        self._settings = settings or RunSettings()
+        self._sandbox = sandbox
+
+    async def start(
+        self,
+        spec: InvocableSpec,
+        input: Input,
+        history: Sequence[Event],
+        ctx: RunContext,
+    ) -> AsyncGenerator[KnownPayload, None]:
+        agent = _agent_of(spec)
+        session = self._session(ctx)
+        if session is not None:
+            diverged = await reconcile(session, history)
+            if diverged is not None:
+                # Two stores disagreeing is worth a place in the record, not just a log line;
+                # the run itself still has the session it needs and plays on.
+                yield diverged
+        message = _to_sdk_input(input, use_responses=self._settings.use_responses)
+        async with self._launch(agent, message, ctx, session) as launch:
+            result = launch.result
+            tool_names: dict[str, str] = {}
+            # The SDK's run loop is a detached task; an abandoned generator must cancel it
+            # explicitly (mirrors agents/runners/headless.py's run_streamed, same reason).
+            stream = cast("AsyncGenerator[Any, None]", result.stream_events())
+            try:
+                async with aclosing(stream) as events:
+                    async for event in events:
+                        payload = self._translate(event, tool_names)
+                        if payload is not None:
+                            yield payload
+                        try:
+                            await ctx.gate.checkpoint()
+                        except ControlSignalled as signalled:
+                            # A complete chunk was just yielded (or none was, at the very
+                            # first safe point) — never a partial one — so this is the next
+                            # safe point the contract promises, not "right now, mid-token".
+                            # The SDK run is dropped either way: a paused turn has no
+                            # checkpoint to sit in, so resuming replays it from the log.
+                            result.cancel()
+                            for payload in signalled.payloads:
+                                yield payload
+                            return
+            except BaseException:
+                result.cancel()
+                raise
+            result.cancel()
+            terminal = self._terminal(result)
+            # Set before the yields, not after them: the Runtime breaks on the terminal event,
+            # so the line after this loop never runs.
+            launch.finished = True
+            for payload in terminal:
+                yield payload
+
+    def _session(self, ctx: RunContext) -> Session | None:
+        """The execution state this run reads and writes — the adapter's own store by default."""
+        return self._sessions.session_for(ctx)
+
+    @asynccontextmanager
+    async def _launch(
+        self, agent: Agent[Any], message: str | list[TResponseInputItem], ctx: RunContext, session: Session | None
+    ) -> AsyncIterator[Launch]:
+        """Start the run and hold whatever scope it needs open until the stream is drained.
+
+        Lifecycle rule: **code after the ``yield`` may never run.** A successful run ends
+        with the Runtime breaking on the terminal event, which closes this generator — the
+        ``yield`` raises ``GeneratorExit`` and the lines below it are skipped. Anything that
+        must happen once per finished run therefore belongs in the ``GeneratorExit`` path,
+        keyed on ``Launch.finished``, never only after the ``yield``.
+        """
+        scope = self._sandbox(agent) if self._sandbox is not None else nullcontext(None)
+        async with scope as sandbox:
+            yield Launch(
+                Runner.run_streamed(
+                    agent,
+                    message,
+                    # The run context travels as the SDK's own context object, which is the one thing
+                    # the SDK hands a function tool: a tool declaring ``RunContextWrapper[RunContext]``
+                    # reaches ``wrapper.context.reporter`` (and the gate) without importing a Runtime.
+                    # Nothing in the SDK reads it — it is opaque to the run loop by design.
+                    context=ctx,
+                    session=session,
+                    run_config=build_run_config(self._settings, sandbox=sandbox),
+                    max_turns=self._settings.max_turns,
+                )
+            )
+
+    def _translate(self, event: Any, tool_names: dict[str, str]) -> KnownPayload | None:
+        payload = translate(event, tool_names)
+        return payload if payload is not None else _usage_reported(event)
+
+    def _terminal(self, result: RunResultStreaming) -> Sequence[KnownPayload]:
+        return (_run_completed(result),)
+
+    async def resume(
+        self,
+        spec: InvocableSpec,
+        thread_id: str,
+        value: Any,
+        ctx: RunContext,
+    ) -> AsyncGenerator[KnownPayload, None]:
+        # M0 scope is UC1's plain chat, which never suspends — there is no interrupted run
+        # for this engine to continue. Raising (not a silent no-op) matches the Runtime's
+        # own rule that this method is only ever called on a WAITING_HUMAN run.
+        raise ConfigError(f"openai-agents engine (M0) has no interrupts to resume: {spec.name!r} never suspends")
+        yield  # pragma: no cover — makes this an async generator; never reached
+
+
+def _usage_reported(event: Any) -> KnownPayload | None:
+    """One finished model call → one ``usage.reported``.
+
+    The terminal event's ``usage`` is the SDK's cumulative total for the turn, so without
+    this a consumer cannot tell one model call from four — which is exactly what v1's
+    ``usage.requests`` counted.
+    """
+    if event.type != "raw_response_event" or getattr(event.data, "type", None) != "response.completed":
+        return None
+    response = event.data.response
+    usage = getattr(response, "usage", None)
+    if usage is None:
+        return None
+    return UsageReported(
+        model=str(getattr(response, "model", "") or ""),
+        usage=Usage(input_tokens=usage.input_tokens, output_tokens=usage.output_tokens),
+    )
+
+
+def _agent_of(spec: InvocableSpec) -> Agent[Any]:
+    if not isinstance(spec.native, Agent):
+        raise ConfigError(f"{spec.name!r} has no openai-agents Agent: expected native=Agent, got {type(spec.native)}")
+    return spec.native
+
+
+def _to_sdk_input(input: Input, *, use_responses: bool) -> str | list[TResponseInputItem]:
+    """All-text input still returns the joined ``str`` it always has, byte for byte — every
+    existing session item, reconcile transcript and stored event stays unchanged, and only a
+    turn that actually carries media takes the branch below.
+
+    That branch emits the SDK's own canonical (Responses) item shape — ``input_text`` /
+    ``input_image`` / ``input_audio`` parts — rather than a converter agentdeck writes itself:
+    ``agents.models.chatcmpl_converter.Converter`` already accepts these parts and maps them
+    down to Chat-Completions parts, so one emitted shape works on both API paths.
+    """
+    texts = [block.text for block in input if isinstance(block, TextBlock)]
+    if len(texts) == len(input):
+        return "\n".join(texts)
+    item = {"role": "user", "content": [_part_of(block, use_responses=use_responses) for block in input]}
+    return cast("list[TResponseInputItem]", [item])
+
+
+def _part_of(block: ContentBlock, *, use_responses: bool) -> dict[str, Any]:
+    if isinstance(block, TextBlock):
+        return {"type": "input_text", "text": block.text}
+    if isinstance(block, ImageBlock):
+        return {"type": "input_image", "image_url": f"data:{block.media_type};base64,{block.data_b64}"}
+    if isinstance(block, AudioBlock):
+        if use_responses:
+            raise ConfigError(
+                "openai-agents engine cannot send an 'audio' block over the Responses API: "
+                "ResponseInputMessageContentListParam carries no audio member at this pin "
+                "(openai-agents==0.17.0) — set use_responses=False (chat-completions) to send audio"
+            )
+        return {
+            "type": "input_audio",
+            "input_audio": {"data": block.data_b64, "format": _audio_format(block.media_type)},
+        }
+    raise ConfigError(
+        f"openai-agents engine cannot send a {block.type!r} block to the model; "
+        "it accepts text, image, and audio (chat-completions only) input blocks"
+    )
+
+
+def _audio_format(media_type: str) -> str:
+    """``audio/ogg; codecs=opus`` (a WhatsApp voice note's own media type) becomes ``ogg``: the
+    subtype with parameters stripped, unvalidated against openai's own ``Literal["mp3", "wav"]``
+    — the chat-completions converter passes the string through unchanged, and a provider such
+    as Gemini's OpenAI-compatible endpoint accepts ``ogg``."""
+    return media_type.split(";", 1)[0].strip().rsplit("/", 1)[-1]
+
+
+def _run_completed(result: RunResultStreaming) -> RunCompleted:
+    output = result.final_output
+    if isinstance(output, str):
+        return RunCompleted(output=coerce_input(output), usage=_usage_of(result))
+    return RunCompleted(output=[DataBlock(data=_structured(output))], usage=_usage_of(result))
+
+
+def _structured(output: Any) -> Any:
+    """An ``output_type`` agent's validated result as JSON data.
+
+    It travels as a ``DataBlock``, which is why this no longer raises: refusing a non-``str``
+    final output turned a documented feature into a failed run. The ceiling, and it applies to
+    every branch below: a leaf JSON cannot carry becomes its ``str()`` — a non-finite float
+    included, since ``null`` would claim it was absent — rather than failing the run at its
+    last event.
+    """
+    if isinstance(output, BaseModel):
+        try:
+            output = output.model_dump(mode="json")
+        except ValueError:
+            # PydanticSerializationError, which is a ValueError: one leaf pydantic cannot
+            # render as JSON. The python dump keeps the rest and the net below takes that
+            # leaf, so only its fidelity is lost — not the whole run's terminal event.
+            output = output.model_dump()
+    elif dataclasses.is_dataclass(output) and not isinstance(output, type):
+        output = dataclasses.asdict(output)
+    return json.loads(json.dumps(output, default=str), parse_constant=str)
+
+
+def _usage_of(result: RunResultStreaming) -> Usage:
+    usage: SDKUsage | None = getattr(result.context_wrapper, "usage", None)
+    if usage is None:
+        return Usage(input_tokens=0, output_tokens=0)
+    return Usage(input_tokens=usage.input_tokens, output_tokens=usage.output_tokens)
+
+
+__all__ = ["Launch", "OpenAIAgentsEngine", "SandboxScope"]

agentdeck/adapters/engines/openai_agents/reconcile.py

@@ -0,0 +1,178 @@
+"""Bringing the SDK session back in line with the event log after a crash between the
+two writes (ADR-D5: the log records the intent, the session is the engine's working memory).
+
+A turn writes the log first and the session second, so a process that dies in between
+leaves the log holding a message the session never got — a question the model would
+otherwise never see, or an answer it would think it never gave. On the next turn this
+compares the two message-level transcripts and appends whatever the session is missing.
+
+Message level means content and order, nothing more, and that has a lasting cost: the log
+stores tool results truncated and never stores reasoning items, so a repaired session holds
+plain text where an intact one held paired tool-call/tool-result items and reasoning, and it
+keeps holding it for the rest of that conversation. The model can then see an answer with no
+evidence of the tool call behind it. Accepted deliberately — the alternative is a turn the
+model cannot see at all.
+
+Two things are never replayed. The input of a run cancelled before it produced anything:
+``run.started`` says a turn was asked for, not that the engine took it, so replaying it would
+land in front of the question the user is about to retry. And anything at all into a session
+that has gone somewhere the log's prefix does not cover: that session is the authority on
+execution, a wrong guess about its tail is worse than a gap, and the disagreement is reported
+instead.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING, Any, Literal
+from weakref import WeakKeyDictionary
+
+from agentdeck.core.content import TextBlock
+from agentdeck.core.events import Custom, InputAppended, MessageCompleted, RunCancelled, RunStarted
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Sequence
+
+    from agents.items import TResponseInputItem
+    from agents.memory.session import Session
+
+    from agentdeck.core.content import Input
+    from agentdeck.core.events import Event
+
+logger = logging.getLogger(__name__)
+
+Role = Literal["user", "assistant"]
+Message = tuple[Role, str]
+"""One transcript entry: the role that spoke and the text it said."""
+
+DIVERGED = "openai_agents.session_diverged"
+"""This engine's own event for "the two stores disagree about more than a missing tail"."""
+
+_LOCKS: WeakKeyDictionary[asyncio.AbstractEventLoop, dict[str, asyncio.Lock]] = WeakKeyDictionary()
+
+
+async def reconcile(session: Session, history: Sequence[Event]) -> Custom | None:
+    """Append the messages ``history`` records and ``session`` is missing, before a turn runs.
+
+    Returns a ``custom`` payload when the two disagree about more than a missing tail, for
+    the caller to yield: a log line alone cannot be noticed, and the run is still perfectly
+    runnable on the session it has. ``None`` means nothing to do, or a repair that went in.
+    """
+    # ponytail: whole log against whole session, every turn — the same ceiling the Runtime's
+    # own per-turn log read already has, and the SDK reads the whole session anyway. Both want
+    # windowing together, once a session's history outgrows one read.
+    logged = _log_transcript(history)
+    if not logged:
+        return None
+    # Read-then-append is atomic only under this lock: two turns racing on one session would
+    # otherwise both apply the same repair and double the conversation. One process is as far as
+    # it reaches — two servers on one session are stopped at the door by #83's session claim.
+    async with _lock_for(session.session_id):
+        stored = _session_transcript(await session.get_items())
+        shared = min(len(stored), len(logged))
+        if stored[:shared] != logged[:shared]:
+            at = next(index for index in range(shared) if stored[index] != logged[index])
+            logger.warning(
+                "session %s disagrees with its log from message %d (%d session messages, %d logged): replaying nothing",
+                session.session_id,
+                at,
+                len(stored),
+                len(logged),
+            )
+            return Custom(
+                name=DIVERGED,
+                data={"agreed_through": at, "session_messages": len(stored), "logged_messages": len(logged)},
+            )
+        missing = logged[len(stored) :]
+        if not missing:
+            # Equal, or the session is ahead: an abandoned turn the engine had in fact started
+            # leaves an input in the session the log skips, and there is nothing to add for it.
+            return None
+        logger.info("replaying %d logged message(s) the session is missing into %s", len(missing), session.session_id)
+        await session.add_items([_as_item(role, text) for role, text in missing])
+    return None
+
+
+def _lock_for(session_id: str) -> asyncio.Lock:
+    """One lock per session, per event loop: a lock outlives neither, so one left behind by a
+    finished loop can never be acquired again."""
+    per_loop = _LOCKS.setdefault(asyncio.get_running_loop(), {})
+    lock = per_loop.get(session_id)
+    if lock is None:
+        lock = per_loop[session_id] = asyncio.Lock()
+    return lock
+
+
+def _log_transcript(history: Sequence[Event]) -> list[Message]:
+    """Every message the log says entered or left the loop, in order.
+
+    A turn's input lands on ``run.started``, mid-turn steering on ``input.appended``, the
+    assistant's side on ``message.completed``. Deltas are streaming UX and tool traffic is not
+    message level, so neither belongs here.
+
+    A run that was cancelled *before it got anywhere* contributes no input: the consumer walked
+    away before the engine read anything, so the session never saw that question and the user's
+    retry would arrive behind a copy of itself. Cancelled after an answer is the opposite case —
+    the SDK persists a turn's input and its output together, so both are in the session and
+    dropping the input would misalign the two transcripts on every later turn. A *failed* run
+    also keeps its input, because a session write that died is what a failure looks like here.
+    """
+    cancelled = {event.run_id for event in history if isinstance(event.payload, RunCancelled)}
+    answered = {event.run_id for event in history if isinstance(event.payload, MessageCompleted)}
+    abandoned = cancelled - answered
+    transcript: list[Message] = []
+    for event in history:
+        payload = event.payload
+        if isinstance(payload, RunStarted) and event.run_id in abandoned:
+            continue
+        if isinstance(payload, RunStarted | InputAppended):
+            transcript.append(("user", _text_of(payload.input)))
+        elif isinstance(payload, MessageCompleted):
+            transcript.append(("assistant", payload.text))
+    return transcript
+
+
+def _session_transcript(items: Sequence[TResponseInputItem]) -> list[Message]:
+    """The same view of the session: user and assistant messages only, tool calls,
+    tool results and reasoning items skipped."""
+    transcript: list[Message] = []
+    for item in items:
+        if not isinstance(item, dict):
+            continue
+        role = item.get("role")
+        if role == "user" or role == "assistant":  # noqa: PLR1714 — two comparisons narrow role, `in` does not
+            transcript.append((role, _item_text(item.get("content"))))
+    return transcript
+
+
+def _join_texts(texts: Iterable[str]) -> str:
+    """The one join both reconciliation sides call, so a multi-``TextBlock`` turn reads the same
+    string from the log and from the session instead of drifting by whose join ran. Before
+    ``_to_sdk_input`` could emit a parts list (#161), the two agreed only because the session's
+    content was the bare string this function's caller had already joined."""
+    return "\n".join(texts)
+
+
+def _item_text(content: Any) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        # A text part is ``input_text`` on the user side, ``output_text`` on the assistant
+        # side — both have a ``text`` key. An image or audio part has neither type nor key,
+        # so filtering on the key itself covers both roles without naming either type.
+        return _join_texts(
+            part["text"] for part in content if isinstance(part, dict) and isinstance(part.get("text"), str)
+        )
+    return ""
+
+
+def _text_of(input: Input) -> str:
+    return _join_texts(block.text for block in input if isinstance(block, TextBlock))
+
+
+def _as_item(role: Role, text: str) -> TResponseInputItem:
+    return {"role": role, "content": text}
+
+
+__all__ = ["DIVERGED", "reconcile"]

agentdeck/adapters/engines/openai_agents/runconfig.py

@@ -0,0 +1,118 @@
+"""How one run is configured: plain resolved values in, an SDK ``RunConfig`` out.
+
+The values arrive from the composition root (``agentdeck/composition.py``'s
+``resolve_run_settings``) rather than being read here, for the reason the store and the
+control port are already resolved there: an adapter that reaches for ``get_settings()``
+cannot be handed a different endpoint by a caller, and a second front door would have to
+mutate process state to get one.
+
+A bare :class:`RunSettings` therefore configures nothing at all — no provider, the SDK's
+own defaults — which is what a code-first caller wiring ``OpenAIAgentsEngine()`` by hand
+gets. Naming a model is what turns on the provider (see ``_provider``), but it never reaches
+``RunConfig.model``: the SDK overrides *every* agent's own model with that field once it is
+set, string or ``Model`` alike, so the settings-resolved default is handed to each agent
+instead, at compile time (``authoring.compile.compile_agent``) — the one place an agent's own
+declared model and the run's default both resolve to a single value before either ever
+reaches an SDK ``RunConfig``.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+from agents import ModelSettings, MultiProvider, OpenAIProvider, RunConfig
+from openai import AsyncOpenAI
+
+
+@dataclass(frozen=True, slots=True)
+class RunSettings:
+    """Everything a run's ``RunConfig`` is resolved from, as values an adapter can hold.
+
+    Defaults are the SDK's, not the project's: ``RunSettings()`` must leave a run exactly as
+    ``RunConfig()`` would, so the contract suite and a code-first caller keep configuring
+    their agents themselves.
+    """
+
+    model: str | None = None
+    api_key: str = ""
+    base_url: str = ""
+    ca_bundle: str = ""
+    use_responses: bool = True
+    workflow_name: str = "Agent workflow"
+    nest_handoff_history: bool = False
+    temperature: float | None = None
+    max_tokens: int | None = None
+    max_turns: int = 10
+
+
+def build_run_config(settings: RunSettings, *, sandbox: Any = None) -> RunConfig:
+    """One run's ``RunConfig``.
+
+    Built per run, never once and mutated: ``sandbox`` is this run's workspace handle, and a
+    shared config carrying somebody else's would hand two concurrent turns the same session.
+    """
+    return RunConfig(
+        workflow_name=settings.workflow_name,
+        # No `model=` here: the SDK's own `RunConfig.model` overrides every agent's model
+        # once set, so a per-agent default lives on the compiled SDK agent instead
+        # (`authoring.compile.compile_agent`), where an agent's own declaration still wins.
+        nest_handoff_history=settings.nest_handoff_history,
+        tracing_disabled=not tracing_enabled(),
+        model_provider=_provider(settings) or MultiProvider(),
+        # ``include_usage`` asks the Chat-Completions API to emit the streaming usage chunk
+        # (prompt/completion tokens) — without it, streamed turns carry no token counts at
+        # all, so ``usage.reported`` and ``run.completed`` would both report zero. No-op on
+        # the Responses API, where usage is always included.
+        model_settings=ModelSettings(
+            temperature=settings.temperature, max_tokens=settings.max_tokens, include_usage=True
+        ),
+        sandbox=sandbox,
+    )
+
+
+def tracing_enabled() -> bool:
+    """Opt-in switch for the SDK's default trace exporter (issue #61).
+
+    Off by default: a keyless/fake-model run (tests, CI, the M0 demo) has no OpenAI
+    account to export traces to, and the SDK's exporter otherwise attempts a real HTTPS
+    call on every run, logging a non-fatal ``Tracing client error 401``. Set
+    ``AGENTDECK_OPENAI_AGENTS_TRACING_ENABLED=true`` to restore it for a deployment that
+    wants the SDK's own trace export.
+
+    Not the Langfuse switch it used to be: traces are built from the event stream by
+    ``adapters/telemetry/langfuse``, so the SDK's own exporter is a separate question now
+    and answered separately.
+    """
+    raw = os.environ.get("AGENTDECK_OPENAI_AGENTS_TRACING_ENABLED")
+    return raw is not None and raw.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _provider(settings: RunSettings) -> OpenAIProvider | None:
+    """The provider for the endpoint these settings name, or ``None`` for "no endpoint".
+
+    A custom CA bundle needs its own httpx client (``verify=<path>``), so ``base_url`` and
+    ``api_key`` ride on that client rather than on the provider — the provider ignores both
+    once it is handed a client of its own.
+    """
+    if not settings.model:
+        return None
+    if settings.ca_bundle:
+        return OpenAIProvider(
+            openai_client=AsyncOpenAI(
+                base_url=settings.base_url or None,
+                api_key=settings.api_key,
+                http_client=httpx.AsyncClient(verify=settings.ca_bundle),
+            ),
+            use_responses=settings.use_responses,
+        )
+    return OpenAIProvider(
+        base_url=settings.base_url or None,
+        api_key=settings.api_key or None,
+        use_responses=settings.use_responses,
+    )
+
+
+__all__ = ["RunSettings", "build_run_config", "tracing_enabled"]