Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

function_tool on a callable object uses an inherited or generated class docstring as the tool description

Aperta
  • Qualcosa non va?
#5,443 2 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@Narendra02053 ci sta già lavorando.

Dal 27/10/2026.

Valutazione

Difficoltà
3/5
Tempo stimato
1-2 giorni
Idoneità per principianti
58/100
Tipo di issue
Bug
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
python
Ambito
ai, backend-api-design

Direzione di ricerca

Start with _normalize_function_tool_callable in src/agents/tool.py and generate_func_documentation in src/agents/function_schema.py; inspect how both obtain class docstrings and review test_callable_object_uses_call_docstring_when_class_docstring_missing in tests/test_function_tool_decorator.py. Add regression coverage for inherited stdlib and generated dataclass or NamedTuple docstrings, plus documented user base classes. Done when callable tool descriptions and summaries use the intended __call__ or user-written class documentation across those cases.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Please read this first
  • Have you read the docs? Yes
  • Have you searched for related issues? Yes. Callable-object tools and _normalize_function_tool_callable came from #3949. I didn't find anything about where a callable tool's class docstring comes from.
Describe the bug

For a callable object, _normalize_function_tool_callable reads the class docstring with inspect.getdoc(type(func)) (tool.py#L2609). When the class has no docstring of its own, inspect.getdoc falls back to the first base class that has one, and @dataclass and NamedTuple store generated text as __doc__. That text then takes priority over the __call__ docstring, so the description sent to the model is wrong:

  • a tool class whose undocumented abstract base derives from ABC gets the stdlib text "Helper class that provides a standard way to create an ABC using inheritance." (an undocumented typing.Generic or typing.Protocol base does the same with those classes' docstrings)
  • a @dataclass gets its constructor signature, including default values such as an internal base URL
  • a NamedTuple gets 'NamedTupleLookup(region,)'

A plain class with only a __call__ docstring works, which is what test_callable_object_uses_call_docstring_when_class_docstring_missing in tests/test_function_tool_decorator.py covers.

Debug information
  • Agents SDK version: 0.24.0, and current main (b040da59)
  • Related library versions: none
  • Python version: 3.12.7, plus 3.10.4 and 3.14.6 with the 0.24.0 wheel, same output
  • Operating system: macOS 26.6.2
  • Model and model provider: none needed, the description is wrong before any request is sent
  • Does the issue reproduce with the latest Agents SDK release? Yes
  • Does the issue occur consistently or intermittently? Consistently
WeatherLookup     'Helper class that provides a standard way to create an ABC using\ninheritance.'
DataclassLookup   "DataclassLookup(base_url: str = 'https://weather.internal.example', units: str = 'metric')"
NamedTupleLookup  'NamedTupleLookup(region,)'
Configured        'Look up the weather.'
Repro steps
from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import NamedTuple

from agents import function_tool


class WeatherTool(ABC):
    @abstractmethod
    async def __call__(self, city: str) -> str: ...


class WeatherLookup(WeatherTool):
    async def __call__(self, city: str) -> str:
        """Return the current weather for a city."""
        return f"sunny in {city}"


@dataclass
class DataclassLookup:
    base_url: str = "https://weather.internal.example"
    units: str = "metric"

    async def __call__(self, city: str) -> str:
        """Return the current weather for a city."""
        return f"sunny in {city}"


class NamedTupleLookup(NamedTuple):
    region: str = "us-east-1"

    async def __call__(self, city: str) -> str:
        """Return the current weather for a city."""
        return f"sunny in {city}"


class DocumentedBase:
    """Look up the weather.

    Args:
        city: The city to look up.
    """

    async def __call__(self, city: str) -> str:
        return f"sunny in {city}"


class Configured(DocumentedBase):
    pass


for obj in (WeatherLookup(), DataclassLookup(), NamedTupleLookup(), Configured()):
    print(f"{type(obj).__name__:17} {function_tool(obj).description!r}")
Expected behavior

The first three get 'Return the current weather for a city.'. The docstrings that stdlib bases like ABC, Generic and Protocol carry, and the text @dataclass and NamedTuple generate, weren't written for the tool and shouldn't become its description. Docstrings from the user's own classes should keep working as they do today, as Configured shows.

Suggested fix

Keep finding the class docstring through the MRO the way inspect.getdoc does, but skip two kinds of text: the docstrings of stdlib bases such as abc.ABC, typing.Generic and typing.Protocol, and text that @dataclass or NamedTuple generated. Generated text sits in the class's own __dict__ next to __dataclass_fields__ or _fields, and it starts with ClassName( (or is just ClassName when dataclasses can't build a signature on 3.11+), so a prefix check is enough. Rebuilding the string with inspect.signature(cls) doesn't reliably match on 3.14, which renders annotations with annotation_format=FORWARDREF. Docstrings from the user's own base classes and mixins would keep being used, as today.

The class summary needs the same source. When both docstrings exist, the description comes from generate_func_documentation(type(func), ...) at L2613, which calls inspect.getdoc again (function_schema.py#L260). For example, a @dataclass subclass of a documented base whose __call__ has a docstring gets "ConfiguredDataclass(units: str = 'metric')" as its description, and changing only L2609 wouldn't fix that.

Lingua principale
Python
Stelle
30.4k
Fork
4.9k
Merge medio
15h 42m
PR unite (30g)
124

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di openai/openai-agents-python

Tutte le issue di openai/openai-agents-python

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.