agents.agent-config.update

Update fields on an existing agent configuration

Update an existing AgentConfig row.

Overview

Property	Value
Workflow type	Linear
Library	App-agents
Version	1.0

Triggers

Source	Endpoint / Event	Description
API	PATCH /api/agents/configs/{config_uuid}	Update an existing agent configuration

Input Schema

Field	Type	Required	Default	Description
agent_config_uuid	string	Yes	—	Agent configuration UUID to update.
organization_uuid	string	Yes	—	Organization context UUID supplied by the workflow runtime.
name	string	No	—	Human-readable agent configuration name.
description	string	No	—	Short human-readable summary of the agent's job.
system_prompt	string	No	—	Instruction prompt supplied to the agent at session launch.
ai_provider_config_uuid	string	No	—	Optional enabled AI provider profile UUID. Discover valid profile/model pairs with data.ai-provider.list(enabled_only=true); each row's default_model is the model_name accepted for that profile. Omit to use the organization's default enabled profile.
model_profile	string	No	—	Name of an enabled AI provider profile to rebind this config to (the stable handle; equivalent to passing that row's ai_provider_config_uuid).
model_connection_uuid	string	No	—	Optional AI-provider connection UUID to switch this config to. Descriptive, budget, memory, runner, and tag updates reuse the stored connection when omitted.
model_name	string	No	—	Optional model name override. Must match the default_model shown for the selected enabled AI provider profile in data.ai-provider.list.
max_steps	integer	No	—	Maximum number of reasoning/tool-use steps allowed per session.
max_tokens_per_step	integer	No	—	Maximum model output token budget allowed for each step.
budget_usd	float	No	—	Optional per-session cost ceiling in USD for this agent configuration.
memory_enabled	boolean	No	—	Whether sessions launched from this config may retrieve agent memory.
memory_write_enabled	boolean	No	—	Whether finished sessions from this config are distilled into memory. Separate from memory_enabled, which governs reading: a bad recall wastes prompt tokens, a bad writer permanently pollutes the pool every later recall draws from. Defaults off.
memory_strategy	string	No	—	Memory retrieval strategy when memory_enabled is true. Allowed values: last_k (most recent), importance (highest-scored), pack (ranked against the session's task and fitted to a token budget).
memory_top_k	integer	No	—	Maximum number of memory records to retrieve when memory is enabled; normally 5-30.
runner_group_uuid	string	No	—	Optional agent-eligible runner group UUID. Omit to leave runner selection to session launch defaults.
runner_image	string	No	—	Optional runner container image override for sessions launched from this config.
runtime_profile	string	No	—	Reviewed runtime behavior. workspace-probe-v1 is the safe default; software-development-v1 is accepted only by a cloudless DevKit group when organization code execution policy permits it.
tags	dict	No	—	Optional JSON object of caller-defined tags stored with the agent configuration.

Output Schema

Field	Type	Required	Default	Description
agent_config_uuid	json	No	—	—
error	string	No	—	—
error_type	string	No	—	—
failed_at	string	No	—	—
failed_at_state	string	No	—	—
failed_layer	json	No	—	—
failed_step	string	No	—	—
failure_reason	string	No	—	—
updated	json	No	—	—
organization_uuid	json	No	—	—
name	json	No	—	—
description	json	No	—	—
system_prompt	json	No	—	—
ai_provider_config_uuid	json	No	—	—
model_profile	json	No	—	—
model_override	json	No	—	—
model_connection_uuid	json	No	—	—
model_name	json	No	—	—
max_steps	json	No	—	—
max_tokens_per_step	json	No	—	—
budget_usd	json	No	—	—
memory_enabled	json	No	—	—
memory_write_enabled	json	No	—	—
memory_strategy	json	No	—	—
memory_top_k	json	No	—	—
runner_group_uuid	json	No	—	—
runner_image	json	No	—	—
runtime_profile	json	No	—	—
tags	json	No	—	—

States

State	Initial	Terminal	Success	Auto-advance	Description
initiated	Yes	No	—	run	—
run	No	No	—	complete	—
completed	No	Yes	Yes	—	—
failed	No	Yes	No	—	—

State Diagram

Transitions

From	Action	To	Description
initiated	run	run	—
run	complete	completed	—
* (any state)	fail	failed	—

Outcomes

Outcome	Type	Description	State Data Keys
updated	SUCCESS	Agent configuration updated	agent_config_uuid, updated, organization_uuid
failed	FAILURE	Agent configuration updated failed	failure_reason, error, error_type, failed_at_state, failed_step, failed_layer

Business Errors

Code	Message Template
AGENTS_ORGANIZATION_CONTEXT_INVALID	Authenticated organization context is missing or does not match the workflow input
AGENTS_CONFIG_NOT_FOUND	Agent configuration {agent_config_uuid} was not found in the organization
AGENTS_SKILL_NOT_FOUND	Agent skill {skill_uuid} was not found in the organization
AGENTS_MCP_SERVER_NOT_FOUND	MCP server {mcp_server_uuid} was not found in the organization
AGENTS_RUNNER_GROUP_NOT_FOUND	Runner group {runner_group_uuid} was not found in the organization
AGENTS_VALIDATION_FAILED	Workflow input or domain state failed validation:
AGENTS_CONFLICT	Conflicting agent domain state:

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "agents.agent-config.update",
  "initial_data": {
    "agent_config_uuid": "value",
    "organization_uuid": "value"
  }
}