Choose the correct SDK surface
These examples use the OpenAI Python SDK's client.beta.agents.sessions namespace, not Responses or Agents SDK Runner. For raw HTTP, the session root is https://api.openai.com/v1/agents/sessions with server-side Bearer authorization and OpenAI-Beta: agents=v1. Keep the API key outside browser code.
| Task | Python method | Contract |
|---|---|---|
| Start work | sessions.create(...) | agent, environment, input; stream=True for events |
| Inspect dependencies | sessions.retrieve(session_id) | Read current required_actions |
| Send message or tool result | sessions.events.create(session_id, events=[...]) | Input event batch; not the final answer |
| Observe live changes | sessions.events.stream(session_id) | Live events, not missed-event replay |
| Recover saved output | sessions.items.list(session_id, order='asc', limit=100) | Paginated saved items; consume every needed page |
Match the pending call
A function action carries type=function_call, name, arguments, turn_id, and call_id. Arguments are an object here. Validate them against your tool schema and authenticated ownership. Do not execute a historical function-call item merely because it appears in saved output.
# action is a current required_actions entry converted with to_dict().
result = {
'type': 'agent.session.input.tool_result',
'turn_id': action['turn_id'],
'call_id': action['call_id'],
'success': True,
'output': json.dumps({'order_id': 'ORDER-100', 'status': 'shipped'}),
}
client.beta.agents.sessions.events.create(session_id, events=[result])
# Failure uses success=False and error='Safe explanation', not output.Map signals to application behavior
Stream events and webhook deliveries are different interfaces. Keep business status separate from transport and turn status.
| Signal | Application behavior |
|---|---|
| agent.session.requires_action | Inspect pending function or environment dependency |
| agent.session.turn.output_text.delta | Accumulate the matching item/content part |
| agent.session.turn.output_text.done | Replace partial text with complete text |
| agent.session.turn.completed | Finish only the root turn; inspect business outcome |
| agent.session.turn.failed / cancelled | Display terminal failure/cancellation for the root |
| agent.session.idle or closed stream | Do not infer task success |
Use three different identities
Store session ownership for access control, turn_id plus call_id for tool-result correlation, and a business-operation key for side effects. The event-create method also accepts idempotency_key in Python (idempotencyKey in TypeScript). Persist the same key and identical batch when retrying that submission. An event key does not deduplicate a payment performed by your own service.
| Failure | Safe next step |
|---|---|
| Invalid arguments or denied access | Return a safe tool failure; do not retry unchanged |
| Result submission times out | Retrieve current action; resend stored result if still pending |
| Business write outcome is unknown | Reconcile with the downstream operation ID before repeating |
| Browser disconnects | Keep session ID; recover saved state, not a new task |
| Authentication or access error | Correct credentials/project access before retrying |
Verify the boundary before release
Record the SDK version in your lockfile. Exercise success, denied ownership, malformed arguments, duplicate calls, and interrupted result delivery. Confirm that logs contain correlation IDs but not secrets or unnecessary customer data. Use the linked API reference for optional fields and SDK-version-specific types.
Read the official reference
Check the source for current API fields, account requirements, and service limits.
OpenAI: functions Events and saved items Session input event reference Run sessions