Rename or describe an agent, or save its card and profile
name and description change the agent itself: no version is made, and description: null clears it. Neither reaches a run. A card becomes a new version; existing versions never change, and a card equal to one the agent already has reuses it. A card, runtime_profile_id or model_source changes what the agent does: unless it equals what the agent runs (release.status: unchanged, nothing released), the save makes a release of it and activates it (applied). runtime_profile_id alone saves the card the agent runs now on that profile; without a card or profile the agent's current ones are used. model_source: profile runs the profile's default model and writes it into the card; fixed keeps the card's model; absent, the current source is kept while the card's model is the one running. A refused release (failed, with its reason) keeps the card version and leaves the request as the agent's draft; a save a newer one replaced answers superseded and changes nothing.
Auth: cookie session only; no scope. Idempotency-Key: ignored.
cookieSession__Host-werft_session<token>For the web console: the browser session cookie set by POST /v1/auth/login. It holds the scopes of the user's workspace role (owner: all; admin and member: all but sessions:recover). Requests other than GET must also send X-Requested-With: werft-web.
id*stringThe agent's id.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidX-Requested-With?"werft-web"Required with a cookie session: the literal werft-web.
"werft-web"application/json- body
name?string1 <= length <= 120description?|nullauto_model_migration?booleancard?runtime_profile_id?string1 <= length <= 128model_source?string"fixed""profile"follow_latest_profile?booleanSuccess
application/json- response
agent*versions*array<>releases*array<>active_release*|nullbehavior_revision*integer0 <= value <= 2147483647model_source*string"fixed""profile"draft*|nulleffective_behavior*profile_tracking?string"follow""pinned"profile_rollout?|nullrelease*curl -X PATCH 'https://example.com/v1/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08' \ -H 'Content-Type: application/json' \ -d '{}'{ "agent": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9", "slug": "string", "name": "string", "description": "string", "managing_team_id": "911b0313-617e-40f5-9150-864225bf0223", "managing_team_name": "string", "status": "active", "active_release_id": "string", "activation_revision": -1, "auto_model_migration": true, "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" }, "versions": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "version_no": 1, "card": { "role": "string", "instructions": "string", "language": "follow-user", "model": "string", "capabilities": { "mcp": [ { "server": "string" } ], "forbidden": [], "tool_policy": { "per_tool": { "property1": "allow", "property2": "allow" } }, "credential_refs": [ "string" ], "env": [ { "name": "string" } ] }, "rules": [] }, "content_sha256": "string", "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4", "created_at": "2019-08-24T14:15:22Z" } ], "releases": [ { "id": "string", "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c", "card_sha256": "string", "runtime_profile_id": "string", "repository_id": "string", "profile_digest": "string", "runtime_config_snapshot": { "property1": null, "property2": null }, "effective_tools": { "tools": [ "string" ], "mcp": [ "string" ] }, "policy_pins": { "tools": { "default": { "builtin": "allow", "mcp": "allow" }, "per_tool": { "property1": "allow", "property2": "allow" } }, "github": { "repositories": [ "string" ], "push_approval": true, "features": { "workflows": true, "actions": true, "checks": true, "issues": true, "review": true }, "actions_allow": [ { "workflow": "string", "ref": "string" } ] } }, "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4", "created_at": "2019-08-24T14:15:22Z", "approved_by": "02030314-b162-4b4d-8af1-88eabdcc615d", "approved_at": "2019-08-24T14:15:22Z", "note": "string", "label": "string", "activated_at": "2019-08-24T14:15:22Z", "deactivated_at": "2019-08-24T14:15:22Z" } ], "active_release": { "id": "string", "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c", "card_sha256": "string", "runtime_profile_id": "string", "repository_id": "string", "profile_digest": "string", "runtime_config_snapshot": { "property1": null, "property2": null }, "effective_tools": { "tools": [ "string" ], "mcp": [ "string" ] }, "policy_pins": { "tools": { "default": { "builtin": "allow", "mcp": "allow" }, "per_tool": { "property1": "allow", "property2": "allow" } }, "github": { "repositories": [ "string" ], "push_approval": true, "features": { "workflows": true, "actions": true, "checks": true, "issues": true, "review": true }, "actions_allow": [ { "workflow": "string", "ref": "string" } ] } }, "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4", "created_at": "2019-08-24T14:15:22Z", "approved_by": "02030314-b162-4b4d-8af1-88eabdcc615d", "approved_at": "2019-08-24T14:15:22Z", "note": "string", "label": "string", "activated_at": "2019-08-24T14:15:22Z", "deactivated_at": "2019-08-24T14:15:22Z" }, "behavior_revision": 0, "model_source": "fixed", "draft": { "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c", "runtime_profile_id": "string", "model_source": "fixed", "failure": "string" }, "effective_behavior": { "applied": { "runtime_profile_id": "string", "model": "string", "model_source": "fixed", "title_model": "string" }, "draft": { "runtime_profile_id": "string", "model": "string", "model_source": "fixed", "title_model": "string" } }, "profile_tracking": "follow", "profile_rollout": { "status": "pending", "reason": "string", "target_profile_id": "string" }, "release": { "status": "applied", "reason": "string", "release_id": "string", "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c" }}