Magentic workflow builder (agentworkflow.NewMagenticWorkflowBuilder)

[PratikDhanave]

Summary

docs/dotnet-go-sdk-feature-comparison.md lists the agent-workflow builders as Partial: "Handoff and Magentic builders are not yet implemented." Handoff is now in flight (#545). This issue proposes the Magentic builder to close the last named gap and reach parity with the .NET MagenticBuilder / Magentic-One orchestration pattern.

What Magentic is

A manager-orchestrated multi-agent pattern: an orchestrator LLM maintains a task ledger (facts + plan) and re-evaluates a progress ledger each round (is the request satisfied? are we stalled/looping? who speaks next, and with what instruction?). It delegates to specialist agents, replans on stalls, and terminates on completion — strictly more capable than round-robin group chat.

Proposed API

Matching the existing New…WorkflowBuilder conventions (sequential / concurrent / group chat):

wf, err := agentworkflow.NewMagenticWorkflowBuilder(researcher, coder, reviewer).
    WithManager(orchestrator).            // the orchestrator agent / chat client
    WithMaximumRoundCount(30).            // total invocation cap
    WithMaximumStallCount(3).             // rounds without progress before replanning
    WithMaximumResetCount(2).             // ledger rebuilds before giving up
    WithName("magentic").
    WithOutputFrom(reviewer).
    Build()

Implementation sketch

Reuse the groupChatHostExecutor + GroupChatManager machinery that Handoff (#545) already builds on. The Magentic manager implements SelectNextAgent (from the progress ledger's next_speaker) and ShouldTerminate (request satisfied, or reset budget exhausted). The task/progress ledgers become checkpoint-persisted manager state, matching the existing per-session-isolation model.

Design questions for maintainers

1. Orchestrator handle — the manager needs its own LLM. Prefer WithManager(*agent.Agent), a lower-level chat-client interface, or a MagenticManagerFactory mirroring GroupChatManagerFactory?
2. Ledger prompts — ship a StandardMagenticManager with built-in prompts (like .NET), and/or expose the prompts / JSON ledger schema for overriding?
3. Stall/reset semantics — should a reset rebuild the whole task ledger, or only the plan? Terminate vs. surface a partial result when the reset budget is exhausted?
4. Scope — land the standard manager first, or the builder + a pluggable manager interface together?

I implemented the Handoff builder (#545) reusing this same machinery and would like to own this one end-to-end, matching your test conventions (canonical file, black-box where possible, red-green). Happy to adjust the API to your preferences before writing code.