Agent/Task Workflows

Agent/Task Workflows

This guide focuses on authoring Agent/Task workflows (kind: agent_workflow) from YAML or JSON.

Use this format when you want a higher-level authoring model and let PetalFlow compile it into Graph IR.

Canonical Schemas

The authoritative schema contracts are published in the PetalFlow repository:

• Agent/Task v1 schema: schemas/agent-workflow/v1.json
• Graph IR v1 schema (compile target): schemas/graph-workflow/v1.json

Raw URLs for editor tooling:

• raw agent-workflow v1
• raw graph-workflow v1

Required Top-Level Fields

Agent/Task workflows require these fields:

Field	Type	Notes
version	string	Your workflow/business version
schema_version	string	SemVer schema contract (MAJOR.MINOR.PATCH)
kind	string	agent_workflow (canonical), agent-workflow accepted for compatibility
id	string	Workflow identifier
name	string	Human-readable name
agents	object	Map of agent IDs to agent definitions
tasks	object	Map of task IDs to task definitions
execution	object	Strategy and execution wiring

Note

schema_version major 1 is the currently supported contract for agent workflows.

Minimal YAML Example

version: "1.0"
schema_version: "1.0.0"
kind: agent_workflow
id: release_notes_flow
name: Release Notes Flow

agents:
  researcher:
    role: Research Analyst
    goal: Gather release context
    provider: anthropic
    model: claude-sonnet-4-20250514

  writer:
    role: Technical Writer
    goal: Draft concise release notes
    provider: anthropic
    model: claude-sonnet-4-20250514

tasks:
  gather_changes:
    description: Summarize major changes for {{input.version}} from provided changelog text.
    agent: researcher
    expected_output: Structured bullet summary

  draft_notes:
    description: Write final release notes using {{tasks.gather_changes.output}}.
    agent: writer
    expected_output: Final release notes markdown

execution:
  strategy: sequential
  task_order:
    - gather_changes
    - draft_notes

Equivalent JSON Example

{
  "version": "1.0",
  "schema_version": "1.0.0",
  "kind": "agent_workflow",
  "id": "release_notes_flow",
  "name": "Release Notes Flow",
  "agents": {
    "researcher": {
      "role": "Research Analyst",
      "goal": "Gather release context",
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514"
    },
    "writer": {
      "role": "Technical Writer",
      "goal": "Draft concise release notes",
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514"
    }
  },
  "tasks": {
    "gather_changes": {
      "description": "Summarize major changes for {{input.version}} from provided changelog text.",
      "agent": "researcher",
      "expected_output": "Structured bullet summary"
    },
    "draft_notes": {
      "description": "Write final release notes using {{tasks.gather_changes.output}}.",
      "agent": "writer",
      "expected_output": "Final release notes markdown"
    }
  },
  "execution": {
    "strategy": "sequential",
    "task_order": ["gather_changes", "draft_notes"]
  }
}

Agent Definition

Each agent requires:

• role
• goal
• provider
• model

Optional agent fields:

• backstory
• tools (array of tool references)
• tool_config (per-tool config overrides)
• config (provider/model settings, such as temperature/max tokens)

Task Definition

Each task requires:

• description
• agent (must reference an existing agent ID)
• expected_output

Optional task fields:

• output_key
• inputs
• review (human enables human gate in compiled flow)
• context (task IDs providing additional context)

Template Syntax (description / inputs)

Use these references in task templates:

• {{input.field}} for runtime input vars
• {{tasks.other_task.output}} for prior task outputs

Example:

tasks:
  summarize:
    description: Summarize {{input.topic}} with context {{tasks.research.output}}.
    agent: writer
    expected_output: Concise summary

Execution Strategies

Supported values for execution.strategy:

• sequential
• parallel
• hierarchical
• custom

Sequential

Requires execution.task_order including all task IDs.

execution:
  strategy: sequential
  task_order: [research, write, review]

Parallel

Tasks execute as parallel branches and are merged by compiler/runtime behavior.

execution:
  strategy: parallel
  merge_strategy: concat

Hierarchical

Requires manager_agent.

execution:
  strategy: hierarchical
  manager_agent: coordinator

Custom (DAG)

Declare dependencies with execution.tasks.<task>.depends_on.

execution:
  strategy: custom
  tasks:
    draft:
      depends_on: [research]
    qa:
      depends_on: [draft]
      condition: tasks.draft.output.confidence > 0.8

Caution

custom dependencies must form a DAG (no cycles). Conditions must parse successfully when expression validation is enabled.

Validate, Compile, Run

1. Validate Agent/Task structure and references.
2. Compile to Graph IR.
3. Run compiled graph (or run Agent/Task directly).

# 1) Validate
petalflow validate workflow.agent.yaml

# 2) Compile
petalflow compile workflow.agent.yaml --output workflow.graph.json

# 3) Run
petalflow run workflow.graph.json --input '{"topic":"workflow automation"}'

Common Validation Failures

Frequent errors include:

• Missing required fields (AT-010)
• Undefined agent references (AT-001)
• Invalid execution strategy (AT-005)
• Incomplete/incorrect task_order in sequential mode (AT-006)
• Cycles in custom dependency graphs (AT-007)
• Unresolved task template/context references (AT-008)
• Invalid schema header (AT-014)

Authoring Tips

Use stable IDs

Keep task/agent IDs predictable and lowercase snake_case for maintainability.

Pin schema_version

Set schema_version explicitly in all workflows and update intentionally.

Compile in CI

Run validate and compile in CI before deployment to catch schema drift early.

Prefer YAML for editing

Use YAML for authoring comfort, JSON for generated/serialized artifacts.