Files
codex/sdk/python/examples/16_external_message/sync.py
Ahmed Ibrahim 1a4096e273 Add untrusted external messages to the Python SDK (#44086)
## Why

Applications need to deliver content from other agents, tools, or services with tool-level authority, without treating it as user input or granting authorization.

## What changed

- Export `ExternalMessage` for sync and async `run(...)` and `turn(...)`, accepting text or structured content with a tool name and optional namespace. Send it through `toolOutput` and require CLI 0.151.0 or newer.
- Support starting a turn or joining an active regular turn while preserving external content as function output in history. Keep external messages separate from user-input lists and `steer(...)`.
- Give turn handles independent subscriptions, replaying completed items and latest usage to joining handles. Release consumed transient events and clean up subscriptions on closure, failure, or cancellation.
- Document the authority boundary and add sync and async examples.

## Testing

Add coverage for wire representations, input validation, runtime compatibility, tool authority across resume, active-turn joins, and tool-output truncation. Add subscription tests for replay, concurrent consumers, early completion, cancellation, and cleanup.

GitOrigin-RevId: 6106327085fd9c4bd11b71e20b3d8e74738b8bb5
2026-09-09 06:54:18 +00:00

34 lines
1.1 KiB
Python

"""Process an untrusted notification within a task authorized by the user."""
import sys
from pathlib import Path
_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
if str(_EXAMPLES_ROOT) not in sys.path:
sys.path.insert(0, str(_EXAMPLES_ROOT))
from _bootstrap import ensure_local_sdk_src, runtime_config
ensure_local_sdk_src()
from openai_codex import Codex, ExternalMessage, Sandbox
with Codex(config=runtime_config()) as codex:
thread = codex.thread_start(sandbox=Sandbox.read_only)
thread.run(
"When deployment notifications arrive, summarize their status and suggest "
"what I should check. Do not change files or deploy anything."
)
# External content has tool authority; it does not supply user permission.
result = thread.run(
ExternalMessage(
tool_name="notifications",
namespace="slack",
content="Staging deployment failed: the health check returned HTTP 503.",
),
source="slack_notification",
)
print("status:", result.status)
print("text:", result.final_response)