8000 Azure Foundry v2 (AzureAIClient) - Invalid Payload Error During Workflow Handoffs with HandoffBuilder · Issue #3097 · microsoft/agent-framework · GitHub
[go: up one dir, main page]
Skip to content

Azure Foundry v2 (AzureAIClient) - Invalid Payload Error During Workflow Handoffs with HandoffBuilder #3097

New issue
New issue
Closed
Bug
Closed
Azure Foundry v2 (AzureAIClient) - Invalid Payload Error During Workflow Handoffs with HandoffBuilder#3097
Bug
Assignees
TaoChenOSU
Labels
bugSomething isn't workingpythonv1.0Features being tracked for the version 1.0 GAworkflowsRelated to Workflows in agent-framework
@amit12cool

Description

@amit12cool
amit12cool
opened on Jan 6, 2026

Description

When using AzureAIClient (Azure Foundry v2 with Responses API) with HandoffBuilder workflows, the framework fails with a 400 Invalid Payload error when passing conversation history between agents during handoffs. The error occurs specifically when an agent with text-only assistant 8000 messages hands off to another agent.

Environment

  • Framework Version: agent-framework-python/1.0.0b251223
  • Azure AI Projects SDK: azsdk-python-ai-projects/2.0.0b2
  • Python Version: 3.13.11
  • Client Type: AzureAIClient (v2 Responses API)
  • Region: Sweden Central
  • Model: gpt-4.1-mini
  • API Version: 2025-11-15-preview

Steps to Reproduce

  1. Create multiple declarative agents from YAML using AgentFactory.create_agent_from_yaml()
  2. Initialize each agent with separate AzureAIClient instances with agent_name parameter:
chat_client = AzureAIClient(
    endpoint=azure_project_endpoint,
    model=azure_model_deployment,
    credential=AzureCliCredential(),
    agent_name="AgentName",  # Bind to specific agent
    http_client=httpx.AsyncClient()
)
agent = AgentFactory.create_agent_from_yaml(yaml_content, chat_client=chat_client)
  1. Build a workflow with HandoffBuilder:
workflow = (
    HandoffBuilder(
        name="multi_agent_workflow",
        participants=[master_agent, diagnostic_agent, correction_agent, healthcheck_agent]
    )
    .set_coordinator(master_agent)
    .add_handoff(master_agent, [diagnostic_agent, healthcheck_agent])
    .with_termination_condition(lambda conv: len(conv) >= 15)
    .with_interaction_mode("autonomous", autonomous_turn_limit=10)
    .build()
    .as_agent()
)
  1. Send a user message that triggers a handoff with text content
  2. First agent responds with text + handoff tool call
  3. Framework attempts to pass conversation history to second agent

Expected Behavior

The workflow should successfully pass conversation history between agents, with messages properly formatted for Azure v2 Responses API:

{
  "input": [{
    "type": "message",
    "role": "assistant",
    "content": [{
      "type": "text",
      "text": "...",
      "annotations": []
    }]
  }]
}

Actual Behavior

Error: HTTP 400 - Invalid payload from Azure Responses API

{
  "error": {
    "code": "invalid_payload",
    "message": "Invalid payload",
    "type": "invalid_request_error",
    "details": [
      {
        "code": "ValidationError",
        "message": "type: Value is \"array\" but should be \"string\"",
        "param": "/input",
        "type": "error"
      },
      {
        "code": "ValidationError",
        "message": "required: Required properties [\"type\"] are not present",
        "param": "/input/1",
        "type": "error"
      },
      {
        "code": "ValidationError",
        "message": "type: Value is \"array\" but should be \"string\"",
        "param": "/input/1/content",
        "type": "error"
      },
      {
        "code": "ValidationError",
        "message": "required: Required properties [\"annotations\"] are not present",
        "param": "/input/1/content/0",
        "type": "error"
      }
    ]
  }
}

Logs Showing the Issue

