Skip to main content

Workflows

  • optional

A Template Package can include workflow definitions to be created in the Workflow service for the selected project during deployment. Each workflow is listed in the manifest.workflows array. The manifest entry names the JSON definition file under workflows/; the file holds the workflow configuration (task definitions and related fields).

Workflow definition files must be placed inside the workflows folder in the ZIP archive. The file value should match the file path relative to workflows/ in the ZIP.

Unlike agents and teams, workflow deploy uses the file content as the create payload and sets _name from the manifest entry. Manifest fields other than name, file, and ifExists are not merged into the workflow body.

Each manifest row must include:

  • name — workflow definition name (maps to _name); used to detect an existing workflow in the project
  • file — JSON filename (or path) under workflows/

Each definition file must contain a single JSON object (not an array). Typical fields include _description, _userType, _taskDefs, _timeoutSeconds, and _timeoutPolicy (see the Workflow Service documentation for the full definition shape).

AI_CONVERSE tasks and teams#

If a workflow includes tasks with _type: "AI_CONVERSE", each such task must set _inputParams.teamName to the team display name (the same value as manifest.teams[].name / team _name).

At deploy time, after teams are processed, the package runner resolves teamName to the team's _id, writes _inputParams._teamId, and removes teamName from the payload before creating the workflow definition. The referenced team must exist when the workflow step runs—typically from manifest.teams earlier in the same package, or already present in the project.

ifExists#

If a workflow definition with the same name already exists:

  • default (or omitted/empty): keep the existing workflow unchanged and skip this manifest entry.
  • recreate — the existing workflow definition is deleted, then created again from the file.

Values are compared case-insensitively.

update is not supported for workflows. Any value other than default or recreate fails validation.

Deploy behavior#

  • Scripts, file uploads, knowledge bases, custom MCP tools, agents, and teams run before workflows.
  • workflows[].file is read from the ZIP workflows/ folder.
  • Existing definitions are matched by _name.
  • For AI_CONVERSE tasks, unresolved or missing teamName / team _id causes that workflow entry to be skipped.
  • If ifExists has an invalid value, the entry fails validation.

Complete example#

This example deploys agents and a team first, then workflows that depend on them (including an AI_CONVERSE task).

// manifest.json{   "Template Name": "Success Workflows",   "Template Version": "1.0.0",   "agents": [      {         "name": "Workflow Demo Agent 1",         "userType": "workflow_demo_agent_1",         "file": "test-agent-1.json",         "ifExists": "recreate"      },      {         "name": "Workflow Demo Agent 2",         "userType": "workflow_demo_agent_2",         "file": "test-agent-2.json",         "ifExists": "recreate"      }   ],   "teams": [      {         "name": "Test Team One",         "file": "test-team-one.json",         "ifExists": "recreate"      }   ],   "workflows": [      {         "name": "Basic_Weather_Fetch_Workflow",         "file": "Basic_Weather_Fetch_Workflow.json",         "ifExists": "recreate"      },      {         "name": "Weather_AI_Converse",         "file": "Weather_AI_Converse.json",         "ifExists": "recreate"      }   ]}
// Package ZIP layoutSuccess Workflows.zip /|-- agents /|   |-- test-agent-1.json|   |-- test-agent-2.json|-- teams /|   |-- test-team-one.json|-- workflows /|   |-- Basic_Weather_Fetch_Workflow.json|   |-- Weather_AI_Converse.json|-- manifest.json
// workflows/Basic_Weather_Fetch_Workflow.json{   "_description": "Minimal SCRIPT_EXECUTION workflow for template package deploy testing.",   "_userType": "weather_workflow_basic_static",   "_taskDefs": [      {         "_name": "noop_step",         "_type": "SCRIPT_EXECUTION",         "_sequenceno": 1,         "_inputParams": {            "_userType": "weather_workflow_demo_static",            "_scriptName": "generateNewYorkWeatherData"         },         "_retryCount": 0,         "_timeoutSeconds": 30      }   ],   "_timeoutSeconds": 300,   "_timeoutPolicy": "TIME_OUT_WF"}
// workflows/Weather_AI_Converse.json{   "_description": "Minimal AI_CONVERSE workflow for template package deploy testing.",   "_userType": "weather_workflow_ai_converse_static",   "_taskDefs": [      {         "_name": "ask_ai",         "_type": "AI_CONVERSE",         "_sequenceno": 1,         "_inputParams": {            "teamName": "Test Team One",            "_userPrompt": "Give a one-sentence weather tip for New York."         },         "_retryCount": 0,         "_timeoutSeconds": 120      }   ],   "_timeoutSeconds": 300,   "_timeoutPolicy": "TIME_OUT_WF"}

Note the teamName: "Test Team One" value matches the team name in the manifest. At deploy, that name is resolved to _teamId before the workflow definition is created.