Python: [Bug]: Declarative agent: Adding `outputSchema` to agent YAML produces incorrect output

[hapiiiiGit]

Description

When outputSchema is added to the declarative agent YAML,
the model output does not conform to the schema.

Agent YAML (outputSchema section)

outputSchema:
  type: object
  properties:
    answer:
      type: string
      description: The answer to the user's question.

Without outputSchema (correct behavior)
The model returns valid Python code as expected:

import math

def triangle_area(a, b, c):
    '''
    Given the lengths of the three sides of a triangle. Return the area of
    the triangle rounded to 2 decimal points if the three sides form a valid triangle. 
    Otherwise return -1
    Three sides make a valid triangle when the sum of any two sides is greater 
    than the third side.
    Example:
    triangle_area(3, 4, 5) == 6.00
    triangle_area(1, 2, 10) == -1
    '''
    if a + b > c and a + c > b and b + c > a:
        # Calculate the semi-perimeter
        s = (a + b + c) / 2
        # Calculate the area using Heron's formula
        area = math.sqrt(s * (s - a) * (s - b) * (s - c))
        return round(area, 2)
    else:
        return -1

With outputSchema (incorrect behavior)
The model ignores the task and returns an arbitrary JSON structure:

{
  "name": "triangle_area",
  "parameters": [
    {"name": "a", "type": "float"},
    ...
  ]
}

Code Sample

kind: Prompt
name: MinimalRelayAgent
displayName: Minimal Relay Agent
description: Python coding assistant with local tools
instructions: "You are a Python coding assistant. Your task is to complete the following\
  \ Python code from the HumanEval benchmark.\nGive concise, evidence-aware answers.\n\
  Note:\n  1. Output only final valid Python code. The final answer must be executable\
  \ Python code.\n  2. Do not explain your reasoning or include prose in the final\
  \ answer.\n"
model:
  id: ${GEMINI_MODEL}
  provider: Gemini
  apiType: Chat
  connection:
    kind: key
    apiKey: ${GEMINI_API_KEY}
  options:
    temperature: 0.1
    maxOutputTokens: 4000
    chatToolMode: none
outputSchema:
  type: object
  properties:
    answer:
      type: string
      description: The answer to the user's question.


tools:
  - kind: function
    name: calculator
    description: Evaluate a safe arithmetic expression.
    bindings:
      - name: calculator

  - kind: function
    name: code_linter
    description: Run lightweight static analysis on Python code or a workspace-relative Python file.
    bindings:
      - name: code_linter

  - kind: function
    name: python_executor
    description: Execute Python code in a short-lived subprocess.
    bindings:
      - name: python_executor

Error Messages / Stack Traces

**With `outputSchema`** (incorrect behavior)
The model ignores the task and returns an arbitrary JSON structure:

{
  "name": "triangle_area",
  "parameters": [
    {"name": "a", "type": "float"},
    ...
  ]
}

gemini input

