microsoft / microsoft/agent-framework

Python: Nested HandoffBuilder Workflows

Open
#3,170 1 comment 0 reactions 1 assignee View on GitHub

@TaoChenOSU is already working on this.

Since Jan 12, 2026.

agents orchestration python question workflows
Dominant language
Python
Stars
13.6k
Forks
2.3k
Avg merge
2d 45m
Merged PRs (30d)
358

Description

### Discussed in https://github.com/microsoft/agent-framework/discussions/2999

Originally posted by **eddieahn** December 22, 2025
I have a use case involving nested handoff workflows in the Microsoft Agent Framework:

Parent Workflow:

- Uses HandoffBuilder with enable_return_to_previous=False
- For most questions, after an agent completes its task, control should return to the coordinator
- However, for certain specific questions, the coordinator needs to hand off to a child/sub-workflow

Child/Sub Workflow:

- Should be triggered for specific question types that require a multi-step process
- Within this sub-workflow, I need enable_return_to_previous=True
- Each agent in the sub-workflow requires substantial user input
- Agents should return to each other sequentially to complete their tasks
- Only when the entire sub-workflow is complete should control return to the parent workflow's coordinator

Question:
Is there a way to achieve this nested handoff behavior using HandoffBuilder, or does this require building a fully custom workflow? If HandoffBuilder doesn't currently support this, would this be considered a viable feature enhancement?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.