Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation

Suggested
Overview Models Agents Tools Audio & voice Production API reference

Create an agent session

beta.agents.sessions.create(SessionCreateParams**kwargs) -> AgentSession
POST/agents/sessions

Creates a managed agent session, optionally submits initial input, and returns the session or streams its events when stream is true. See running sessions.

ParametersExpand Collapse
environment: EnvironmentParam

An inline execution environment or a reference to an environment template.

agent: Optional[Agent]

Agent configuration. With agent_id, supplied fields override the saved agent for this session. Without agent_id, model is required.

agent_id: Optional[str]

The ID of a saved reusable agent. Omit agent to use its configuration unchanged.

minLength0
maxLength64
input: Optional[Union[str, Iterable[AgentSessionInputMessageParam], null]]

Initial input to submit when the session is created. A string is shorthand for a single user message. Required when environment.type is none, or when stream is true for an environment that is not self_hosted; optional for self-hosted and non-streaming execution environments.

metadata: Optional[Dict[str, str]]

Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. Omission or null defaults to an empty map.

spend_control: Optional[SpendControl]

Optional spending limit in USD cents. Omission or null creates an unlimited session.

stream: Optional[Literal[false]]

Whether to stream session events as server-sent events. Defaults to false.

vault_ids: Optional[Sequence[str]]

The IDs of vaults made available to the session.

ReturnsExpand Collapse
class AgentSession: …

A Managed Agents session.

id: str

The ID of the session.

minLength0
agent: Agent

The agent running in the session.

created_at: int

The Unix timestamp, in seconds, when the session was created.

formatint64
environment: Environment

The execution environment for the session.

error: Optional[str]

The error that caused the session to fail, if any.

minLength0
last_active_at: int

The Unix timestamp, in seconds, when the session was last active.

formatint64
metadata: Dict[str, str]

Custom string key-value pairs attached to the session.

object: Literal["agent.session"]

The object type. Always agent.session.

required_actions: List[RequiredAction]

Actions that must be completed before the session can continue.

status: Literal["idle", "in_progress", "requires_action", "failed"]

The current status of the session.

usage: Optional[TokenUsage]

Best-effort token usage for the session, or null if unknown. Recorded usage may change.

vault_ids: List[str]

The IDs of vaults made available to the session.

spend_control: Optional[SpendControl]

Configured spending limit and best-effort consumption, in USD cents. Unlimited sessions omit this object.

Create an agent session

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
for session in client.beta.agents.sessions.create(
    environment={
        "type": "none"
    },
):
  print(session)
{
  "id": "id",
  "agent": {
    "id": "id",
    "instructions": "instructions",
    "model": "model",
    "multi_agent": {
      "enabled": true,
      "max_concurrent_subagents": 1
    },
    "name": "name",
    "reasoning": {
      "effort": "none",
      "summary": "concise"
    },
    "service_tier": "auto",
    "text": {
      "format": {
        "type": "text"
      },
      "verbosity": "low"
    },
    "tools": [
      {
        "defer_loading": true,
        "description": "description",
        "name": "name",
        "parameters": {
          "foo": "bar"
        },
        "type": "function"
      }
    ]
  },
  "created_at": 0,
  "environment": {
    "type": "none"
  },
  "error": "error",
  "last_active_at": 0,
  "metadata": {
    "foo": "string"
  },
  "object": "agent.session",
  "required_actions": [
    {
      "request": {
        "credential_origin": "credential_origin",
        "fields": [
          {
            "id": "id",
            "label": "label",
            "required": true,
            "type": "type"
          }
        ],
        "options": [
          {
            "id": "id",
            "field_ids": [
              "string"
            ],
            "label": "label"
          }
        ],
        "reason": "reason",
        "type": "browser_authentication"
      },
      "request_id": "request_id",
      "turn_id": "turn_id",
      "type": "computer_use_approval_request"
    }
  ],
  "status": "idle",
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 0
  },
  "vault_ids": [
    "string"
  ],
  "spend_control": {
    "consumed": 0,
    "limit": 1
  }
}
Returns Examples
{
  "id": "id",
  "agent": {
    "id": "id",
    "instructions": "instructions",
    "model": "model",
    "multi_agent": {
      "enabled": true,
      "max_concurrent_subagents": 1
    },
    "name": "name",
    "reasoning": {
      "effort": "none",
      "summary": "concise"
    },
    "service_tier": "auto",
    "text": {
      "format": {
        "type": "text"
      },
      "verbosity": "low"
    },
    "tools": [
      {
        "defer_loading": true,
        "description": "description",
        "name": "name",
        "parameters": {
          "foo": "bar"
        },
        "type": "function"
      }
    ]
  },
  "created_at": 0,
  "environment": {
    "type": "none"
  },
  "error": "error",
  "last_active_at": 0,
  "metadata": {
    "foo": "string"
  },
  "object": "agent.session",
  "required_actions": [
    {
      "request": {
        "credential_origin": "credential_origin",
        "fields": [
          {
            "id": "id",
            "label": "label",
            "required": true,
            "type": "type"
          }
        ],
        "options": [
          {
            "id": "id",
            "field_ids": [
              "string"
            ],
            "label": "label"
          }
        ],
        "reason": "reason",
        "type": "browser_authentication"
      },
      "request_id": "request_id",
      "turn_id": "turn_id",
      "type": "computer_use_approval_request"
    }
  ],
  "status": "idle",
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 0
  },
  "vault_ids": [
    "string"
  ],
  "spend_control": {
    "consumed": 0,
    "limit": 1
  }
}