Declarative Config to AG2 Mapping¶

This document maps canonical workflow YAML declaratives to AG2-native execution.

Runtime loading is strict. Files are validated by typed contracts (Pydantic with extra="forbid"), so examples here use only canonical shapes.

Core Point¶

Only workflow declaratives map to AG2.

These do not map to AG2:

• app backend declaratives
• shell declaratives
• domain event contracts
• workflow triggers

Those are Mozaiks layers that exist before a workflow starts.

Workflow File Mapping¶

Native or Near-Native Mappings¶

orchestrator.yaml¶

Maps to workflow-local execution concerns such as:

• pattern selection
• startup mode
• initial agent
• initial message
• turn budget

Canonical startup key is workflow_startup_mode (AgentDriven, UserDriven, BackendOnly).

orchestration_pattern is metadata describing the selected AG2 Network patternbook label. The runtime does not route from this string; it routes from the compiled transition_graph.yaml transition graph.

agents.yaml¶

Each agent entry becomes an AG2 agent definition after prompt composition and tool binding.

transition_graph.yaml¶

Maps to AG2 1.0 Network transition conditions and targets. Mozaiks compiles the rules into a TransitionGraph; turn-to-turn routing is resolved through AG2 1.0 WorkflowAdapter.

Runtime compilation rules:

• unconditional after_turn rules compile to FromSpeaker
• condition_type: context_equals rules compile to a source-scoped adapter over AG2 ContextEquals
• condition_type: context_expression rules compile to a source-scoped custom AG2 1.0 TransitionCondition that evaluates Mozaiks ${context_variable} syntax against workflow context state
• condition_type: tool_called rules compile to SourceScopedToolCalled, a native AG2 ToolCalled subclass that also checks the declared source agent
• target_agent: user pauses the run for user input
• target_agent: terminate compiles to TerminateTarget

AG2 derives tool routing from its native ToolCallEvent stream, including turns with an empty message body. The registered mozaiks_source_tool_called condition retains both source_agent_id and tool_name through graph serialization and rehydration. Static tool routing still evaluates the source predicate when AG2 selects the target: another agent calling the same tool cannot satisfy that rule. Text mentioning the tool and a ToolResultEvent without its matching call do not establish a tool transition. AG2 owns event interpretation, packet construction, transition evaluation, and workflow state progression.

LLM classification belongs before routing: a Refinement Engine route, agent tool, or structured output sets context state; the graph then routes deterministically.

Termination is declarative. A workflow bundle ends through transition_graph.yaml, usually by routing the final agent to:

- source_agent: FinalAgent
  target_agent: terminate
  transition_type: after_turn
  transition_target: TerminateTarget

The runtime does not inspect message text for completion and does not use a separate Python termination handler. During execution, Mozaiks resolves the next speaker through AG2 1.0 WorkflowAdapter; when that resolution returns AG2 TerminateTarget, the turn loop reports run_completed=true and the runtime marks the app-scoped ChatSessions run as completed. max_turns remains a safety cap, not the primary happy-path completion mechanism.

A rule may end the run as failed with termination_reason: workflow_failed. That close, max_turns and no_transition_matched end the run as failed: the session is marked failed and one chat.run_complete with status: failed carries the close reason. A workflow can explain a workflow_failed end to the user by naming a declared string context variable in orchestrator.yaml:

failure_message_key: app_build_failure_message

A deterministic tool writes that variable when it decides the run cannot continue; the runtime reports its text as the failed run's error.

context_variables.yaml¶

Maps to the shared workflow state container used during execution.

Canonical shape:

definitions:
  var_name:
    type: string
    source:
      type: state
      default: null
agents:
  AgentName:
    variables:
      - var_name

ContextAuthorityPolicy owns write permission. The factory-injected ContextVariablesBridge checks each set or delete before accepting it. A declared deterministic_tool writer is selected only inside the trusted callable invocation installed by the agent factory, bound to that exact bridge, policy instance, and (workflow_name, app_id, chat_id) run. Tool arguments cannot replace the injected bridge or choose its writer identity. Ordinary bridge access remains context_bridge; a variable declaration alone does not establish tool provenance.