{
  "model": "models/gemini-2.5-pro",
  "contents": [
    {
      "parts": [
        {
          "text": "\ndef triangle_area(a, b, c):\n    '''\n    Given the lengths of the three sides of a triangle. Return the area of\n    the triangle rounded to 2 decimal points if the three sides form a valid triangle. \n    Otherwise return -1\n    Three sides make a valid triangle when the sum of any two sides is greater \n    than the third side.\n    Example:\n    triangle_area(3, 4, 5) == 6.00\n    triangle_area(1, 2, 10) == -1\n    '''\n"
        }
      ],
      "role": "user"
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 4000,
    "temperature": 0.1,
    "responseMimeType": "application/json"
  },
  "systemInstruction": {
    "parts": [
      {
        "text": "You are a Python coding assistant. Your task is to complete the following Python code from the HumanEval benchmark.\nGive concise, evidence-aware answers.\nNote:\n  1. Output only final valid Python code. The final answer must be executable Python code.\n  2. Do not explain your reasoning or include prose in the final answer.\n"
      }
    ],
    "role": "user"
  },
  "tools": [
    {
      "functionDeclarations": [
        {
          "name": "calculator",
          "description": "Evaluate a safe arithmetic expression.",
          "parameters": {
            "type": "OBJECT",
            "properties": {
              "expression": {
                "type": "STRING",
                "description": "Arithmetic expression, for example: sqrt(16) + 2 ** 3."
              }
            },
            "required": [
              "expression"
            ]
          },
          "behavior": "UNSPECIFIED"
        },
        {
          "name": "code_linter",
          "description": "Run lightweight static analysis on Python code or a workspace-relative Python file.",
          "parameters": {
            "type": "OBJECT",
            "properties": {
              "code": {
                "type": "STRING",
                "description": "Python source code to analyze."
              },
              "file_path": {
                "type": "STRING",
                "description": "Workspace-relative Python file path to analyze when code is not provided."
              }
            }
          },
          "behavior": "UNSPECIFIED"
        },
        {
          "name": "python_executor",
          "description": "Execute Python code in a short-lived subprocess.",
          "parameters": {
            "type": "OBJECT",
            "properties": {
              "timeout_seconds": {
                "type": "INTEGER",
                "description": "Maximum runtime in seconds. Values are clamped between 1 and 30."
              },
              "code": {
                "type": "STRING",
                "description": "Python code to execute."
              }
            },
            "required": [
              "code"
            ]
          },
          "behavior": "UNSPECIFIED"
        },
        {
          "name": "read_file",
          "description": "Read a UTF-8 text file from the workspace.",
          "parameters": {
            "type": "OBJECT",
            "properties": {
              "path": {
                "type": "STRING",
                "description": "Workspace-relative path to read."
              },
              "max_chars": {
                "type": "INTEGER",
                "description": "Maximum number of characters to return. Clamped between 1 and 200000."
              }
            },
            "required": [
              "path"
            ]
          },
          "behavior": "UNSPECIFIED"
        },
        {
          "name": "write_file",
          "description": "Write UTF-8 text to a workspace file.",
          "parameters": {
            "type": "OBJECT",
            "properties": {
              "content": {
                "type": "STRING",
                "description": "Text content to write."
              },
              "append": {
                "type": "BOOLEAN",
                "description": "If true, append to the file instead of replacing it."
              },
              "path": {
                "type": "STRING",
                "description": "Workspace-relative path to create or update."
              }
            },
            "required": [
              "path",
              "content"
            ]
          },
          "behavior": "UNSPECIFIED"
        },
        {
          "name": "web_search",
          "description": "Search the web with DuckDuckGo HTML results.",
          "parameters": {
            "type": "OBJECT",
            "properties": {
              "query": {
                "type": "STRING",
                "description": "Search query."
              },
              "max_results": {
                "type": "INTEGER",
                "description": "Maximum number of results. Values are clamped between 1 and 10."
              }
            },
            "required": [
              "query"
            ]
          },
          "behavior": "UNSPECIFIED"
        }
      ]
    }
  ]
}

Package Versions

agent-framework 1.3.0 agent-framework-gemini 1.0.0a260514

Python Version

Python 3.14.4

Additional Context

No response

[github-actions]

🤖 Automated triage reproduction notes (agent-authored — trust but verify)

Agent analysis

Repro: GeminiChatClient._build_config() in python/packages/gemini/agent_framework_gemini/_chat_client.py (lines 750-753) fails to forward the JSON schema when options["response_format"] is a plain dict rather than a Pydantic model. The declarative loader always sets response_format (not response_schema) via _loader.py:464. Minimal repro: call client.get_response with options={"response_format": {"type": "object", "properties": {...}} and assert config.response_schema is not None.

• Failing test: python/packages/gemini/tests/test_issue_5888_output_schema.py
• Files examined: python/packages/gemini/agent_framework_gemini/_chat_client.py, python/packages/declarative/agent_framework_declarative/_loader.py, python/packages/declarative/agent_framework_declarative/_models.py, python/packages/gemini/tests/test_gemini_client.py
• Tests run: python/packages/gemini/tests/test_issue_5888_output_schema.py::test_response_format_dict_schema_forwarded_to_gemini
• Reported version: 1.0a260514
• Current version: 1.0a260514