AG2 Update Watchpoints¶

This is the living update log for Mozaiks' AG2 1.0 integration. Use it when AG2 changes, when Mozaiks adds workflow runtime behavior, or when a Refinement Engine change depends on agentic execution mechanics.

Keep this file focused on intentional divergences from AG2. Broad architecture rules belong in AG2 Ownership Boundary. The current replacement plan lives in AG2 Execution Alignment Plan.

Current Baseline¶

Reviewed on August 25, 2026 against:

• installed package: ag2==1.0.2 from the ag2 import package
• declared dependencies: ag2[a2a,openai,tracing]==1.0.2, ag2[gemini]==1.0.2, and ag2[anthropic]==1.0.2
• AG2 docs:
• https://docs.ag2.ai/latest/docs/beta/network/overview/
• https://docs.ag2.ai/latest/docs/beta/network/hub_and_identity/
• https://docs.ag2.ai/latest/docs/beta/network/agent_clients/
• https://docs.ag2.ai/latest/docs/beta/network/adapters_overview/
• https://docs.ag2.ai/latest/docs/beta/network/migration_from_group_chat/
• https://docs.ag2.ai/latest/docs/beta/network/task_observation/
• https://docs.ag2.ai/latest/docs/beta/tasks/
• https://docs.ag2.ai/latest/docs/beta/ag2_compatibility/
• https://docs.ag2.ai/docs/blog/2026/05/14/AG2-Action-Driven-Network/
• https://docs.ag2.ai/docs/blog/2026/05/16/AG2-Network-What-Survives/
• https://docs.ag2.ai/docs/blog/2026/06/16/AG2-Network-Networks-You-Can-Deploy/
• https://docs.ag2.ai/docs/blog/2026/06/17/AG2-Agent-Harness/

AG2 currently owns the primitives Mozaiks should not recreate:

• Hub, HubClient, AgentClient, channel lifecycle, WAL, and audit state
• WorkflowAdapter, TransitionGraph, AgentTarget, TerminateTarget, FromSpeaker, ToolCalled, and ContextEquals
• default agent notify handling, including WAL projection into agent context, Agent.ask(...), and round-end packet emission
• Task, task lifecycle events, TaskMirror, and capability observation

Mozaiks still owns deterministic product contracts around those primitives:

• workflow YAML validation and compilation
• tenant/session/app context boundaries
• structured-output validation for generated artifact contracts
• Studio/platform transport projection and persistence
• artifact lineage, validation, promotion, and scoped refinement policy
• task-batch DAG policy and result ownership checks

Intentional Divergences¶

Too-Much-Ownership Flags¶

Treat these as cleanup or upstream-collaboration triggers:

• Any new Mozaiks loop that decides the next agent turn without AG2 WorkflowAdapter/TransitionGraph.
• Any new Mozaiks wrapper around Agent.ask(...) for multi-agent workflow execution outside mozaiksai.core.adapters.
• Any new custom task observation stream when a real HubClient or Hub is present and TaskMirror can provide the lifecycle signal.
• Any new workflow runtime state store that duplicates AG2 channel WAL or Hub audit without a tenant/session persistence reason.
• Any Refinement Engine feature that lets an AG2 agent directly promote artifacts, mutate routing policy, or choose workspace state without deterministic Mozaiks validation.

Update Procedure¶

Run this procedure whenever AG2 is upgraded or when workflow runtime code changes under mozaiksai/core/workflow, mozaiksai/core/adapters, or mozaiksai/control_plane.

1. Confirm the installed AG2 version:

@'
import ag2
print(getattr(ag2, "__version__", "unknown"))
print(ag2.__file__)
'@ | .\.venv\Scripts\python.exe -

1. Inspect AG2 1.0 surfaces in the installed package:

rg --hidden --no-ignore "class (Hub|HubClient|AgentClient|WorkflowAdapter|TransitionGraph|TaskMirror|Task)|context_vars|EV_PACKET|EV_CHANNEL_CLOSED" .\.venv\Lib\site-packages\ag2\network -n

1. Re-check official AG2 docs for Network, Tasks, Task Observation, and Adapter behavior.

2. For each divergence above, decide one of:

3. retire: AG2 now owns the capability directly.
4. shrink: Mozaiks still needs an adapter, but the adapter can get thinner.
5. keep: the behavior is a Mozaiks product/runtime contract.

6. upstream: the behavior is generic agent orchestration and should be raised with AG2.

7. Run targeted tests:

pytest tests/test_ag2_network_execution_alignment.py tests/test_workflow_network_graph.py tests/test_ag2_agent_runner.py

1. Update this file and any affected architecture docs in the same change.

Current Decision Log¶

August 25, 2026¶

• AG2 1.0.2 compatibility audit completed: an isolated prospect installation passed dependency checks, imports, signature comparisons, and non-network probes for the AG2 surfaces Mozaiks uses. No production or test compatibility changes were required.
• Modernization remains separate: this upgrade does not adopt AG2 assembly policies, evaluation, or additional dependency-injection primitives.
• Existing fragile seams remain explicit watchpoints: the wrapped Network default handler, channel-state dependency key, event-class serialization, event representation parsing, and detailed task lifecycle assumptions remain covered by focused tests rather than changed in this upgrade.

