Skip to content

fix(response): don't use a standard-library type's docstring as the schema description - #3707

Open
BichengWang wants to merge 1 commit into
ag2ai:mainfrom
BichengWang:fix/response-schema-builtin-docstring
Open

BichengWang wants to merge 1 commit into
ag2ai:mainfrom
BichengWang:fix/response-schema-builtin-docstring

Conversation

@BichengWang

Copy link
Copy Markdown
Contributor

Why are these changes needed?

ResponseSchema falls back to the type's __doc__ when no description is given. For standard-library types that docstring describes the type, not the response, and it is sent to the provider as the schema description:

from ag2.response import ResponseSchema
from ag2.config.openai.mappers import response_proto_to_schema

response_proto_to_schema(ResponseSchema(int))["json_schema"]["description"]
# 'int([x]) -> integer\nint(x, base=10) -> integer\n\nConvert a number or string to an integer, ...'

The same happens for bool, float, list[str], dict[str, int], set[int], datetime.date, Decimal, UUID, and unions (int | str yields "Represent a union type\n\nE.g. for int | str"). The OpenAI, Bedrock, DashScope and Mistral mappers all forward response.description, so every request with such a response_schema carries this text.

This change reads the docstring only when the type is not defined in the standard library. User-defined models, dataclasses, TypedDicts and enums behave as before, and an explicit description= still wins.

Two existing tests asserted the leaked docstring ("description": type_.__doc__ for int/float/bool in the OpenAI and DashScope mapper tests); they now assert the key is absent.

Related issue number

None.

Checks

  • I've included any doc changes needed for https://docs.ag2.ai/. (no doc change needed)
  • I've added tests (if relevant) corresponding to the changes introduced in this PR.
  • I've made sure all auto checks have passed. (to tick after CI runs)

AI assistance

  • I understand the changes in this PR and can explain them in my own words.
  • I have verified that the PR description accurately reflects the actual diff.
  • If AI assistance was used, I reviewed, tested, and validated the generated code/text before submitting.

Validation run (offline): new tests in test/response/test_schema.py fail before the fix (6 failed) and pass after; pytest test/response test/config test/providers test/test_usage.py test/agent -> 1983 passed, 365 skipped, 1 xfailed (test_gemini_integration.py ignored: needs redis, not installed); ruff check and ruff format --check clean; mypy==2.4.0 ag2/response/schema.py test/response/test_schema.py -> no issues.

@github-actions github-actions Bot added area:core Agent runtime core: ag2/*.py, ag2/events, ag2/response, ag2/streams area:providers LLM provider clients and mappers (ag2/config) labels Nov 21, 2026
@codecov

codecov Bot commented Nov 21, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

Files with missing lines Coverage Δ
ag2/response/schema.py 100.00% <100.00%> (ø)

... and 2 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:core Agent runtime core: ag2/*.py, ag2/events, ag2/response, ag2/streams area:providers LLM provider clients and mappers (ag2/config)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant