Class: OpenAI::Resources::Beta::Agents::Sessions

Inherits:
Object
  • Object
show all
Defined in:
lib/openai/resources/beta/agents/sessions.rb,
lib/openai/resources/beta/agents/sessions/items.rb,
lib/openai/resources/beta/agents/sessions/turns.rb,
lib/openai/resources/beta/agents/sessions/events.rb,
lib/openai/resources/beta/agents/sessions/artifacts.rb,
lib/openai/resources/beta/agents/sessions/subagents.rb,
lib/openai/resources/beta/agents/sessions/subagents/items.rb,
lib/openai/resources/beta/agents/sessions/subagents/turns.rb,
lib/openai/resources/beta/agents/sessions/subagents/turns/items.rb,
sig/openai/helpers/agents.rbs,
sig/openai/resources/beta/agents/sessions.rbs,
sig/openai/resources/beta/agents/sessions/items.rbs,
sig/openai/resources/beta/agents/sessions/turns.rbs,
sig/openai/resources/beta/agents/sessions/events.rbs,
sig/openai/resources/beta/agents/sessions/artifacts.rbs,
sig/openai/resources/beta/agents/sessions/subagents.rbs,
sig/openai/resources/beta/agents/sessions/subagents/items.rbs,
sig/openai/resources/beta/agents/sessions/subagents/turns.rbs,
sig/openai/resources/beta/agents/sessions/subagents/turns/items.rbs

Defined Under Namespace

Classes: Artifacts, Events, Items, Subagents, Turns

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Sessions

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Sessions.

Parameters:



294
295
296
297
298
299
300
301
 
# File 'lib/openai/resources/beta/agents/sessions.rb', line 294

def initialize(client:)
  @client = client
  @subagents = OpenAI::Resources::Beta::Agents::Sessions::Subagents.new(client: client)
  @artifacts = OpenAI::Resources::Beta::Agents::Sessions::Artifacts.new(client: client)
  @items = OpenAI::Resources::Beta::Agents::Sessions::Items.new(client: client)
  @events = OpenAI::Resources::Beta::Agents::Sessions::Events.new(client: client)
  @turns = OpenAI::Resources::Beta::Agents::Sessions::Turns.new(client: client)
end

Instance Attribute Details

#artifacts ⇒ OpenAI::Resources::Beta::Agents::Sessions::Artifacts (readonly)

Returns:



12
13
14
 
# File 'lib/openai/resources/beta/agents/sessions.rb', line 12

def artifacts
  @artifacts
end

#events ⇒ OpenAI::Resources::Beta::Agents::Sessions::Events (readonly)

Returns:



18
19
20
 
# File 'lib/openai/resources/beta/agents/sessions.rb', line 18

def events
  @events
end

#items ⇒ OpenAI::Resources::Beta::Agents::Sessions::Items (readonly)

Returns:



15
16
17
 
# File 'lib/openai/resources/beta/agents/sessions.rb', line 15

def items
  @items
end

#subagents ⇒ OpenAI::Resources::Beta::Agents::Sessions::Subagents (readonly)

Returns:



9
10
11
 
# File 'lib/openai/resources/beta/agents/sessions.rb', line 9

def subagents
  @subagents
end

#turns ⇒ OpenAI::Resources::Beta::Agents::Sessions::Turns (readonly)

Returns:



21
22
23
 
# File 'lib/openai/resources/beta/agents/sessions.rb', line 21

def turns
  @turns
end

Instance Method Details

#create(environment:, agent: nil, agent_id: nil, input: nil, metadata: nil, vault_ids: nil, request_options: {}) ⇒ OpenAI::Models::Beta::AgentSession

See OpenAI::Resources::Beta::Agents::Sessions#create_streaming for streaming counterpart.

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

Parameters:

Returns:

See Also:



61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/openai/resources/beta/agents/sessions.rb', line 61

def create(params)
  parsed, options = OpenAI::Beta::Agents::SessionCreateParams.dump_request(params)
  if parsed[:stream]
    message = "Please use `#create_streaming` for the streaming use case."
    raise ArgumentError.new(message)
  end

  @client.request(
    method: :post,
    path: "agents/sessions",
    body: parsed,
    model: OpenAI::Beta::AgentSession,
    security: {bearer_auth: true},
    options: {extra_headers: {"OpenAI-Beta" => "agents=v1"}, **options}
  )
