Class AgentSessionResource

Index

Constructors

constructor

Methods

cancel create delete get list message update

Constructors

constructor

new AgentSessionResource(http: HttpClient): AgentSessionResource
Parameters
- http: HttpClient
Returns AgentSessionResource
- Defined in packages/sdk/src/v1/resources/agent_sessions.ts:9

Methods

cancel

cancel(agentSession: string): Promise<AgentSession>
Cancel an agent session Requests cancellation of an active agent session. The session status is set to "cancelled" and any in-progress agent turn is interrupted as soon as the platform can safely stop it. If the session is already in a terminal state ("completed", "failed", or "cancelled"), the call succeeds and returns the session unchanged — it is safe to call this endpoint more than once. Requires an app-scoped API key. The session must belong to an agent owned by the authenticated app.
Parameters
- agentSession: string
  Agent session ID (ase_...) of the session to cancel.
Returns Promise<AgentSession>
The agent session after the cancellation request is applied.
- Defined in packages/sdk/src/v1/resources/agent_sessions.ts:147

create

create(
    input: {
        agent: string;
        instructions: string;
        max_runs_per_turn?: number;
        max_tokens?: number;
        max_turns?: number;
        metadata?: Record<string, unknown>;
        name?: string;
        start_idle?: boolean;
        team?: string;
        thread?: string;
        user?: string;
    },
): Promise<AgentSession>
Create an agent session Creates a new agent session and enqueues it for execution. The session begins in "pending" status and transitions to "running" once the platform picks it up. Subscribe to the session stream endpoint to receive real-time status updates. You must supply the ID of an agent that the authenticated app owns and a plain-text instructions string describing the task. All other parameters are optional and default to the agent's configured limits when omitted. Set start_idle to true to create the session without running an opening turn — it begins in "waiting" status and runs its first turn only once you post a message (see the message endpoint). Use this when you want the first message to drive the session instead of the instructions alone. Requires an app-scoped API key. Returns HTTP 201 on success.
Parameters
- input: {
      agent: string;
      instructions: string;
      max_runs_per_turn?: number;
      max_tokens?: number;
      max_turns?: number;
      metadata?: Record<string, unknown>;
      name?: string;
      start_idle?: boolean;
      team?: string;
      thread?: string;
      user?: string;
  }
  Request body.
  - agent: string
    Agent ID (agi_...) of the agent that will execute the session.
  - instructions: string
    Plain-text task description given to the agent as its primary objective for this session.
  - Optionalmax_runs_per_turn?: number
    Maximum number of tool invocations allowed within a single agent turn. Defaults to 25.
  - Optionalmax_tokens?: number
    Maximum number of tokens the agent may consume across all turns. Defaults to 20,000.
  - Optionalmax_turns?: number
    Maximum number of agent turns before the session is automatically terminated. Defaults to 100.
  - Optionalmetadata?: Record<string, unknown>
    Arbitrary key-value metadata to attach to the session. Stored and returned as-is; not interpreted by the platform.
  - Optionalname?: string
    Human-readable display name for the session. Useful for identifying sessions in the dashboard. null if omitted.
  - Optionalstart_idle?: boolean
    When true, create the session without running an opening turn. The session starts in "waiting" status and runs its first turn only when you post a message. Defaults to false, which runs an initial turn from instructions immediately.
  - Optionalteam?: string
    Team ID (tea_...) to associate with this session for access-control and attribution purposes. null if omitted.
  - Optionalthread?: string
    Thread ID (thr_...) to link this session to an existing conversation thread. null if omitted.
  - Optionaluser?: string
    User ID to associate with this session for attribution purposes. null if omitted.
Returns Promise<AgentSession>
The newly created agent session.
- Defined in packages/sdk/src/v1/resources/agent_sessions.ts:78

delete

delete(agentSession: string): Promise<void>
Delete an agent session Permanently deletes an agent session and its associated data. This action is irreversible — the session record, its trajectory, and all inbox messages are removed. To stop a running session without deleting it, use the cancel endpoint instead. The session must be in a terminal state ("completed", "failed", or "cancelled") before it can be deleted; attempting to delete an active session returns 422. Requires an app-scoped API key. Returns HTTP 204 with no body on success.
Parameters
- agentSession: string
  Agent session ID (ase_...) of the session to delete.
Returns Promise<void>
Empty body. HTTP 204 indicates the session was permanently deleted.
- Defined in packages/sdk/src/v1/resources/agent_sessions.ts:95

get

get(agentSession: string): Promise<AgentSession>
Retrieve an agent session Returns the agent session identified by agent_session. Use this endpoint to poll session status or to inspect the final result after execution completes. For real-time updates without polling, subscribe to the session stream endpoint instead, which delivers server-sent events whenever the session state changes. Requires an app-scoped API key. The session must belong to an agent owned by the authenticated app.
Parameters
- agentSession: string
  Agent session ID (ase_...) of the session to retrieve.
Returns Promise<AgentSession>
The requested agent session.
- Defined in packages/sdk/src/v1/resources/agent_sessions.ts:112

list

