Azure OpenAI compatibility: max_tokens not supported, needs max_completion_tokens

[mastreips]

Azure OpenAI compatibility: max_tokens not supported, needs max_completion_tokens

🐛 Bug Report

Description

When using fastagent (mcp-agent) with Azure OpenAI endpoints, the library sends the max_tokens parameter to the API. However, some Azure OpenAI deployments (particularly newer models like gpt-5-nano-v1) require max_completion_tokens instead of max_tokens, causing API requests to fail.

Error Message

openai.BadRequestError: Error code: 400 - {
  'error': {
    'message': "Unsupported parameter: 'max_tokens' is not supported with this model. Use 'max_completion_tokens' instead.",
    'type': 'invalid_request_error',
    'param': 'max_tokens',
    'code': 'unsupported_parameter'
  }
}

Environment

• fastagent version: (latest from pip as of 2025-11-09)
• Python version: 3.11
• Azure OpenAI endpoint: https://YOUR-RESOURCE.cognitiveservices.azure.com
• Azure API version: 2025-04-01-preview
• Model deployment: gpt-5-nano-v1 (Azure deployment name)
• Model string in config: azure.gpt-5-nano-v1

Configuration

# fastagent.config.azure.yaml
azure:
  api_key: "YOUR_AZURE_API_KEY"
  base_url: "https://YOUR-RESOURCE.cognitiveservices.azure.com"
  azure_deployment: "gpt-5-nano-v1"
  api_version: "2025-04-01-preview"

default_model: azure.gpt-5-nano-v1

# Note: Removing model_params entirely doesn't help - library still sends max_tokens

Steps to Reproduce

1. Configure fastagent with Azure OpenAI using the configuration above
2. Create an agent with or without RequestParams(maxTokens=...)
3. Run any query that triggers a completion
4. Error occurs at augmented_llm_openai.py:345 when calling chat.completions.create(**arguments)

Expected Behavior

The library should:

1. Detect when using Azure OpenAI (check if base_url contains .cognitiveservices.azure.com)
2. For Azure OpenAI endpoints, use max_completion_tokens instead of max_tokens
3. Allow both OpenAI and Azure OpenAI to work with the same configuration pattern

Current Workaround

• Using standard OpenAI endpoints (non-Azure) works fine
• Avoiding Azure OpenAI entirely

Proposed Solution

In mcp_agent/llm/providers/augmented_llm_openai.py, around line 345 in the _openai_completion method:

# Detect if using Azure OpenAI
is_azure = (
    hasattr(self, '_base_url') and 
    self._base_url and 
    'cognitiveservices.azure.com' in str(self._base_url)
)

# Use appropriate parameter name
if request_params and request_params.max_tokens:
    if is_azure:
        arguments["max_completion_tokens"] = request_params.max_tokens
    else:
        arguments["max_tokens"] = request_params.max_tokens

References

• OpenAI Python Issue #1724 - Similar Azure OpenAI parameter issues
• Crush Issue #1061 - Same error with Azure OpenAI
• Azure OpenAI API Documentation - Parameter differences

Additional Context

This affects users trying to:

• Use Azure OpenAI for enterprise/compliance reasons
• Take advantage of Azure OpenAI's specific model deployments
• Switch between OpenAI and Azure OpenAI based on cost/region

The library already handles Azure OpenAI authentication correctly using the azure config section, so adding parameter translation would complete the Azure support.

---

Impact: This blocks Azure OpenAI usage entirely for affected models. Users cannot work around it in configuration - the fix must be in the library code.

[evalstate]

Does Azure follow identical rules to OpenAI? I assume that sharing the logic on whether to use max_completion... would solve this?

[mastreips]

Does Azure follow identical rules to OpenAI? I assume that sharing the logic on whether to use max_completion... would solve this?

I'm using a different model for OpenAI direct (4o-mini). This issue is for 5-nano via Azure.