end

#create_streaming(environment:, agent: nil, agent_id: nil, input: nil, metadata: nil, vault_ids: nil, request_options: {}) ⇒ OpenAI::Internal::Stream<OpenAI::Models::Beta::AgentSessionErrorEvent, OpenAI::Models::Beta::AgentSessionEnvironmentReadyEvent, OpenAI::Models::Beta::AgentSessionEnvironmentResetEvent, OpenAI::Models::Beta::AgentOutputCommandExecutionOutputDeltaEvent, OpenAI::Models::Beta::AgentSessionCreatedEvent, OpenAI::Models::Beta::AgentSessionTurnCreatedEvent, OpenAI::Models::Beta::AgentSessionTurnInProgressEvent, OpenAI::Models::Beta::AgentSessionTurnCompletedEvent, OpenAI::Models::Beta::AgentSessionTurnFailedEvent, OpenAI::Models::Beta::AgentSessionTurnCancelledEvent, OpenAI::Models::Beta::AgentSessionTurnItemAddedEvent, OpenAI::Models::Beta::AgentSessionIdleEvent, OpenAI::Models::Beta::AgentSessionInProgressEvent, OpenAI::Models::Beta::AgentSessionRequiresActionEvent, OpenAI::Models::Beta::AgentSessionFailedEvent, OpenAI::Models::Beta::AgentSessionEnvironmentPendingEvent, OpenAI::Models::Beta::AgentSessionEnvironmentConnectedEvent, OpenAI::Models::Beta::AgentSessionEnvironmentDisconnectedEvent, OpenAI::Models::Beta::AgentSessionEnvironmentFailedEvent, OpenAI::Models::Beta::AgentSessionSubagentCreatedEvent, OpenAI::Models::Beta::AgentSessionSubagentActiveEvent, OpenAI::Models::Beta::AgentSessionSubagentClosedEvent, OpenAI::Models::Beta::AgentSessionTurnItemDoneEvent, OpenAI::Models::Beta::AgentSessionTurnContentPartAddedEvent, OpenAI::Models::Beta::AgentSessionTurnContentPartDoneEvent, OpenAI::Models::Beta::AgentSessionTurnOutputTextDeltaEvent, OpenAI::Models::Beta::AgentSessionTurnOutputTextDoneEvent, OpenAI::Models::Beta::AgentSessionTurnReasoningSummaryPartAddedEvent, OpenAI::Models::Beta::AgentSessionTurnReasoningSummaryPartDoneEvent, OpenAI::Models::Beta::AgentSessionTurnReasoningSummaryTextDeltaEvent, OpenAI::Models::Beta::AgentSessionTurnReasoningSummaryTextDoneEvent>

See OpenAI::Resources::Beta::Agents::Sessions#create for non-streaming counterpart.

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

Parameters:

Returns:

See Also:



116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/openai/resources/beta/agents/sessions.rb', line 116

def create_streaming(params)
  parsed, options = OpenAI::Beta::Agents::SessionCreateParams.dump_request(params)
  unless parsed.fetch(:stream, true)
    message = "Please use `#create` for the non-streaming use case."
    raise ArgumentError.new(message)
  end

  parsed.store(:stream, true)
  @client.request(
    method: :post,
    path: "agents/sessions",
    headers: {"accept" => "text/event-stream", "accept-encoding" => "identity"},
    body: parsed,
    stream: OpenAI::Internal::Stream,
    model: OpenAI::Beta::AgentSessionEvent,
    security: {bearer_auth: true},
    options: {extra_headers: {"OpenAI-Beta" => "agents=v1"}, **options}
  )
end

#delete(session_id, request_options: {}) ⇒ OpenAI::Models::Beta::AgentSessionDeleted

Removes a managed agent session from the public API and returns a deletion confirmation. If backend execution has ended, deletion can cancel a still-open public turn and abandon unpublished outputs. Running execution must be cancelled first. Physical cleanup may continue asynchronously. See managing sessions.

