On this page
Decide approval on an agent session
Answers a tool call waiting for approval; the turn continues.
Answers a tool call waiting for approval; the turn continues.
- Path
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session:decideApproval - 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. |
call_id | string | The waiting ToolCall's id. Required. |
decision | ApprovalDecision | The answer. Required. One of approve, reject. |
remember | bool | Also allow later calls of the same tool in this session without asking ("always allow"); only with APPROVE. |
reason | string | Why, at most 500 characters; the agent reads it with a rejection. |
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, usage, sandbox, wait_changed, wait_continuation. |
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. |
usage | StepUsage | Observed accounting for this step; absent values are unknown, never zero. Output only. |
step_key | string | Stable runtime-assigned effect key, independent of invocation attempts. 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. |
sandbox | SandboxActivity | For SANDBOX: authoritative allocation/release history, including replacements. One of the payload group. |
wait | AgentSessionWait | For WAIT_CHANGED: a durable wait fact, without execution authority. One of the payload group. |
wait_continuation | SessionWaitContinuation | For WAIT_CONTINUATION: ready owners consumed by exact turn admission. 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. |
StepUsage
| Field | Type | What it is |
|---|---|---|
input_tokens | uint64 | Uncached input tokens the step was charged for; absent when unknown. Output only. |
cached_tokens | uint64 | Input tokens served from the provider cache; absent when unknown. Output only. |
output_tokens | uint64 | Output tokens; absent when unknown. Output only. |
cost_usd | string | The exact decimal USD charge the gateway reported; absent when unknown. Output only. |
model | string | The catalog id the step ran on; empty for a step with no inference. Output only. |
kind | string | model, tool, compaction or subcall. Output only. |
first_delta_time | timestamp | For a model step: when the runtime received the stream's first non-empty assistant text or tool-call delta (not a role-only or empty chunk), on the runtime's clock, from the attempt that produced the recorded step. 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 must execute this pending call. Calls rejected before dispatch remain in history with this false and a corresponding ToolResult. Output only. |
deadline | timestamp | The client call's fixed deadline. A reconnecting client never starts a call after this time; retries retain the original deadline and call id. 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, archived. |
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. |
first_delta_time | timestamp | The first non-empty assistant text or tool-call delta of the turn: the earliest first_delta_time of its recorded model steps. 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. |
SandboxActivity
| Field | Type | What it is |
|---|---|---|
lease | string | The lease's resource name. Output only. |
state | string | allocated or released (the release was read back as ENDED). Output only. |
sandbox_seconds | string | On released: exact decimal seconds from allocation to release. Output only. |
AgentSessionWait
| Field | Type | What it is |
|---|---|---|
name | string | Exact name; the final segment is the conserved wait UUID. |
uid | string | Immutable platform Resource UID. Output only. |
meta | ResourceMeta | Standard metadata. Output only. |
goal | string | Optional exact Goal in this Session, never a current-Goal selector. |
type | string | time or signal. Other producer types require their own admitted adapter. Required. |
reference | string | Exact source reference for a signal; empty for a timer. |
deadline | timestamp | Actual future due time; required only for a timer. |
resume_prompt | string | What to do after observing this wait's evidence, at most 16 KiB. Required. |
state | string | active, ready, resolved or cancelled. Ready still requires turn admission. Output only. |
evidence | struct | Original bounded observed evidence, retained through delivery and restart. Output only. |
resumed_turn | int64 | The only turn that consumed this wait; unset until resolved. Output only. |
create_time | timestamp | Creation time. Output only. |
update_time | timestamp | Last state change time. Output only. |
SessionWaitContinuation
| Field | Type | What it is |
|---|---|---|
waits | AgentSessionWait[] | Conserved wait snapshots and observed evidence for this exact turn. 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:decideApproval" \
-H "Authorization: Bearer $SYLPHX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"call_id":"…","decision":"approve"}'