Automatic tool output name generation fails with Generic types containing brackets

[lionpeloux]

Initial Checks

• I confirm that I'm using the latest version of Pydantic AI
• I confirm that I searched for my issue in https://github.com/pydantic/pydantic-ai/issues before opening this issue

Description

When using Generic types directly in output_type without wrapping them in ToolOutput, the automatic tool output name generation fails because the generated name contains brackets [], which violates Google's function naming requirements.

see : https://pydanticlogfire.slack.com/archives/C083V7PMHHA/p1758034303546309

Current Behavior

Using Generic types directly in output_type fails:

scan_agent_v2 = BaseAgent(
    name="scan-agent",
    model_ref=ModelRef.GEMINI_2_5_PRO,
    system_prompt=SYSTEM_PROMPT,
    output_type=[
        ScanSuccess[ElectricStorageWaterHeaterScanResult],  # ❌ Fails
        ScanFailure,
    ],
)

Error:

ModelHTTPError: status_code: 400
"Invalid function name. Must start with a letter or an underscore. Must be a-z, A-Z, 0-9, or contain underscores, dots and dashes, with a maximum length of 64."

Expected Behavior

Generic types should work seamlessly without requiring explicit ToolOutput wrapping.

Current Workaround

Explicitly wrap Generic types in ToolOutput with a custom name:

class ScanSuccess[T](ScanResponse):
    """Extraction réussie des données du scan."""
    result: T

class ScanFailure(ScanResponse):
    """Échec de l'extraction des données du scan."""
    message: str

scan_agent_v2 = BaseAgent(
    name="scan-agent",
    model_ref=ModelRef.GEMINI_2_5_PRO,
    system_prompt=SYSTEM_PROMPT,
    output_type=[
        ToolOutput(
            ScanSuccess[ElectricStorageWaterHeaterScanResult],
            name="scan_success",  # ✅ Works with explicit name
        ),
        ToolOutput(ScanFailure, name="scan_failure"),
    ],
)

Root Cause

The automatic name generation appears to include the Generic type parameters (e.g., ScanSuccess[ElectricStorageWaterHeaterScanResult]), resulting in function names with brackets that violate Google's function naming constraints.

Proposed Solution

The automatic name generation should sanitize Generic type names by:

1. Removing brackets from the class name (but keep type parameter)
2. Converting to a valid function name format (snake_case)
3. Ensuring compliance with provider naming requirements

Python, Pydantic AI & LLM client version

python 3.143
pydantic-ai >= 1.0.2
google/gemini-2.5-pro` via OpenRouter

[DouweM]

@lionpeloux Thanks for the report. We'll want to strip out unsupported characters after we add the object_def.name here:

pydantic-ai/pydantic_ai_slim/pydantic_ai/_output.py

Lines 946 to 949 in 8e652f0

	if name is None:
	name = default_name
	if multiple:
	name += f'_{object_def.name}'

I think it's safest to stick to [a-z0-9-_].

Would you be up for submitting a PR?

[lionpeloux]

Ok. Do you favor something more general :

safe_name = re.sub(r'[^a-z0-9-_]', '', object_def.name)

Or focused on the generic class issue with [] :

safe_name = object_def.name.replace('[', '').replace(']', '')

[lionpeloux]

from enum import StrEnum
from pydantic import BaseModel
from pydantic_ai import Agent
import os

os.environ['OPENAI_API_KEY'] = 'your-api-key-here'

class SuccessResponse[T](BaseModel):
    data: T | None = None
    """The data returned by the tool, conforming to the specified data schema."""
    
    message: str | None = None
    """An explicative message that tells in natural language what data was extracted."""

class FailureResponse(BaseModel):
    message: str
    """An explicative message that tells in natural language what went wrong."""


class City(StrEnum):
    PARIS = 'Paris'
    LONDON = 'London'
    TOKYO = 'Tokyo'
    NEW_YORK = 'New York'
    SYDNEY = 'Sydney'
    MELBOURNE = 'Melbourne'
    BEIJING = 'Beijing'



class CityData(BaseModel):
    city: City



agent = Agent(
    'openai:gpt-4.1',
    system_prompt="You're a city data expert you should return the data for the city that the user asks for.",
    output_type=[
        SuccessResponse[CityData],
        FailureResponse
    ],
)

for prompt in ['What is the capital of France?', 'What is the color of the banana?']:
    result = agent.run_sync(prompt)
    print(result.output.model_dump_json(indent=2))

{
  "data": {
    "city": "Paris"
  },
  "message": "The capital of France is Paris."
}
{
  "message": "I can only provide data related to the specified cities. Please ask about Paris, London, Tokyo, New York, Sydney, Melbourne, or Beijing."
}