Agent Sessions
Manage agent sessions and interact with agents through conversational events.
Create agent session
Creates 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
Lists all sessions for the specified agent. 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
Returns the full details of a specific agent session, identified by 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 to verify its configuration.
Update agent session
Updates the configuration of an existing agent session. You can modify fields such as the name, description, or metadata.
Delete agent session
Permanently deletes an agent session. This action cannot be undone.
Interact with an agent
Creates a new input event in the session to interact with the agent.
List events in agent session
Lists all events in a specific agent session, with optional pagination.
List outstanding client tool calls for an agent session
Lists the client tool calls the session is waiting for 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. The response returns secret-derived values unmasked because the caller needs them to execute the tool. For this reason, this endpoint is restricted to the same roles permitted to submit input to the session.
Get event in agent session
Returns the details of a specific event in an agent session.
Delete event
Permanently deletes an event from a session. The event is erased and cannot be recovered. Unlike a hidden event, a deleted event cannot be restored.
Hide event
Hides an event in a session. Sets hide_reason to 'manual'.
Unhide event
Unhides a hidden event in a session. Clears the hide_reason.
List session artifacts
Lists all artifacts stored in a specific agent session, with cursor-based pagination. Artifacts are files that the user uploads or that the agent generates within a session. The response lists the files in a session but does not include the file content.
Get session artifact
Returns a specific artifact by its unique `artifact_id`, including metadata and base64-encoded file content.
Get session artifact raw bytes
Returns the raw bytes of an artifact. Unlike `getSessionArtifact`, which returns a JSON wrapper with base64-encoded data, this endpoint returns the file content as the response body. The response uses the artifact's own `Content-Type`. Use this endpoint to dereference an artifact URL as a binary download, for example with A2A `FilePart.fileWithUri`.