microsoft / microsoft/agent-framework-go
Proposal: Handoff agent-workflow builder (agentworkflow.NewHandoffWorkflowBuilder)
- Dominant language
- Go
- Stars
- 618
- Forks
- 56
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 122
Description
## Gap
`docs/dotnet-go-sdk-feature-comparison.md` marks the agent-workflow builders as **Partial**: Go has `NewSequentialWorkflowBuilder`, `NewConcurrentWorkflowBuilder`, and `NewGroupChatWorkflowBuilder`, but the doc notes *"Handoff and Magentic builders are not yet implemented."* There is no `handoff` reference anywhere in `workflow/` or `agent/` today.
Handoff is the missing member of the core orchestration set and the more broadly useful of the two gaps: a triage/router agent hands control to a specialist based on the conversation; the specialist can hand back, or on to another agent.
## Proposed shape (seeking design alignment *before* any code)
A sibling builder in `workflow/agentworkflow`, matching the existing builders' convention (`New…WorkflowBuilder(agents ...*agent.Agent)`, `WithName` / `WithDescription` / `WithOutputFrom`, `Build() (*workflow.Workflow, error)`):
```go
agentworkflow.NewHandoffWorkflowBuilder(triage).
WithHandoff(triage, billing, refunds).
WithHandoff(billing, triage).
Build()
```
Modeled on .NET's `HandoffBuilder` (`Microsoft.Agents.AI.Workflows`): each participating agent is given handoff *tools* (one per allowed target); when the agent calls a handoff tool, the workflow routes the turn to that target carrying the shared conversation. Under the hood it should compose onto the existing executor graph / group-chat manager plumbing rather than introduce a new engine.
## Design questions I'd want the team's steer on first
1. Handoff surfaced as auto-injected function tools (the .NET approach), vs. an edge condition on the agent's chosen target?
2. Reuse the group-chat manager machinery, or a dedicated handoff executor?
3. Termination: an explicit end agent, a max-turns cap, or a "no handoff called → done" signal?
4. Scope handoff only for this issue; track Magentic separately?
## Why I'm asking first
This is a feature, not a bug fix, so I don't want to drop an unsolicited large PR that then rots. If the team is open to it and we can agree on the shape (tools-vs-edges especially), I'm happy to implement it with the same test rigor as the recent fixes, matching the .NET semantics for cross-SDK parity.
Contributor guide
Research direction
Start with docs/dotnet-go-sdk-feature-comparison.md and the existing builders under workflow/agentworkflow, then inspect the agent and workflow packages for current executor-graph and group-chat manager plumbing. Review the .NET HandoffBuilder semantics and resolve the listed design questions before implementation. Done means an agreed API and behavior for routing shared conversations between agents, with matching tests and documentation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- ai, backend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100