update-process-flow

• UpstreamError (502): a title in agent.context_target_agent_ids matches no agent; the error lists the names.

A real response, captured from a live call to update-process-flow:

flow came back populated and is shown as … here, because the real value runs to thousands of characters. Read it from your own call rather than from this page.

{
  "lifecycle_id": "qlc_000183",
  "result": {
    "agent_id": "6ab1968189fbbb1251ca6754",
    "flow": "\u2026",
    "process_flow_id": "6ab1945e7566f41b5c28e308"
  }
}

// the object you get back IS the result — there is no `.result` to read
{
  agent_id: '6ab1968189fbbb1251ca6754',
  flow: '…',
  process_flow_id: '6ab1945e7566f41b5c28e308'
}

// The TS SDK names these camelCase — lifecycleId, traceId — where Python uses
// lifecycle_id and trace_id. Both are non-enumerable: readable, but omitted by
// Object.keys() and JSON.stringify(). `result.lifecycleId` here is undefined.
result.lifecycleId // 'qlc_000183'

# a dict subclass; `result` is already unwrapped
{
 "agent_id": "6ab1968189fbbb1251ca6754",
 "flow": "\u2026",
 "process_flow_id": "6ab1945e7566f41b5c28e308"
}

out.lifecycle_id  # 'qlc_000183' — an attribute, not a key

Refusals. Before it runs, this tool refuses: neither process_flow_id nor flow_name; agent.skills ids that do not exist in the project; in add mode a missing agent.title, an unknown type, invalid agent settings, a skilled agent that is not runnable (no skills and not conversational) and a decider agent with fewer than 2 conditions; in edit mode an empty agent, and any non-editable field. A context_target_agent_ids title that matches no agent is raised only when the call runs, as an upstream error naming the unmatched titles.

agent in full. In add mode (no agent_id) it has the same shape as one manifest.agents[] entry, minus ref (there is only one agent): title is required, and skills, next_agents and next must be real existing ids, not manifest refs. In edit mode (agent_id set) title is not required: include only the fields you are changing, and every omitted field is left untouched. Editable in edit mode: title, role, role_description, prompt, llm, skills, context, has_knowledge_base, is_preview_mode_enabled, triggers, context_required, context_target_agent_ids, conditions (decider agent only), context_access, agent_base_prompt, is_terminal_agent (skilled agent only), is_user_specific_task (skilled agent only) and registration_id (interop agent only: repoints an external agent node at a different peer agent connection). Not editable in edit mode: type (a node type cannot change after creation), next, next_agents and ref (manifest-only). Passing one is refused before the call runs, and the error lists the editable fields.

This is the tool equivalent of the UI's + button. In add mode (no agent_id) the agent may be a skilled_agent, decider_agent or interop_agent (the external agent node), defaulting to skilled_agent. Positioning is add mode only: after_agent_id is the existing agent to insert after (omit it for a skilled agent to prepend it as the new initial agent; omit it for a decider agent only on an empty process flow), and add_on_side_if_decider is required when after_agent_id points at an existing decider agent.

Unlike create-process-flow's manifest mode, which resolves next_agents against refs in the same call, this tool's agent.next_agents and agent.next values must be real existing ids already in the project and flow: fetch them with get-process-flow first if needed. agent.skills is always real existing skill ids, since there is no ref resolution and no Wexa tool creates a skill: call list-skills to find them. The one exception is agent.context_target_agent_ids, which takes agent titles as they appear in the process flow, not ids: the tool resolves them for you and returns a clear error listing which names did not match.

In edit mode (agent_id set) agent is a partial update: only the fields you include change. Rewiring (next, next_agents) is not supported in place, because the backend has no such field on an in-place update. To rewire, remove the agent in the console and add it back: open the agent in the process flow editor and choose Delete, then Remove from process flow. No tool removes a single agent from a process flow.

The result carries agent_id and the updated flow, which the full response shows as … because the real value runs to thousands of characters. An agent this tool adds is not recorded as a version until you promote-flow.

In add mode, add_on_side_if_decider must be one of the existing decider's own condition names and that decision slot must not already be wired; the platform passes both positioning arguments on and the data service enforces them.

Marked consequential: it is audited in full, and a policy rule may hold it for a person to approve. See Policy and approvals.