list(
    params?: {
        agent?: string;
        excludeSystem?: boolean;
        limit?: number;
        routineRun?: string[];
        status?: string[];
    },
): Promise<AgentSessionListResponse>
List agent sessions Returns a flat list of agent sessions visible to the authenticated app, ordered by creation time descending. Use the agent, status, and routine_run filters to narrow results. All filters are optional and can be combined. The status and routine_run parameters each accept multiple values; pass the parameter more than once or as a comma-separated array to match any of the supplied values. Requires an app-scoped API key. Results are limited to sessions that belong to agents owned by the authenticated app.
Parameters
- Optionalparams: {
      agent?: string;
      excludeSystem?: boolean;
      limit?: number;
      routineRun?: string[];
      status?: string[];
  }
  Query parameters.
  - Optionalagent?: string
    Filter by agent ID (agi_...). Omit to return sessions for all agents in the app.
  - OptionalexcludeSystem?: boolean
    When true, omits sessions that were created automatically by the platform rather than by your app. Defaults to false.
  - Optionallimit?: number
    Maximum number of sessions to return. Defaults to 25; maximum is 100.
  - OptionalroutineRun?: string[]
    Filter to sessions that were created by the specified routine run IDs. Accepts up to 100 IDs. Omit to return sessions regardless of their originating routine run.
  - Optionalstatus?: string[]
    Filter by one or more session statuses. Accepted values are "pending", "running", "waiting", "completed", "failed", and "cancelled". Omit to return sessions in any status.
Returns Promise<AgentSessionListResponse>
A list of agent sessions matching the supplied filters.
- Defined in packages/sdk/src/v1/resources/agent_sessions.ts:29

message

message(
    agentSession: string,
    input: {
        content: string;
        metadata?: Record<string, unknown>;
        role?: string;
    },
): Promise<AgentSession>
Send a message to an agent session Appends a message to the inbox of the specified agent session. The agent reads inbox messages at the start of each turn; sending a message to a "waiting" session signals it to resume execution. Use role to identify the sender type. The default role is "user". Arbitrary key-value metadata may be attached to the message for tracking or display purposes. Requires an app-scoped API key. The session must belong to an agent owned by the authenticated app.
Parameters
- agentSession: string
  Agent session ID (ase_...) of the session whose inbox should receive the message.
- input: { content: string; metadata?: Record<string, unknown>; role?: string }
  Request body.
  - content: string
    Plain-text body of the message to deliver to the agent.
  - Optionalmetadata?: Record<string, unknown>
    Arbitrary key-value metadata to attach to the message. Stored and returned as-is; not interpreted by the platform.
  - Optionalrole?: string
    Role of the message sender. Typically "user" or "tool". Defaults to "user".
Returns Promise<AgentSession>
The agent session with the new message appended to its inbox.
- Defined in packages/sdk/src/v1/resources/agent_sessions.ts:168

update

update(
agentSession: string,
input: { metadata?: Record<string, unknown> },
): Promise<AgentSession>
Update an agent session Updates the mutable fields of an agent session. Currently only metadata can be changed; supply any key-value pairs you want to store alongside the session. Omitting metadata leaves it unchanged. This endpoint may be called while the session is in any status, including while it is actively running. Requires an app-scoped API key. The session must belong to an agent owned by the authenticated app.
Parameters
- agentSession: string
  Agent session ID (ase_...) of the session to update.
- input: { metadata?: Record<string, unknown> }
  Request body.
  - Optionalmetadata?: Record<string, unknown>
    Arbitrary key-value metadata to attach to the session. Replaces the existing metadata map entirely. Omit to leave the current metadata unchanged.
Returns Promise<AgentSession>
The agent session with the updated fields applied.
- Defined in packages/sdk/src/v1/resources/agent_sessions.ts:130

Class AgentSessionResource

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns AgentSessionResource

Methods

cancel

Parameters

Returns Promise<AgentSession>

create

Parameters

agent: string

instructions: string

Optionalmax_runs_per_turn?: number

Optionalmax_tokens?: number

Optionalmax_turns?: number

Optionalmetadata?: Record<string, unknown>

Optionalname?: string

Optionalstart_idle?: boolean

Optionalteam?: string

Optionalthread?: string

Optionaluser?: string

Returns Promise<AgentSession>

delete

Parameters

Returns Promise<void>

get

Parameters

Returns Promise<AgentSession>

list

Parameters

Optionalagent?: string

OptionalexcludeSystem?: boolean

Optionallimit?: number

OptionalroutineRun?: string[]

Optionalstatus?: string[]

Returns Promise<AgentSessionListResponse>

message

Parameters

content: string

Optionalmetadata?: Record<string, unknown>

Optionalrole?: string

Returns Promise<AgentSession>

update

Parameters

Optionalmetadata?: Record<string, unknown>

Returns Promise<AgentSession>

Settings

On This Page

`Optional`max_runs_per_turn?: number

`Optional`max_tokens?: number

`Optional`max_turns?: number

`Optional`metadata?: Record<string, unknown>

`Optional`name?: string

`Optional`start_idle?: boolean

`Optional`team?: string

`Optional`thread?: string

`Optional`user?: string

`Optional`agent?: string

`Optional`excludeSystem?: boolean

`Optional`limit?: number

`Optional`routineRun?: string[]

`Optional`status?: string[]

`Optional`metadata?: Record<string, unknown>

`Optional`role?: string

`Optional`metadata?: Record<string, unknown>