feat(agents): add multi-agent supervisor primitives

[tikhandesanket]

Description

This PR implements the multi-agent supervisor pattern proposed in #289.

The supervisor acts as a central orchestrator that receives a user request, determines which specialist agent should handle it, and routes the request accordingly.

The implementation focuses on keeping the agents decoupled, with the supervisor responsible for coordination rather than embedding specialist-specific logic into individual agents.

Related issue

Fixes #289

Changes

• Add a supervisor agent responsible for routing requests.
• Support routing to multiple specialist agents.
• Preserve conversation/state information during agent handoffs.
• Keep specialist agents independently defined and reusable.
• Add tests covering supervisor routing and agent handoffs.

Testing

• Tests pass locally
• Ruff checks pass
• Documentation updated, if applicable

Checklist

• My changes are focused and relevant to this pull request.
• I have added or updated tests where appropriate.
• I have reviewed my changes for unrelated modifications.
• I have updated documentation where necessary.

[Kaap10]

Thanks for working on this @tikhandesanket. While the goal of introducing multi-agent primitives from #289 is great, the current implementation consists of placeholder abstractions that don't yet fulfill the requirements of the issue:

1. Supervisor does not route requests:
   In src/dynavec/agents/supervisor.py, Supervisor.run() runs every agent sequentially in a list comprehension ([agent.run(goal, state=state) for agent in self.agents]). A supervisor needs routing logic (e.g., using an LLM or router prompt) to determine which named specialist agent to delegate to based on the user's request, rather than executing all agents for every query.

2. Handoff is an identity function:
   In src/dynavec/agents/handoff.py, Handoff.__call__ is currently return state. A handoff mechanism should actively transfer execution control and conversation/context between agents (e.g., as a callable tool or graph transition).

3. ReActAgent does not use state and breaks async parity:
   In src/dynavec/agents/react.py, state: AgentState | None = None was added to run(), but it is never read, modified, or incorporated into messages/prompts. Additionally, arun() was not updated to accept state, breaking parity between sync and async execution.

4. Missing scope from #289:
   The issue requires routing to named agents, control + context handoffs, and sub-agents runnable as nodes/sub-graphs.

Please revisit the architecture so that the supervisor performs actual task routing and handoffs transfer execution control. We can't merge placeholder primitives into the public API.

[tikhandesanket]

Thanks for raising this, @Kaap10 I think the key architectural point is not “must live in dynaflow vs dynavec,” but “must remain decoupled from concrete retrieval/memory implementations.”

I agree with the intent of separating orchestration from retrieval. The supervisor, handoff, and workflow state are runtime/workflow concerns, and they should not directly depend on dynavec-specific retrieval internals like vector search, BM25, or embeddings.

At the same time, I don’t think it is inherently wrong to introduce these as generic primitives in the current package as long as they are:

interface-driven
state-agnostic
not coupled to dynavec memory implementation details
designed so agents can consume dynavec as a capability rather than embed retrieval logic into the supervisor itself
So the correct boundary is:

dynavec provides memory/retrieval capabilities
dynaflow/runtime owns orchestration and state transitions
agents may integrate with dynavec through interfaces, without the supervisor itself depending on retrieval internals
If this PR keeps the supervisor/handoff/state generic and capability-based, then it is aligned with the architecture. If we start embedding retrieval-specific concerns directly into those primitives, then we should refactor that coupling out.

That’s the distinction I’d like us to preserve here.

cc- @codeforstartups
Also check #342 for my next architecture changes

[Kaap10]

Hi @tikhandesanket, thanks for following up.

To be completely clear: the review feedback was not about coupling to retrieval or memory backends. We fully agree that orchestration should remain decoupled from storage and retrieval.

The concern is strictly about the actual code implementation in this PR and the contract defined in #289:

1. Supervisor has no routing logic:
   In src/dynavec/agents/supervisor.py:

   def run(self, goal: str, *, state: AgentState) -> list[AgentResult]:
       return [agent.run(goal, state=state) for agent in self.agents]

   This executes every registered agent in a sequential loop on every query. If a user registers 4 specialist agents, all 4 run every time. Moving routing to a "non-goal" in feat(dynaflow): introduce multi-agent supervisor and handoff primitives #342 changes the definition of Multi-agent: supervisor, handoffs & sub-agents #289 ("supervisor that routes tasks to named agents"). Sequential execution over shared state is already handled by AgentGraph (shipped in feat(agents): add dynaflow graph orchestration engine and control flow (#277, #278) #344); calling a sequential loop a "Supervisor" is misleading to end users.

2. Handoff is an identity function:
   In src/dynavec/agents/handoff.py:

   def __call__(self, state: AgentState) -> AgentState:
       return state

   Returning the input state verbatim is a no-op identity function. A handoff primitive needs to actively transfer execution control or manage conversation history between agents.

3. Dead code in ReActAgent:
   In src/dynavec/agents/react.py, state: AgentState | None = None is accepted in run(), but is never read, modified, or passed into prompts. Meanwhile, arun() does not even have the parameter.

We want to keep PRs focused and decoupled, but we cannot merge placeholder stubs that don't perform the responsibilities they advertise.

Let's either:

• Implement actual task routing in Supervisor (whether via a lightweight router function, callable predicate, or model) and real control-transfer in Handoff.
• Or pause this PR until the design in feat(dynaflow): introduce multi-agent supervisor and handoff primitives #342 is fleshed out into functional primitives rather than placeholder classes.

[tikhandesanket]

@Kaap10 Thanks for the clarification. I understand the issues now. The current Supervisor runs all agents instead of selecting the right one, Handoff doesn't properly transfer control, and ReActAgent.run() doesn't use the state parameter.

I'll review the existing AgentGraph design and state handling before making changes. I'll align the implementation with #289, add tests for agent selection, handoff, and state preservation, and ensure the solution fits the agreed architecture without duplicating existing functionality.