Agent Sessions
Manage agent sessions and interact with agents through conversational events.
Create agent session
Create a new session for interacting with an agent. A session maintains state across all events, tool use, and agent responses produced during the interaction.
List agent sessions
List all agent sessions for the specified agent. This endpoint returns high-level information about each session, with optional filtering and pagination. Use this operation to browse existing sessions or to locate a specific session key for further inspection or updates.
Get agent session
Retrieve the full details of a specific agent session using its unique session key. The response includes the session's configuration, metadata, timestamps, and other stored properties. Use this endpoint to inspect the current state of a session or verify its configuration.
Update agent session
Update the configuration of an existing agent session. This endpoint enables you to modify fields such as the name, description, or metadata.
Delete agent session
Permanently delete an agent session. This action cannot be undone.
Interact with an agent
Create a new input to an agent to interact with it.
List events in agent session
List all events in a specific agent session, with optional pagination.
List outstanding client tool calls for an agent session
List the client tool calls the session is currently waiting on the caller to fulfill. Each entry carries the originating `tool_input` event ID, the tool name, and the fully materialized arguments to invoke the tool with. Secret-derived values are returned unmasked because the caller needs them to execute the tool, so this endpoint is restricted to the same roles permitted to submit input to the session.
Get event in agent session
Retrieve the details of a specific event within an agent session.
Delete event
Permanently delete an event from a session. Removes the event from both the metadata database and the encrypted event store.
Hide event
Manually hide an event in a session. Sets hide_reason to 'manual'.
Unhide event
Unhide a hidden event in a session. Clears the hide_reason.
List session artifacts
List all artifacts stored in a specific agent session, with cursor-based pagination. Artifacts are files either uploaded by the user, or generated within a session. This endpoint shows you what files exist in a session, but does not include the file content.
Get session artifact
Retrieve a specific artifact by its unique `artifact_id`, including metadata and base64-encoded file content.