---
# @generated by sylphx-gen 0.1.0 from contracts@3118f36f16f799965338811e17ed3a9f565a9f136b14c95e9c94a1e21d42ea3e. Do not edit.
title: "Agent sessions"
description: "The `agent_sessions` collection of Sylphx Agents: An AgentSession is a durable conversation with one pinned AgentVersion."
type: reference
product: agents
summary: "An AgentSession is a durable conversation with one pinned AgentVersion."
updated: 2026-09-28
order: 900
---

An AgentSession is a durable conversation with one pinned AgentVersion. Its conversation is its SessionEvent log. Each turn runs as one Sylphx Workflows Run, and each model call and tool call is a step keyed by `(session, turn, step)`, assigned by the runtime and never taken from the model's tool-call id. An idle session holds no Run and no compute.

**Service** Sylphx Agents · **Resource type** `agents.sylphx.com/AgentSession` · **Name pattern** `orgs/{org}/projects/{project}/envs/{env}/agent_sessions/{agent_session}` · **Shape** `record`

**Not available yet.** Sylphx Agents is declared in the registry but no backend serves it: every call answers `501` with the problem code `UNIMPLEMENTED`.

## Fields

| Field | Type | What it is |
| --- | --- | --- |
| `name` | `string` | `orgs/{org}/projects/{project}/envs/{env}/agent_sessions/{agent_session}`. |
| `uid` | `string` | `ases_<cell><ulid>`; never reused. Output only. |
| `meta` | `ResourceMeta` | Resource metadata. |
| `agent` | `string` | The Agent the session talks to. Required. |
| `agent_version` | `string` | The AgentVersion the session pinned; the Agent's current version when unset at create. |
| `end_user` | `string` | The Sylphx Auth end user the session belongs to, set from the caller's end-user session; empty for a session a secret key started. An end user reads and changes only their own sessions. Output only. |
| `title` | `string` | A short title; set by the caller or summarised by the runtime. |
| `state` | `SessionState` | The session's state. Output only. One of `idle`, `running`, `awaiting_approval`, `awaiting_client`, `failed`. |
| `turn_count` | `int64` | The number of turns started, from 0. Output only. |
| `last_event_sequence` | `int64` | The sequence of the newest event, from 0. Output only. |
| `create_time` | `timestamp` | When the session was created. Output only. |
| `update_time` | `timestamp` | When the last event was appended. Output only. |
| `usage` | `SessionUsage` | What the session has used so far. Output only. |
| `environment_lease` | `string` | The Sylphx Sandboxes lease attached to the session, while it has one. Output only. |
| `environment` | `EnvironmentSpec` | The environment for this session; when omitted, use the pinned Agent version's default. An explicit value replaces that default. |
| `credentials` | `map<string, CredentialBinding>` | Session-scoped credential bindings, keyed by the tool or MCP credential name. Values are references or opaque handles, never secret values. |
| `profiles` | `ProfileMount[]` | Granted platform Profiles to mount when the session starts, each by resource name and mode. The runtime never puts profile values in events. |

## Methods

Every method of the collection, in the registry's order, with the scope it
needs. The full request, response and examples are one link away.

| Method | Call | What it does |
| --- | --- | --- |
| `POST` | [`create`](/docs/api/agent_sessions#create) | Starts a session of an agent, pinned to its current version unless `agent_version` names another. Requires a secret key until end-user ownership is implemented. The session starts idle; `:send` starts its first turn. |
| `GET` | [`get`](/docs/api/agent_sessions#get) | Gets a session. |
| `GET` | [`list`](/docs/api/agent_sessions#list) | Lists sessions, newest first. With a publishable key, only the caller's end user's sessions. |
| `DELETE` | [`delete`](/docs/api/agent_sessions#delete) | Deletes a session and its events. A session whose turn is running is refused with `INVALID_STATE` unless `force` is set, which interrupts it first. |
| `POST` | [`send`](/docs/api/agent_sessions#send) | Sends a user message. On an idle or failed session it starts a new turn; while a turn runs it is refused with `INVALID_STATE` (use `:steer`). The same `Idempotency-Key` returns the same event. |
| `POST` | [`steer`](/docs/api/agent_sessions#steer) | Sends a message into the running turn; the agent reads it at its next step. On an idle session it is the same as `:send`. |
| `POST` | [`interrupt`](/docs/api/agent_sessions#interrupt) | Stops the running turn at its current step. Calls already made keep their results; the session becomes idle. A no-op on an idle session. |
| `POST` | [`decide_approval`](/docs/api/agent_sessions#decide-approval) | Answers a tool call waiting for approval; the turn continues. |
| `POST` | [`submit_tool_result`](/docs/api/agent_sessions#submit-tool-result) | Returns the result of a client tool call; the turn continues. |

## create

Starts a session of an agent, pinned to its current version unless `agent_version` names another. Requires a secret key until end-user ownership is implemented. The session starts idle; `:send` starts its first turn.

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions` · scope `agents:sessions` · effect `write` · not available yet · [Request, response and examples](/docs/api/agent_sessions/create)

## get

Gets a session.

`GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session` · scope `agents:sessions` · effect `read` · not available yet · [Request, response and examples](/docs/api/agent_sessions/get)

## list

Lists sessions, newest first. With a publishable key, only the caller's end user's sessions.

`GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions` · scope `agents:sessions` · effect `read` · not available yet · paginated · [Request, response and examples](/docs/api/agent_sessions/list)

## delete

Deletes a session and its events. A session whose turn is running is refused with `INVALID_STATE` unless `force` is set, which interrupts it first.

`DELETE https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session` · scope `agents:sessions` · effect `destructive` · not available yet · [Request, response and examples](/docs/api/agent_sessions/delete)

## send

Sends a user message. On an idle or failed session it starts a new turn; while a turn runs it is refused with `INVALID_STATE` (use `:steer`). The same `Idempotency-Key` returns the same event.

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session:send` · scope `agents:sessions` · effect `write` · not available yet · [Request, response and examples](/docs/api/agent_sessions/send)

## steer

Sends a message into the running turn; the agent reads it at its next step. On an idle session it is the same as `:send`.

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session:steer` · scope `agents:sessions` · effect `write` · not available yet · [Request, response and examples](/docs/api/agent_sessions/steer)

## interrupt

Stops the running turn at its current step. Calls already made keep their results; the session becomes idle. A no-op on an idle session.

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session:interrupt` · scope `agents:sessions` · effect `write` · not available yet · [Request, response and examples](/docs/api/agent_sessions/interrupt)

## decide_approval

Answers a tool call waiting for approval; the turn continues.

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session:decideApproval` · scope `agents:sessions` · effect `write` · not available yet · [Request, response and examples](/docs/api/agent_sessions/decide_approval)

## submit_tool_result

Returns the result of a client tool call; the turn continues.

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session:submitToolResult` · scope `agents:sessions` · effect `write` · not available yet · [Request, response and examples](/docs/api/agent_sessions/submit_tool_result)