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

AgentSession beta().agents().sessions().create(SessionCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())
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
SessionCreateParams params
EnvironmentParam environment

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

Optional<Agent> agent

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

Optional<String> agentId

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

minLength0
maxLength64
Optional<Input> input

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.

Optional<Metadata> metadata

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.

Optional<SpendControl> spendControl

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

Optional<List<String>> vaultIds

The IDs of vaults made available to the session.

ReturnsExpand Collapse
class AgentSession:

A Managed Agents session.

String id

The ID of the session.

minLength0
Agent agent

The agent running in the session.

long createdAt

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

formatint64
Environment environment

The execution environment for the session.

Optional<String> error

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

minLength0
long lastActiveAt

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

formatint64
Metadata metadata

Custom string key-value pairs attached to the session.

JsonValue; object_ "agent.session"constant"agent.session"constant

The object type. Always agent.session.

List<RequiredAction> requiredActions

Actions that must be completed before the session can continue.

Status status

The current status of the session.

Optional<TokenUsage> usage

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

List<String> vaultIds

The IDs of vaults made available to the session.

Optional<SpendControl> spendControl

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

Create an agent session

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.beta.agents.AgentSession;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        SessionCreateParams params = SessionCreateParams.builder()
            .environmentNone()
            .build();
        AgentSession agentSession = client.beta().agents().sessions().create(params);
    }
}
{
  "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
  }
}