Ensure agent (config-as-code converge)
Idempotently converge a repo-defined agent definition onto the platform. Identity is name + account scope. Hash-only probes skip the payload in the steady state (a miss is a normal 200 definitionRequired response, not an error); full requests create the agent or append a new version when the canonical content hash differs. Non-executing: never touches the execution pipeline. The response always carries the server-computed canonical hash. Set dryRun to plan without writing (CI drift gate), onConflict: “overwrite” to converge over dashboard/API edits, and deploy: { alias } to atomically save and activate the definition at a release alias (release: “publish” / “none” remain compatibility spellings of deploy live / save-only, and mixing the two is a 400). A non-live deploy is alias-scoped: it appends a candidate version and moves that one pointer, and never writes the agent row, its config hash, its capabilities, its draft pointer or its live pointer, so “unchanged” is decided against the hash stored on the alias rather than against the live row. onConflict, expectedRemoteHash and managed-by-code provenance describe live-row writes and therefore do not apply to a non-live deploy; remoteHash in the response is the hash the alias carried before. The one exception is an agent name that does not exist yet: the create is the live row (there is nothing to preview against), and live is still not aimed. Optional version.label / version.notes stamp provenance (a git SHA, a release tag) on the appended version row.
Authentication
Request
The complete set of capabilities (flow, sub-agent and saved-tool attachments) on this agent, in display order. Each entry names its source by name, so the declaration is portable across accounts. Capabilities on the agent but absent here are removed; omit the field to leave them untouched. When present, the capabilities are part of the content hash and of the version this converge snapshots. They are written to the agent itself, so they cannot accompany a non-live deploy.
Atomically save this definition and activate it at a release alias. Use { alias: “live” } to deploy to production, or any name matching ^[a-z0-9][a-z0-9-]{0,62}$ for a preview pointer. A non-live alias appends a candidate version and moves that one pointer: it never writes the agent row, its config hash, its capabilities, its draft pointer or its live pointer, so onConflict and expectedRemoteHash describe writes it never performs and are rejected with a 400 alongside it. A release alias is organization-owned, so a non-live deploy on a personal-scope agent is a 400 with code alias_requires_organization. Mutually exclusive with release.
Compatibility input, translated to a deploy: “publish” activates live, “none” saves without activating. Prefer deploy.
The complete set of skills bound to this agent, in load order. Each entry names a skill by slug; version pins that skill versionNumber, and omitting it follows the skill’s published version. Skills bound to the agent but absent here are unbound; omit the field to leave bindings untouched. Bindings are agent state, not alias state, so they take effect immediately and cannot accompany a non-live deploy.
Provenance recorded on the version row this converge appends. Omit to keep the default “sdk-ensure” label and the server-generated notes.
Response
Converge result: unchanged | created | updated | definitionRequired (hash miss — retry with the full definition) | plan (dryRun)