Python: HandoffBuilder participants contract conflicts with runtime Agent-only enforcement

[moonbox3]

Description

HandoffBuilder.participants() accepts SupportsAgentRun by API contract, but build() fails unless each participant is specifically an Agent instance.

Current behavior:

• participants() type/docs allow SupportsAgentRun.
• HandoffAgentExecutor._prepare_agent_with_handoffs() enforces isinstance(agent, Agent) and raises TypeError.

Expected behavior:

• Either fully support SupportsAgentRun participants, or
• tighten public contract/docs/type hints at participants() to require Agent explicitly.

Code Sample

from agent_framework import AgentResponse, AgentSession, Message, Content, SupportsAgentRun
from agent_framework.orchestrations import HandoffBuilder

class MinimalSupportsAgentRun:
    def __init__(self, id, name):
        self.id = id
        self.name = name
        self.description = "d"

    async def run(self, messages=None, *, stream=False, session=None, **kwargs):
        return AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("ok")])])

    def create_session(self, **kwargs):
        return AgentSession()

    def get_session(self, *, service_session_id, **kwargs):
        return AgentSession(service_session_id=service_session_id)

a = MinimalSupportsAgentRun("a", "A")
b = MinimalSupportsAgentRun("b", "B")
print(isinstance(a, SupportsAgentRun))  # True

wf = (
    HandoffBuilder()
    .participants([a, b])
    .with_start_agent(a)
    .with_autonomous_mode()
    .build()  # raises TypeError today
)

Error Messages / Stack Traces

TypeError: Handoff can only be applied to Agent. Please ensure the agent is a Agent instance.

Package Versions

• agent-framework-core: 1.0.0rc2
• agent-framework-orchestrations: 1.0.0b260225
• Source commit tested: 02ba27493 (main)

Python Version

Python 3.13.5

Additional Context

Likely locations:

• packages/orchestrations/agent_framework_orchestrations/_handoff.py
  • HandoffBuilder.participants(...)
  • HandoffAgentExecutor._prepare_agent_with_handoffs(...)