Reference

Goals

An optional durable objective of one Session.

Checked 2026-09-28

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	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	Reads the exact Goal, including its terminal receipt after a successor starts.
POST	settle	Settles only the named Goal/version with an observed environment receipt. Replaying operation_id returns its original receipt, never its successor.
POST	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

#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

#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

#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