Parameters:

  • session_id (String) —

    The ID of the session.

  • request_options (OpenAI::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



248
249
250
251
252
253
254
255
256
 
# File 'lib/openai/resources/beta/agents/sessions.rb', line 248

def delete(session_id, params = {})
  @client.request(
    method: :delete,
    path: ["agents/sessions/%1$s", session_id],
    model: OpenAI::Beta::AgentSessionDeleted,
    security: {bearer_auth: true},
    options: {extra_headers: {"OpenAI-Beta" => "agents=v1"}, **params[:request_options].to_h}
  )
end

#list(after: nil, agent_id: nil, limit: nil, order: nil, request_options: {}) ⇒ OpenAI::Internal::CursorPage<OpenAI::Models::Beta::AgentSession>

Lists managed agent sessions using ID-based pagination and the requested sort order. See managing sessions.

Parameters:

  • after (String) —

    Return resources after this resource ID in the selected order.

  • agent_id (String) —

    Only return sessions whose root agent has this ID. Omit to return sessions for all agents.

  • limit (Integer, nil) —

    The maximum number of resources to return.

  • order (Symbol, OpenAI::Models::Beta::Agents::SessionListParams::Order) —

    Sort order by the created_at timestamp. Use asc for ascending order or desc for descending order. Defaults to desc.

  • request_options (OpenAI::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



218
219
220
221
222
223
224
225
226
227
228
229
230
 
# File 'lib/openai/resources/beta/agents/sessions.rb', line 218

def list(params = {})
  parsed, options = OpenAI::Beta::Agents::SessionListParams.dump_request(params)
  query = OpenAI::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "agents/sessions",
    query: query,
    page: OpenAI::Internal::CursorPage,
    model: OpenAI::Beta::AgentSession,
    security: {bearer_auth: true},
    options: {extra_headers: {"OpenAI-Beta" => "agents=v1"}, **options}
  )
end

#retrieve(session_id, request_options: {}) ⇒ OpenAI::Models::Beta::AgentSession

Retrieves the current state of a managed agent session. See managing sessions.

Parameters:

  • session_id (String) —

    The ID of the session.

  • request_options (OpenAI::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



149
150
151
152
153
154
155
156
157
 
# File 'lib/openai/resources/beta/agents/sessions.rb', line 149

def retrieve(session_id, params = {})
  @client.request(
    method: :get,
    path: ["agents/sessions/%1$s", session_id],
    model: OpenAI::Beta::AgentSession,
    security: {bearer_auth: true},
    options: {extra_headers: {"OpenAI-Beta" => "agents=v1"}, **params[:request_options].to_h}
  )
end

#stream(session_id, input:, tool_handlers: {}, idempotency_key: nil, request_options: {}) {|stream| ... } ⇒ OpenAI::Helpers::Agents::SessionStream

Submit input to an idle session and stream one turn through idle or failure. The caller must be the session's only input writer during iteration. Handlers run sequentially; failures submit a generic error without exception text. Input and each tool result use distinct retry-safe idempotency keys. A block closes the connection on every exit path without cancelling the turn.

Parameters:

Yield Parameters:

Returns:



271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
 
# File 'lib/openai/resources/beta/agents/sessions.rb', line 271

def stream(session_id, input:, tool_handlers: {}, idempotency_key: nil, request_options: {})
  stream = OpenAI::Helpers::Agents::SessionStream.new(
    sessions: self,
    session_id: session_id,
    input: input,
    tool_handlers: tool_handlers,
    idempotency_key: idempotency_key,
    request_options: request_options
  )
  return stream unless block_given?

  begin
    yield stream
  ensure
    stream.close
  end

  stream
end

#update(session_id, agent: nil, metadata: nil, request_options: {}) ⇒ OpenAI::Models::Beta::AgentSession

Updates session metadata, model, reasoning effort, or service tier. Model settings apply to subsequent turns. Omitted fields are unchanged. See managing sessions.

Parameters:

  • session_id (String) —

    The ID of the session.

  • agent (OpenAI::Models::Beta::Agents::SessionUpdateParams::Agent) —

    Model settings for subsequent turns. Omitted fields stay unchanged.

  • metadata (Hash{Symbol=>String}, nil) —

    Replaces all metadata. Omit to leave unchanged, or pass null or {} to clear it. Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters.

  • request_options (OpenAI::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/openai/resources/beta/agents/sessions.rb', line 181

def update(session_id, params = {})
  parsed, options = OpenAI::Beta::Agents::SessionUpdateParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["agents/sessions/%1$s", session_id],
    body: parsed,
    model: OpenAI::Beta::AgentSession,
    security: {bearer_auth: true},
    options: {extra_headers: {"OpenAI-Beta" => "agents=v1"}, **options}
  )
end