Menu
Platform
AI
App store purchases
Credits
Database
Flags
Generated Assets
Monitoring
Notifications
Organizations
Payments
- Payments
- Payments quickstart
- Checkout policies
- Checkout sessions
- Customer subscriptions
- Entitlement grants
- Exchange rates
- Licence keys
- Licence tokens
- Merchant accounts
- Portal sessions
- Price catalogs
- Revenue
- Revenue facts
- Revenue sources
- Tax threshold statuses
- Usage events
- Usage invoices
- Usage meter prices
- Usage meters
- Usage reservations
- Usage settings
- Usage tiers
Sandboxes
Webhooks
Getting Started
Authentication
KV Store
Deploy & Infrastructure
Reference
Steer an agent session
Sends a message into the running turn; the agent reads it at its next step.
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.
Not available yet. Sylphx Agents is declared in the registry but no backend serves it: every call answers 501 with the problem code UNIMPLEMENTED.
- Path
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session:steer - Scope
agents:sessions - Effect
write— a successful call changes state. - Collection agent_sessions
#Request
| Field | Type | What it is |
|---|---|---|
name | string | The name of the session. Required. |
message | Message | The message, 1 to 64 parts. Required. |
#Message
| Field | Type | What it is |
|---|---|---|
parts | ContentPart[] | The content, in order; 1 to 64 parts. Required. |
#ContentPart
| Field | Type | What it is |
|---|---|---|
text | string | Text. One of the part group. |
file | FileRef | A file, by Sylphx Data object URL or an https URL. One of the part group. |
#FileRef
| Field | Type | What it is |
|---|---|---|
uri | string | Where the file is. Required. |
media_type | string | Its media type, for example image/png. |
filename | string | Its display name. |
#Response
| Field | Type | What it is |
|---|---|---|
name | string | orgs/{org}/projects/{project}/envs/{env}/agent_sessions/{agent_session}/session_events/{session_event}. |
uid | string | sevt_<cell><ulid>; never reused. Output only. |
meta | ResourceMeta | Resource metadata. |
sequence | int64 | The position in the session's log, from 1, with no gaps. Output only. |
type | SessionEventType | What the event is. Output only. One of user_message, steer, agent_message, tool_call, tool_result, approval_requested, approval_decided, status, compaction, thought, file_change, response, error. |
turn | int64 | The turn it belongs to, from 1; 0 for an event outside a turn. Output only. |
step | int64 | The step within the turn, from 1, assigned by the runtime; 0 for an event that is not a step. Output only. |
create_time | timestamp | When it was appended. Output only. |
message | Message | For USER_MESSAGE, STEER and AGENT_MESSAGE. One of the payload group. |
tool_call | ToolCall | For TOOL_CALL. One of the payload group. |
tool_result | ToolResult | For TOOL_RESULT. One of the payload group. |
approval | Approval | For APPROVAL_REQUESTED and APPROVAL_DECIDED. One of the payload group. |
status_change | StatusChange | For STATUS. One of the payload group. |
thought | Message | For THOUGHT: a reasoning summary, never private model reasoning. One of the payload group. |
file_change | FileChange | For FILE_CHANGE. One of the payload group. |
response | TurnResult | For RESPONSE: the completed turn's answer and usage. One of the payload group. |
error | ErrorEvent | For ERROR. One of the payload group. |
#ResourceMeta
| Field | Type | What it is |
|---|---|---|
generation | int64 | Increases by one on every change to spec. Output only. |
etag | string | Strong ETag (AIP-154): changes on any change to spec, status, or metadata. Send it back as If-Match or etag to make Update and Delete conditional; a mismatch fails with ABORTED / 409 ETAG_MISMATCH. Output only. |
create_time | timestamp | When the Resource was created. Output only. |
update_time | timestamp | When the Resource last changed. Output only. |
delete_time | timestamp | Set while the Resource is being deleted. Output only. |
labels | map<string, string> | Caller-writable, indexed labels (AIP-122 label rules). |
annotations | map<string, string> | Caller-writable, unindexed annotations. |
display_name | string | Caller-writable human-readable name. |
creator | string | The principal that created the Resource. Output only. |
#Message
| Field | Type | What it is |
|---|---|---|
parts | ContentPart[] | The content, in order; 1 to 64 parts. Required. |
#ToolCall
| Field | Type | What it is |
|---|---|---|
id | string | The call's id within the session, (turn, step) based. Output only. |
tool | string | The tool name. Output only. |
input | struct | The input, as the model sent it. Output only. |
model_call_id | string | The model's own id for the call, as sent; never used as a key. Output only. |
client | bool | Whether the client runs it (a ClientTool). Output only. |
#ToolResult
| Field | Type | What it is |
|---|---|---|
call_id | string | The ToolCall's id. Output only. |
output | value | The output. Output only. |
error | bool | Whether the call failed; output then holds the error. Output only. |
duration | duration | How long the call took. Output only. |
#Approval
| Field | Type | What it is |
|---|---|---|
call_id | string | The ToolCall's id. Output only. |
decision | ApprovalDecision | The answer, once given; unset while it waits. Output only. One of approve, reject. |
remember | bool | Whether the answer covers later calls of the same tool in this session ("always allow"). Output only. |
principal | string | Who answered. Output only. |
reason | string | The reason given, if any. Output only. |
#StatusChange
| Field | Type | What it is |
|---|---|---|
state | SessionState | The state after the change. Output only. One of idle, running, awaiting_approval, awaiting_client, failed. |
reason | string | Why, for FAILED and INTERRUPTED: a registry error code and message. Output only. |
#FileChange
| Field | Type | What it is |
|---|---|---|
path | string | The path relative to the session's repository root. Output only. |
change | string | added, modified, deleted, renamed or copied. Output only. |
added | int64 | Lines added, when reported by the harness. Output only. |
removed | int64 | Lines removed, when reported by the harness. Output only. |
old_path | string | The previous path, for a rename or copy. Output only. |
source | string | edit for an incremental edit or final for the turn's final diff. Output only. |
#TurnResult
| Field | Type | What it is |
|---|---|---|
text | string | The final response's text. Output only. |
is_error | bool | Whether the turn ended with an error. Output only. |
usage | TurnTokenUsage | Model token usage reported by the harness. Output only. |
cost_micros | int64 | The reported cost, in micro-USD. Output only. |
duration | duration | How long the turn ran. Output only. |
#ErrorEvent
| Field | Type | What it is |
|---|---|---|
kind | string | The registry error code or harness error kind. Output only. |
message | string | A safe error description. Output only. |
#ContentPart
| Field | Type | What it is |
|---|---|---|
text | string | Text. One of the part group. |
file | FileRef | A file, by Sylphx Data object URL or an https URL. One of the part group. |
#TurnTokenUsage
| Field | Type | What it is |
|---|---|---|
input_tokens | int64 | Input tokens. Output only. |
output_tokens | int64 | Output tokens. Output only. |
cache_read_tokens | int64 | Input tokens read from the model's cache. Output only. |
cache_write_tokens | int64 | Input tokens written to the model's cache. Output only. |
#FileRef
| Field | Type | What it is |
|---|---|---|
uri | string | Where the file is. Required. |
media_type | string | Its media type, for example image/png. |
filename | string | Its display name. |
#Errors
UNAUTHENTICATED— No valid key or token was presented.PERMISSION_DENIED— The key lacks the method's permission.RESOURCE_NOT_FOUND— The named Resource does not exist or is not visible.INVALID_FIELD— A field failed validation.INVALID_STATE— The Resource is in a state that forbids the call.IDEMPOTENCY_KEY_REUSED— An Idempotency-Key was reused with another body.IDEMPOTENCY_IN_PROGRESS— The first call with this Idempotency-Key is still running.
Every error arrives in the body Errors describes.
#Examples
curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session:steer" \
-H "Authorization: Bearer $SYLPHX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message":{"parts":[{}]}}'