[Release] openai/openai-agents-python v0.17.0: v0.17.0

OpenAI Agents Python SDK v0.17.0 introduces gpt-realtime-2 as the default model for RealtimeAgents and implements a critical security fix for sandbox local source materialization. The update constrains local artifact sources to remain within the SDK process base directory unless explicitly granted via SandboxPathGrant, closing a local artifact boundary vulnerability. Applications relying on copying trusted files from outside the base directory must now explicitly grant those paths at the manifest level.

Key Points

• •RealtimeAgent default model updated to gpt-realtime-2 for improved real-time capabilities
• •Sandbox local source materialization now enforces base_dir boundary by default for security
• •LocalFile.src and LocalDir.src must stay within SDK process base_dir or be covered by Manifest.extra_path_grants
• •Use SandboxPathGrant to explicitly grant access to trusted host paths outside base_dir
• •Mark path grants as read_only=True when sandbox only needs read access to reduce attack surface
• •Relative local sources are resolved from base_dir; absolute paths must already be inside it or explicitly granted
• •extra_path_grants should be treated as trusted application configuration, never populated from untrusted sources
• •Migration required for applications that previously copied files from outside base_dir without explicit grants
• •Fixed Responses context-management extra_args collision bug
• •Breaking change requires audit of existing sandbox manifests to ensure proper path grant configuration

Workflow Diagram

Concepts

Artifacts (1)

from pathlib import Path

from agents.sandbox import Manifest, SandboxPathGrant
from agents.sandbox.entries import Dir, LocalDir

# This is an absolute host path outside the SDK process base_dir.
TRUSTED_DOCS_ROOT = Path("/opt/my-app/docs")

manifest = Manifest(
    extra_path_grants=(
        # This host root is outside the SDK process base_dir, so the manifest must grant it.
        SandboxPathGrant(path=str(TRUSTED_DOCS_ROOT), read_only=True),
    ),
    entries={
        # No grant is needed for local sources that stay under the SDK process base_dir.
        "fixtures": LocalDir(src=Path("fixtures"), description="Local test fixtures."),
        # This entry reads from the granted host root and copies it into the sandbox workspace.
        "docs": LocalDir(src=TRUSTED_DOCS_ROOT, description="Trusted local documents."),
        # Dir creates a sandbox workspace directory; it does not read from the host filesystem.
        "output": Dir(description="Generated artifacts."),
    },
)