microsoft / microsoft/agent-framework-go

Proposal: Handoff agent-workflow builder (agentworkflow.NewHandoffWorkflowBuilder)

Open
#520 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.