AgentGenerator Output Assembly Contract¶

Status: CANONICAL — describes what actually exists Last verified: 2026-05-31 Source files: - factory_app/workflows/AgentGenerator/tools/generate_and_download.py - factory_app/workflows/AgentGenerator/tools/workflow_converter.py - factory_app/workflows/AgentGenerator/structured_outputs.yaml - factory_app/workflows/AgentGenerator/agents.yaml - factory_app/workflows/AgentGenerator/extended_orchestration/task_batches.yaml

Related: structured-output-extraction-contract.md — the general runtime contract for structured outputs and auto-tool-call. This document covers the AgentGenerator-specific pattern where a task batch worker agent produces all workflow bundle files in a single structured output.

How This Works¶

AgentGenerator uses the task batch pattern:

1. PackBuildCoordinator collects the user's workflow pack specification into pack_spec (context variable)
2. The workflow_bundle_tasks task batch fires — one WorkflowBundleBuilderAgent instance per workflow in the pack, running in parallel
3. Each worker emits a WorkflowBundleBuilderOutput with a files list of CodeFile entries
4. The runtime collects all results into context_variables["workflow_bundle_results"], keyed by task_id
5. generate_and_download reads workflow_bundle_results, writes each bundle to disk, zips them, and presents the download UI

There are no sequential planning agents scraping MongoDB. Each WorkflowBundleBuilderAgent instance owns its full bundle output end-to-end.

Generated workflow bundles are staged at:

$MOZAIKS_GENERATED_ARTIFACTS_PATH/workflows/{app_id}/{workflow_name}/

They do not become active runtime-loaded workflows until an explicit promotion step copies them into an active app root's workflows/ directory.

Agent Roster¶

Task Batch: workflow_bundle_tasks¶

Declared in extended_orchestration/task_batches.yaml.

source:
  kind: context_variable
  path: pack_spec.workflows
  task_model: WorkflowInPack
worker:
  mode: ag2_agent
  agent_field: initial_agent   # WorkflowBundleBuilderAgent
  prompt_field: initial_message
result:
  context_key: workflow_bundle_results
  status_key: workflow_bundle_status

Each task receives one WorkflowInPack entry from pack_spec.workflows. The runtime injects it as context_variables["structured_output"] for the worker.

WorkflowBundleBuilderOutput¶

The worker emits a single WorkflowBundleBuilderOutput structured output:

workflow_name: str
files:
  - filename: orchestrator.yaml
    content: "..."
  - filename: agents.yaml
    content: "..."
  - filename: handoffs.yaml
    content: "..."
  - filename: context_variables.yaml
    content: "..."
  - filename: structured_outputs.yaml
    content: "..."
  - filename: tools.yaml
    content: "..."
  - filename: hooks.yaml
    content: "..."
  - filename: ui_config.yaml
    content: "..."
  - filename: tools/some_tool.py
    content: "..."
  - filename: ui/index.js
    content: "..."

Each CodeFile has: - filename — workflow-local relative path (e.g., tools/save_result.py, ui/index.js) - content — full file content as a string

workflow_bundle_results Structure¶

After the task batch completes, context_variables["workflow_bundle_results"] is a dict:

{
    "task_id_1": {
        "workflow_name": "StoryCreator",
        "files": [
            {"filename": "orchestrator.yaml", "content": "..."},
            {"filename": "agents.yaml", "content": "..."},
            ...
        ]
    },
    "task_id_2": {
        "workflow_name": "ReviewWorkflow",
        "files": [ ... ]
    }
}

Keys starting with _ are internal meta entries and are skipped during assembly.

Assembly: generate_and_download¶

Reads workflow_bundle_results directly from context. For each bundle entry:

1. _write_bundle_to_disk(wf_name, files, base_dir) — writes all CodeFile entries under base_dir/{wf_name}/
2. _build_pack_zip(bundle_dirs, output_path) — zips all workflow directories into a single archive
3. use_ui_tool("DownloadCenter", ...) — presents the download UI to the user

No MongoDB scraping. No create_workflow_files() assembly step.

Files Written¶

$MOZAIKS_GENERATED_ARTIFACTS_PATH/workflows/{app_id}/
├── {WorkflowName}/
│   ├── orchestrator.yaml
│   ├── agents.yaml
│   ├── handoffs.yaml
│   ├── context_variables.yaml
│   ├── structured_outputs.yaml
│   ├── tools.yaml
│   ├── hooks.yaml
│   ├── ui_config.yaml
│   ├── extended_orchestration/
│   │   └── task_batches.yaml   ← if workflow uses task batches
│   ├── tools/
│   │   └── *.py               ← tool implementations
│   └── ui/
│       ├── index.js            ← component barrel
│       └── *.jsx               ← workflow-local React components
└── {PackName}.zip             ← all workflows bundled together

Generated workflow tools are workflow-local. Generated bundles must not reference workflows/_shared, sibling workflow tool folders, or root-level shared paths. Reusable framework-owned support code belongs under mozaiksai.core.*.

Workflow Name and Pack Name¶

• bundle_name is derived from context_variables["pack_name"] if set, otherwise from the first workflow's workflow_name
• All names are converted to PascalCase for the output folder and zip file name

Normalization Utilities in workflow_converter.py¶

workflow_converter.py is a contract normalization helper — it does NOT do assembly. Functions exported:

These are used by tests and by WorkflowBundleBuilderAgent implementations as reference for what a well-formed bundle looks like.

What Does NOT Exist¶

Cross References¶

• structured-output-extraction-contract.md — general auto-tool-call pattern
• workflow-authoring-contracts.md — extended_orchestration/task_batches.yaml format
• factory_app/workflows/AgentGenerator/tools/generate_and_download.py — assembly and download
• factory_app/workflows/AgentGenerator/tools/workflow_converter.py — normalization utilities
• factory_app/workflows/AgentGenerator/extended_orchestration/task_batches.yaml — task batch config
• factory_app/workflows/AgentGenerator/structured_outputs.yaml — WorkflowBundleBuilderOutput model