2026-01-06 15:18:37,002 - agent_framework._workflows._runner - INFO - Starting superstep 3
2026-01-06 15:18:37,003 - agent_framework._workflows._handoff - INFO - Handoff detected: MasterAgent -> HealthCheckAgent. Routing control to specialist 'HealthCheckAgent'.
2026-01-06 15:18:38,886 - azure.core.pipeline.policies.http_logging_policy - INFO - Request URL: 'https://my-project.services.ai.azure.com/api/projects/my-ai-project/agents/HealthCheckAgent/versions?api-version=REDACTED'
2026-01-06 15:18:42,105 - httpx - INFO - HTTP Request: POST https://my-project.services.ai.azure.com/api/projects/my-ai-project/openai/responses?api-version=2025-11-15-preview "HTTP/1.1 400 Bad Request"
2026-01-06 15:18:42,192 - agent_framework_devui._executor - ERROR - Error in agent execution: <class 'agent_framework_azure_ai._client.AzureAIClient'> service failed to complete the prompt: Error code: 400 - {...}

Root Cause Analysis

The framework's workflow/handoff implementation appears to incorrectly serialize conversation history when calling Azure v2's Responses API. Specifically:

  1. ✅ First agent execution works: Initial message and tool calls are correctly formatted
  2. ✅ Handoff detection works: Framework correctly identifies handoff and routes to next agent
  3. ❌ Second agent initialization fails: When passing conversation history containing assistant text messages, the payload format is invalid

The issue appears to be in how the framework converts internal message representations to Azure v2's strict Responses API schema during handoffs.

What Works

  • ✅ Single agent execution with AzureAIClient
  • ✅ Direct tool calls (non-handoff)
  • ✅ Handoff tool registration and invocation
  • ✅ Initial handoff from Agent A → Agent B succeeds
  • ✅ Same workflow with AzureAIAgentClient (v1) works fine

Additional Context

Agent Configuration (YAML)

kind: Prompt
name: HealthCheckAgent
model:
  options:
    temperature: 0.9
    topP: 0.95
tools:
  - kind: mcp
    serverName: DiagnosticServer
    serverDescription: Diagnostic tools
    connection:
      kind: AnonymousConnection
      endpoint: https://mcp-server.example.com/mcp

Conversation Flow Before Error

  1. User: "camera not working"
  2. Master Agent:
    • Text: "🔧 About to execute: Comprehensive Device Health Check..."
    • Tool call: handoff_to_healthcheckagent
  3. Handoff occurs → Health Check Agent receives malformed payload

Workaround Attempted

Setting agent_name parameter on each AzureAIClient fixed tool registration issues but did not resolve the payload formatting problem during handoffs.

Impact

This bug prevents using Azure Foundry v2 (AzureAIClient) with multi-agent workflows that use HandoffBuilder, forcing users to either:

  1. Use v1 API (AzureAIAgentClient) which lacks modern features
  2. Avoid workflows and implement manual agent coordination
  3. Use single-agent architectures only

Suggested Fix

The framework should ensure that when serializing conversation history for Azure v2 Responses API calls during handoffs, all messages conform to the required schema:

  • Messages must have type property
  • Content arrays must include annotations property
  • Input should be properly structured as message objects, not raw arrays

Related Issues

This may be related to Azure v2's stricter schema validation compared to v1, and appears specific to workflow/handoff scenarios rather than direct agent invocation.

Code Sample



Additional Context


No response
Metadata
Metadata
Assignees
Labels
bugSomething isn't workingpythonv1.0Features being tracked for the version 1.0 GAworkflowsRelated to Workflows in agent-framework
Type
Bug
Projects
Agent Framework
Status
Done
Milestone
No milestone
Relationships
None yet
Development
No branches or pull requests
Issue actions
    
    
    




  
    

    

    
    
  
    

  
    

          



    




  

    

    

    





    
    
    
    
    
    
  



0