The invocation's deterministic attribution expires when the callable exits, including on failure. Revocation also applies to invocation context inherited by unfinished child tasks. Each pending set or delete retains the writer that authorized that operation; later operations are checked independently. Before publication, the packet adapter verifies the same policy/run binding and checks every pending operation again under its retained writer. Updates already present in an outgoing packet receive only context_bridge attribution. Authorized updates then reach AG2's native fold before ContextEquals selects the next speaker.

tools.yaml¶

Maps to callable tool registration, with optional Mozaiks validation or wrapper behavior.

Canonical shape:

tools:
  - agent: AgentName
    file: tool_file.py
    function: run_tool
    tool_type: Agent_Tool
  - agent: AgentName
    file: render_status.py
    function: render_status
    tool_type: UI_Surface
    ui:
      component: StatusPanel
      mode: artifact
lifecycle_tools: []

middleware.yaml¶

Maps to Mozaiks prompt-injection declarations. Runtime registration is AG2 1.0 agent middleware, not prior hook registration style. Lifecycle behavior belongs in tools.yaml lifecycle_tools.

Canonical shape:

prompt_middleware:
  - agent: AgentName
    filename: hook_file.py
    function: update_state

Mozaiks-Only Workflow Layers¶

structured_outputs.yaml¶

Used for:

• typed validation
• deterministic auto-tool flows
• stronger execution guarantees than prompt text alone

Canonical shape:

schema_version: mozaiks.structured_outputs.v1
registry:
  AgentName: ModelName
models:
  ModelName:
    type: model
    fields:
      field_name:
        type: str

ui_config.yaml¶

Used for:

• frontend rendering metadata
• agent visibility rules

extended_orchestration/task_batches.yaml¶

Used for:

• declaring which agent produces or exposes a typed task list
• mapping each task item to an AG2 worker agent and prompt
• bounding concurrency, retries, timeouts, dependencies, and failure policy
• declaring the result context key consumed by later workflow agents

The typed DAG contract is Mozaiks-owned because AG2 Task does not assign, dependency-sort, or merge artifact work. Worker execution, task lifecycle observation, and network turn handling should use AG2 Network/Task primitives where practical. See AG2 Execution Alignment Plan.

Minimal task batch authored form:

version: 1
batches:
  - id: my_tasks
    trigger_agent: PlanningAgent
    source:
      kind: context_variable
      path: plan.tasks
      task_model: MyTask
    worker:
      mode: ag2_agent
      agent_field: initial_agent
      prompt_field: initial_message
    result:
      context_key: my_task_results
      status_key: my_task_status

Schema defaults that do not need to be authored: - worker.mode defaults to ag2_agent - execution.concurrency defaults to 4 - execution.failure_policy defaults to fail_batch - result.merge_strategy defaults to collect_task_outputs

Declare result keys in context_variables.yaml when agents need to read them. task_batches.yaml is execution config; it is not a substitute for typed shared workflow state.

What Sits Before AG2¶

The following app-bundle families are consumed before AG2 is involved:

• app/data/*
• app/modules/*
• app/config/*
• workflow triggers: declared in workflows/*/orchestrator.yaml for app-owned workflows, or factory_app/workflows/*/orchestrator.yaml for builder/system workflows

Most importantly:

• a domain event becomes a route decision before AG2 sees a workflow input

That route decision belongs to Mozaiks.

Design Guardrails¶

Do not use AG2 as the conceptual home for:

• CRUD state
• navigation
• settings and subscription policy
• domain event naming
• event-to-workflow policy

Use AG2 for what it is good at:

• conversations
• handoffs
• tool use
• agent coordination inside a workflow

AgentGenerator selects workflow shapes from the shared AG2 Network Patternbook. The patternbook guides generation; the generated YAML remains the runtime contract.

Authoring Note¶

Use *.yaml declaratives in workflow bundles.

Cross References¶

• workflow-architecture.md
• ../foundations/events-and-data/event-system.md
• ../foundations/core-product-app-bundle-boundary.md