Merge remote-tracking branch 'origin/next' into SGPINF-1863-implement-span-queue-telemetry

Author: james-cardenas

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.11.4"
+  ".": "0.11.6"
 }

CHANGELOG.md

@@ -6,6 +6,61 @@
 
 * **tracing:** emit OTel metrics for async span queue depth, batch drain, and SGP export success/failure (HTTP status labels). Disable SDK-side recording with ``AGENTEX_TRACING_METRICS=0``.
 
+## 0.11.6 (2026-05-29)
+
+Full Changelog: [v0.11.5...v0.11.6](https://github.com/scaleapi/scale-agentex-python/compare/v0.11.5...v0.11.6)
+
+### Features
+
+* **api:** add cleaned_at field to task response types ([38ed338](https://github.com/scaleapi/scale-agentex-python/commit/38ed3384094f7f07f6b2482489f457fd1dc4f76d))
+* **deps:** bump openai-agents to >=0.14.3 for scale-sandbox oai_agents adapter ([#375](https://github.com/scaleapi/scale-agentex-python/issues/375)) ([e1b31d9](https://github.com/scaleapi/scale-agentex-python/commit/e1b31d91abadec572989b805592b788500d61994))
+* **lib:** expose data_converter kwarg on AgentexWorker and Temporal client APIs ([#372](https://github.com/scaleapi/scale-agentex-python/issues/372)) ([d04624e](https://github.com/scaleapi/scale-agentex-python/commit/d04624e6899e43a0429ef2deeb84509265b9f636))
+
+
+### Bug Fixes
+
+* **tutorials:** restore tutorial CI deps after agentex-sdk 0.11.5 (pytest + debugpy) ([#379](https://github.com/scaleapi/scale-agentex-python/issues/379)) ([0a2418c](https://github.com/scaleapi/scale-agentex-python/commit/0a2418cc9f9b06e3bdc46099106e50d226412fa0))
+
+
+### Performance Improvements
+
+* **tracing:** span queue linger + per-loop httpx keepalive ([#362](https://github.com/scaleapi/scale-agentex-python/issues/362)) ([feec842](https://github.com/scaleapi/scale-agentex-python/commit/feec8426f79e9f02533451d44997717655fd33f2))
+
+
+### Chores
+
+* back-merge release 0.11.5 into next ([#381](https://github.com/scaleapi/scale-agentex-python/issues/381)) ([ab5a7d9](https://github.com/scaleapi/scale-agentex-python/commit/ab5a7d9732a56d47efad469675c7630046106ef6))
+* **deps:** drop unused runtime deps and exclude tests from wheel ([#367](https://github.com/scaleapi/scale-agentex-python/issues/367)) ([f4303d1](https://github.com/scaleapi/scale-agentex-python/commit/f4303d1e7211783d19beca6554e44eb73bb29c42))
+
+
+### Refactors
+
+* **types:** promote protocol types to agentex.protocol.* ([#371](https://github.com/scaleapi/scale-agentex-python/issues/371)) ([6f1c14f](https://github.com/scaleapi/scale-agentex-python/commit/6f1c14fd61077da52038361642a9fbc4a0a56c8b))
+
+## 0.11.5 (2026-05-29)
+
+Full Changelog: [v0.11.4...v0.11.5](https://github.com/scaleapi/scale-agentex-python/compare/v0.11.4...v0.11.5)
+
+### Features
+
+* **api:** add cleaned_at field to task response types ([38ed338](https://github.com/scaleapi/scale-agentex-python/commit/38ed3384094f7f07f6b2482489f457fd1dc4f76d))
+* **deps:** bump openai-agents to >=0.14.3 for scale-sandbox oai_agents adapter ([#375](https://github.com/scaleapi/scale-agentex-python/issues/375)) ([e1b31d9](https://github.com/scaleapi/scale-agentex-python/commit/e1b31d91abadec572989b805592b788500d61994))
+
+
+### Performance Improvements
+
+* **tracing:** span queue linger + per-loop httpx keepalive ([#362](https://github.com/scaleapi/scale-agentex-python/issues/362)) ([feec842](https://github.com/scaleapi/scale-agentex-python/commit/feec8426f79e9f02533451d44997717655fd33f2))
+
+
+### Chores
+
+* **deps:** drop unused runtime deps and exclude tests from wheel ([#367](https://github.com/scaleapi/scale-agentex-python/issues/367)) ([f4303d1](https://github.com/scaleapi/scale-agentex-python/commit/f4303d1e7211783d19beca6554e44eb73bb29c42))
+
+
+### Refactors
+
+* **types:** promote protocol types to agentex.protocol.* ([#371](https://github.com/scaleapi/scale-agentex-python/issues/371)) ([6f1c14f](https://github.com/scaleapi/scale-agentex-python/commit/6f1c14fd61077da52038361642a9fbc4a0a56c8b))
+
 ## 0.11.4 (2026-05-26)
 
 Full Changelog: [v0.11.3...v0.11.4](https://github.com/scaleapi/scale-agentex-python/compare/v0.11.3...v0.11.4)

examples/tutorials/00_sync/050_openai_agents_local_sandbox/.dockerignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Environments
+.env**
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Git
+.git
+.gitignore
+
+# Misc
+.DS_Store

examples/tutorials/00_sync/050_openai_agents_local_sandbox/Dockerfile

@@ -0,0 +1,50 @@
+# syntax=docker/dockerfile:1.3
+FROM python:3.12-slim
+COPY --from=ghcr.io/astral-sh/uv:0.6.4 /uv /uvx /bin/
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    htop \
+    vim \
+    curl \
+    tar \
+    python3-dev \
+    postgresql-client \
+    build-essential \
+    libpq-dev \
+    gcc \
+    cmake \
+    netcat-openbsd \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN uv pip install --system --upgrade pip setuptools wheel
+
+ENV UV_HTTP_TIMEOUT=1000
+
+# Copy pyproject.toml and README.md to install dependencies
+COPY 00_sync/050_openai_agents_local_sandbox/pyproject.toml /app/050_openai_agents_local_sandbox/pyproject.toml
+COPY 00_sync/050_openai_agents_local_sandbox/README.md /app/050_openai_agents_local_sandbox/README.md
+
+WORKDIR /app/050_openai_agents_local_sandbox
+
+# Copy the project code
+COPY 00_sync/050_openai_agents_local_sandbox/project /app/050_openai_agents_local_sandbox/project
+
+# Copy the test files
+COPY 00_sync/050_openai_agents_local_sandbox/tests /app/050_openai_agents_local_sandbox/tests
+
+# Copy shared test utilities
+COPY test_utils /app/test_utils
+
+# Install the required Python packages with dev dependencies
+RUN uv pip install --system .[dev]
+
+# Set environment variables
+ENV PYTHONPATH=/app
+
+# Set test environment variables
+ENV AGENT_NAME=s050-openai-agents-local-sandbox
+
+# Run the agent using uvicorn
+CMD ["uvicorn", "project.acp:acp", "--host", "0.0.0.0", "--port", "8000"]

examples/tutorials/00_sync/050_openai_agents_local_sandbox/README.md

@@ -0,0 +1,113 @@
+# Tutorial 050: Sync OpenAI Agents SDK with a Local Sandbox
+
+This tutorial demonstrates how to build a **synchronous** agent on AgentEx using the
+[OpenAI Agents SDK](https://developers.openai.com/api/docs/guides/agents) and its
+**sandbox** runtime, running with the **local** (`unix_local`) backend.
+
+The agent is a "local sandbox assistant": it answers questions by actually running
+real shell commands (e.g. `python3 --version`, `ls /tmp`, `python3 -c "..."`)
+instead of guessing.
+
+## Key Concepts
+
+### Sync ACP
+The sync ACP model uses HTTP request/response for communication. The
+`@acp.on_message_send` handler receives a message, runs the agent, and returns the
+agent's final answer as a `TextContent`.
+
+### OpenAI Agents SDK Sandbox
+The OpenAI Agents SDK ships `agents.sandbox`, which lets you give an agent
+**capabilities** (instead of hand-written tools) that the runtime turns into real
+tools backed by a sandbox:
+
+- **`SandboxAgent`**: an `Agent` that is granted sandbox capabilities.
+- **Capabilities** (`from agents.sandbox.capabilities import Shell, Filesystem, Memory`):
+  each capability expands into a set of real tools. This tutorial uses `Shell`, which
+  lets the model run real shell commands.
+- **`SandboxRunConfig`** + a sandbox **client**: tells the runtime *where* the tools
+  actually execute.
+
+### The LOCAL sandbox (`UnixLocalSandboxClient`)
+This tutorial uses the local backend
+(`from agents.sandbox.sandboxes.unix_local import UnixLocalSandboxClient, UnixLocalSandboxClientOptions`),
+`backend_id="unix_local"`. The local sandbox runs shell commands **ON THE HOST** —
+the agent's own container/process. There is **no Docker, no Temporal, and no remote
+sandbox infrastructure** involved. This makes it the simplest way to give an agent a
+real shell.
+
+The sandbox is wired up through the SDK's `RunConfig`:
+
+```python
+from agents import Runner, set_tracing_disabled
+from agents.run_config import RunConfig
+from agents.sandbox import SandboxAgent, SandboxRunConfig
+from agents.sandbox.capabilities import Shell
+from agents.sandbox.sandboxes.unix_local import (
+    UnixLocalSandboxClient,
+    UnixLocalSandboxClientOptions,
+)
+
+set_tracing_disabled(True)  # avoid api.openai.com tracing 401 behind a gateway
+
+agent = SandboxAgent(
+    name="Local Sandbox Assistant",
+    instructions="...use the shell tools to actually run commands...",
+    capabilities=[Shell()],
+)
+run_config = RunConfig(
+    sandbox=SandboxRunConfig(
+        client=UnixLocalSandboxClient(),
+        options=UnixLocalSandboxClientOptions(),
+    )
+)
+result = await Runner.run(agent, input="what's the python version?", run_config=run_config)
+print(result.final_output)
+```
+
+`Runner.run` drives the full tool-call loop internally: the model issues shell
+commands, the local sandbox runs them on the host, the output is fed back, and the
+loop continues until the model produces a final answer.
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `project/acp.py` | ACP server and message handler (runs the sandbox agent) |
+| `project/agent.py` | `SandboxAgent` + `RunConfig(sandbox=...)` wiring + `run_agent` |
+| `project/tools.py` | Sandbox capability factory (`Shell`) |
+| `tests/test_agent.py` | Integration tests |
+| `manifest.yaml` | Agent configuration |
+
+## Running Locally
+
+```bash
+# From this directory
+agentex agents run
+```
+
+Set `OPENAI_API_KEY` (or `LITELLM_API_KEY` if you're behind the Scale LiteLLM
+gateway) in your environment or in a `.env` file in `project/` so the agent can call
+the model.
+
+## Running Tests
+
+```bash
+pytest tests/test_agent.py -v
+```
+
+## Notes
+
+- **No infra required.** Because this uses the `unix_local` backend, the shell tools
+  run directly in the agent's process — no Docker daemon, no Temporal, no remote
+  sandbox. Swap the client for a remote/containerized backend to isolate execution.
+- **Tracing.** `set_tracing_disabled(True)` turns off the OpenAI Agents SDK's native
+  tracer (which would otherwise try to ship traces to `api.openai.com`). The manifest
+  also sets `OPENAI_AGENTS_DISABLE_TRACING=1`. AgentEx/SGP tracing still runs via the
+  tracing manager configured in `acp.py` when SGP credentials are present.
+- **Capabilities are the tools.** To let the agent do more, add capabilities in
+  `project/tools.py` (e.g. `Filesystem()`, `Memory()`).
+
+## Further Reading
+
+- OpenAI Agents SDK guide: https://developers.openai.com/api/docs/guides/agents
+- The next evolution of the Agents SDK: https://openai.com/index/the-next-evolution-of-the-agents-sdk/

examples/tutorials/00_sync/050_openai_agents_local_sandbox/manifest.yaml

@@ -0,0 +1,61 @@
+build:
+  context:
+    root: ../../
+    include_paths:
+      - 00_sync/050_openai_agents_local_sandbox
+      - test_utils
+    dockerfile: 00_sync/050_openai_agents_local_sandbox/Dockerfile
+    dockerignore: 00_sync/050_openai_agents_local_sandbox/.dockerignore
+
+local_development:
+  agent:
+    port: 8000
+    host_address: host.docker.internal
+  paths:
+    acp: project/acp.py
+
+agent:
+  acp_type: sync
+  name: s050-openai-agents-local-sandbox
+  description: A sync OpenAI Agents SDK agent using a local (unix_local) sandbox
+
+  temporal:
+    enabled: false
+
+  credentials:
+    - env_var_name: OPENAI_API_KEY
+      secret_name: openai-api-key
+      secret_key: api-key
+    - env_var_name: REDIS_URL
+      secret_name: redis-url-secret
+      secret_key: url
+    - env_var_name: SGP_API_KEY
+      secret_name: sgp-api-key
+      secret_key: api-key
+    - env_var_name: SGP_ACCOUNT_ID
+      secret_name: sgp-account-id
+      secret_key: account-id
+    - env_var_name: SGP_CLIENT_BASE_URL
+      secret_name: sgp-client-base-url
+      secret_key: url
+
+  env:
+    OPENAI_AGENTS_DISABLE_TRACING: "1"
+
+deployment:
+  image:
+    repository: ""
+    tag: "latest"
+
+  global:
+    agent:
+      name: "s050-openai-agents-local-sandbox"
+      description: "A sync OpenAI Agents SDK agent using a local (unix_local) sandbox"
+    replicaCount: 1
+    resources:
+      requests:
+        cpu: "500m"
+        memory: "1Gi"
+      limits:
+        cpu: "1000m"
+        memory: "2Gi"