---
# @generated by sylphx-gen. Do not edit.
title: "Goals"
description: "The `goals` collection of Sylphx Agents: An optional durable objective of one Session."
type: reference
product: agents
summary: "An optional durable objective of one Session."
updated: 2026-09-28
order: 900
---

An optional durable objective of one Session. Model answers, waits and external Task completion never settle it implicitly.

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

## Fields

| Field | Type | What it is |
| --- | --- | --- |
| `name` | `string` | The exact Session-owned Goal name. |
| `uid` | `string` | The platform Resource UID; the conserved Goal UUID is its name's final id. Output only. |
| `meta` | `ResourceMeta` | Standard resource metadata. Output only. |
| `objective` | `string` | The objective, nonempty and at most 4,000 characters. Required. |
| `token_budget` | `int64` | Omit unless the caller explicitly requests a positive token budget. |
| `state` | `GoalState` | Lifecycle; an execution hold is represented separately. Output only. One of `working`, `waiting`, `completed`, `failed`. |
| `version` | `int32` | Optimistic acceptance-contract version, starting at one. Output only. |
| `tokens_used` | `int64` | Observed tokens charged exactly once per runtime step. Output only. |
| `usage_unavailable` | `bool` | Unknown usage holds execution when a token budget is enforced. Output only. |
| `owner_paused` | `bool` | Explicit owner pause; an unfinished Goal stays unfinished. Output only. |
| `impasse` | `bool` | Execution held after the required repeated observation of an impasse. Output only. |
| `receipt` | `SessionGoalReceipt` | The terminal observation, retained after another Goal becomes active. Output only. |
| `create_time` | `timestamp` | When this Goal was created. Output only. |
| `update_time` | `timestamp` | When this Goal last changed. Output only. |

## 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/goals#create) | Creates an optional objective owned by this Session, without an external Task. The operation_id keeps the original receipt beyond request replay expiry. |
| `GET` | [`get`](/docs/api/goals#get) | Reads the exact Goal, including its terminal receipt after a successor starts. |
| `POST` | [`settle`](/docs/api/goals#settle) | Settles only the named Goal/version with an observed environment receipt. Replaying operation_id returns its original receipt, never its successor. |
| `POST` | [`control`](/docs/api/goals#control) | Applies an explicit owner control to this exact Goal/version. Pause interrupts only its current execution; resume does not resolve a wait or clear observed usage. Amend changes only supplied objective/budget fields. |

## create

Creates an optional objective owned by this Session, without an external Task. The operation_id keeps the original receipt beyond request replay expiry.

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

## get

Reads the exact Goal, including its terminal receipt after a successor starts.

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

## settle

Settles only the named Goal/version with an observed environment receipt. Replaying operation_id returns its original receipt, never its successor.

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

## control

Applies an explicit owner control to this exact Goal/version. Pause interrupts only its current execution; resume does not resolve a wait or clear observed usage. Amend changes only supplied objective/budget fields.

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