August 23, 2026¶

• Sandbox ownership boundary codified: app-preview/validation sandboxes (SandboxPort + e2b/docker adapters, preview URLs, app boot) are Mozaiks-owned application-runtime behavior outside AG2's snippet-execution scope; agent-level execution stays on AG2 SandboxShellTool (already used by six AppGenerator agents). The coding worker's unimplemented e2b validation label was removed so build records only claim strategies that actually ran. Session identity/metadata now persists (validation results carry sandbox_session_id/sandbox_provider; preview sandboxes are created with identity metadata and provider-side kill deadlines), closing the orphaned-sandbox billing vector ahead of hosted e2b activation.
• Upstream questions filed as AG2 discussion #3201: the declarative-network asks (serialized TransitionGraph schema, per-agent response_schema on workflow channels, composable/serializable transition conditions, a public round-end packet hook, a typed one-shot Consulting primitive) are now posted at https://github.com/ag2ai/ag2/discussions/3201. Check that thread before the next alignment pass; fold maintainer answers into the divergence rows above.
• AG2 skills user guide reviewed (https://docs.ag2.ai/docs/user-guide/skills/): no impact on current Mozaiks surfaces. Two standing rules from the review:
• If factory prompt catalogs (capability routing, module archetypes) ever move to on-demand loading for token efficiency, AG2 SkillPlugin progressive disclosure is the sanctioned mechanism — do not build a Mozaiks-owned lazy prompt loader.
• Runtime skill installation (SkillSearchToolkit.install_skill against the skills registry) must never be wired into factory or generated-app agents: it is nondeterministic and a supply-chain vector into the build pipeline.

August 22, 2026¶

• AG2 Harness and deployable-network series reviewed; build repair remains Mozaiks-owned deterministic policy: reviewed the Agent Harness, Networks You Can Deploy, and What Survives posts alongside the Action-Driven Network review. Conclusions:
• MemoryStream, retry/telemetry middleware, token observers, tools, and human-input hooks are useful execution and observability primitives. Mozaiks already uses the applicable primitives behind adapter boundaries.
• AG2 LoopDetector observes repeated tool calls; it does not replace the AppGenerator acceptance gate. AppGenerator therefore fingerprints normalized validation failures and deterministically blocks an unchanged repair result.
• AG2 compaction, aggregation, and KnowledgeStore are conversation-memory concerns. App context, validation evidence, artifact lineage, staleness, acceptance, and promotion remain typed Mozaiks records rather than agent memory.
• Hub WAL, checkpoint storage, at-least-once delivery, authentication, dynamic membership, and federation matter when workflow workers cross process or trust boundaries. They are not prerequisites for the local build-repair loop. Mozaiks should adopt the native durable channel path when it can preserve tenant scope and exact resumability, rather than creating a second agent network.

• None of the four posts changes the ownership boundary: AG2 may execute agent turns and preserve channel events; Mozaiks selects the artifact version, classifies impact, validates generated files, bounds repair, requires review, and authorizes promotion.

• Action-Driven Network blog post reviewed, layering confirmed: reviewed AG2's Action-Driven Network post (https://docs.ag2.ai/docs/blog/2026/05/14/AG2-Action-Driven-Network/) against the Mozaiks routing layers. Conclusions:

• transition_graph.yaml compiled through AG2NetworkRunner is the layer aligned with the ADN Workflow shape (WorkflowAdapter + TransitionGraph). Keep it thin and ADN-shaped so it continues to delegate routing to AG2.
• factory_app/workflows/extended_orchestration/extension_registry.json (cross-workflow build journeys, human user_choice_context screen transitions, artifact dependency graph, affected_declarative_families) sits above what ADN models. ADN channels have no concept of human screen steps, artifact lineage, or staleness-driven re-entry. This stays Mozaiks-owned; do not model a build journey as one ADN Workflow channel.
• The Refinement Engine (mozaiksai/control_plane/) is deterministic artifact policy whose LLM checkpoints map to the ADN Consulting shape (1Q1R, auto-close) via AG2StructuredAgentRunner. It stays Mozaiks-owned per the existing ownership boundary; only the one-shot LLM call belongs to AG2.
• No new divergence introduced. Sharpened the two Consulting-shape watchpoint rows and added upstream question 6 on cross-workflow sequencing.

August 14, 2026¶

• AG2 1.0.1 task lifecycle evidence adopted for task batches: AG2TaskBatchRunner creates an AG2 Task for each deterministic task-batch work item, subscribes to the task stream, executes the preselected worker Agent.ask(...), and records normalized lifecycle evidence. Mozaiks still owns task id selection, worker selection, dependencies, concurrency, prompts, context, tool profile, owned paths, timeout, retries, structured-output validation, output destination, and merge behavior.
• TaskMirror remains deferred for standalone task-batch workers: AG2 1.0.1 TaskMirror requires a HubClient or Hub. The current task-batch runner does not restructure workers into real Hub clients in this change, so it uses authentic standalone Task stream events and leaves channel_id unset. This path does not claim AG2 channel WAL or durable AG2 task/channel resume.

July 28, 2026¶

• AG2 stable baseline adopted: Mozaiks now pins ag2==1.0.0 instead of 1.0.0b0.
• Multimodal media boundary added: mozaiksai.core.media owns provider-neutral media refs, generated media metadata/storage, and AG2 adapter helpers. Workflow product logic must use those primitives rather than storing generated images in chat text or duplicating provider-specific AG2 setup.
• OpenAI image generation config boundary: image-generation agents use OpenAIResponsesConfig through Mozaiks config conversion because AG2 ImageGenerationTool requires the Responses API. Non-image-generation OpenAI agents keep the existing OpenAIConfig path.

July 8, 2026¶

• AG2 package namespace migrated: Mozaiks targeted ag2==1.0.0b0 and imports active beta APIs from ag2.*.
• Mozaiks expression compatibility gap: AG2 1.0.0b0 did not expose a native expression helper for Mozaiks ${context_variable} workflow contracts. Mozaiks keeps a small source-scoped evaluator in ag2_transition_conditions.py for the declarative context_expression contract.
• Retired cache/logger hooks: AG2 1.0.0b0 no longer exposed the earlier cache/logger hook modules; Mozaiks preserves cache seeds for AG2 config conversion and removed the file-logger monkeypatch.
• A2A follow-up: importing ag2.a2a.client currently requires the gRPC dependencies from a2a-sdk[grpc] in this environment. Validate the new AG2 A2A remote-agent API before re-enabling that optional workflow surface.

June 12, 2026¶

• Live AgentGenerator pack smoke passed with real AG2/model calls: scripts/smoke_agentgenerator_live_pack.py --timeout-seconds 900 generated two workflow bundles in parallel, confirmed task overlap through AG2TaskBatchRunner, exported the bundle zip, promoted the generated workflows into an isolated active root, and loaded both workflows through UnifiedWorkflowManager.
• Coordinator/metadata one-shot calls use AG2 task primitive in the smoke: single-agent AG2 Network channel execution timed out before packet emission during the approved-generation coordinator/metadata setup. Direct AG2 task calls completed reliably, so the smoke uses the task primitive for those one-shot setup calls while keeping the generated workflow workers on the real task-batch path. This is a smoke-harness watchpoint, not a new runtime orchestration abstraction.

June 11, 2026 (update 2)¶

• Context expression routing used upstream evaluators in 0.13.x: network_graph.py compiles deterministic routing into AG2 1.0 TransitionCondition objects registered from mozaiksai.core.adapters. Simple equality uses AG2 ContextEquals; tool routes use AG2 ToolCalled; composite context routes use the canonical condition_type: context_expression field and Mozaiks' local ${context_variable} evaluator. The remaining divergence is source-scoping those AG2 conditions to Mozaiks' declarative source_agent field and bridging WorkflowState.context_vars into the local expression evaluator.
• Stream projection boundary: The active Studio/platform event projection surface is _project_ag2_wal_to_mozaiks_transport(...) in ag2_network_runner.py.

June 11, 2026¶

• Keep AG2NetworkRunner, AG2TaskBatchRunner, and AG2StructuredAgentRunner as narrow adapters under mozaiksai.core.adapters.
• AG2NetworkRunner now listens for AG2 on_turn_failed events and returns a failed Mozaiks runner result promptly, while keeping the failure mapping inside the adapter boundary.
• Keep task-batch DAG scheduling in Mozaiks because AG2 Task is lifecycle and observation, not deterministic assignment or dependency scheduling.
• Keep the Refinement Engine as deterministic Mozaiks policy. Use AG2 only for typed LLM checkpoints behind AG2StructuredAgentRunner.
• Treat _install_context_update_handler as the highest-priority AG2 compatibility watchpoint. It is acceptable only because it is isolated to the AG2 adapter boundary.
• Do not create a separate root AGENT_UPDATE.md; this document is the canonical update tracker and is included in the architecture docs navigation.

Upstream Questions¶

Use these with the AG2 team when planning the next alignment pass:

1. Is a public default-handler hook planned for inspecting or transforming the round-end EV_PACKET before WorkflowAdapter.fold(...)?
2. What is the intended durable production KnowledgeStore path for tenant scoped Hub WAL and audit data?
3. Should deterministic external task DAGs be represented as workflow channels, consulting channels, task envelopes, or a future AG2 task graph primitive?
4. Will AG2 expose native condition composition for deterministic transitions, especially FromSpeaker AND ContextEquals and FromSpeaker AND ToolCalled, or should applications keep registering source-scoped custom conditions?
5. What is the recommended durable cancellation/resume model for long-running workflow channels with HITL pauses?
6. Does the Action-Driven Network roadmap intend to model cross-workflow sequencing with human-in-the-loop steps between channels (for example a channel-of-channels or journey primitive), or is the intended pattern application-owned sequencing that opens one Workflow channel per step, as Mozaiks does today through extension_registry.json workflow sequences?