[Bug] Custom role maps

[bet0x]

Description

As it stands, using the OpenAI library with OpenAI-like endpoints will trigger an error related to the unsupported "developer" role. Since most models use "system" for roles, we should allow custom role mappings to avoid such errors.

Steps to Reproduce

1. Configure 03_agent_with_knowledge.py to use a different base url and model.
2. Execute:

(agno) (agno-env) alberto@barrahome:~/Projects/agno$ python cookbook/getting_started/03_agent_with_knowledge.py
INFO Loading knowledge base                                                                                                                                                         
INFO Reading: .............                                                                   
INFO Skipped 2 existing/duplicate documents.                                                                                                                                        
INFO Added 0 documents to knowledge base                                                                                                                                            
ERROR    API status error from OpenAI API: Error code: 400 - {'object': 'error', 'message': '1 validation error for ChatCompletionRequest\nmessages.0\n  Input tag \'developer\'    
         found using \'role\' does not match any of the expected tags: <Roles.system: \'system\'>, <Roles.user: \'user\'>, <Roles.assistant: \'assistant\'>, <Roles.tool: \'tool\'> 
         [type=union_tag_invalid, input_value={\'content\': "<instruction...>", \'role\': \'developer\'}, input_type=dict]\n    For further information visit                       
         https://errors.pydantic.dev/2.10/v/union_tag_invalid', 'type': 'BadRequestError', 'param': None, 'code': 400}                                                              
▰▰▱▱▱▱▱ Thinking...

Agent Configuration (if applicable)

    model=OpenAIChat(
        id="mistralai/Mistral-Small-24B-Instruct-2501", 
        base_url="https://........../v1", 
        api_key="........"
    ),

    embedder=OpenAIEmbedder(
        id="mixedbread-ai/mxbai-embed-large-v1",
        base_url="https://......",
        api_key=".........."
    ),
` ``

### Expected Behavior

The agent to run.         

### Actual Behavior

Crashes

### Screenshots or Logs (if applicable)

_No response_

### Environment

```markdown
OS: Ubuntu 24.04 noble
 Kernel: x86_64 Linux 6.9.12-060912-generic
 Shell: bash
 Disk: 863G / 1.8T (50%)
 CPU: AMD Ryzen 9 7900X 12-Core @ 24x 5.733GHz
 GPU: NVIDIA RTX A6000, NVIDIA GeForce RTX 3060
 RAM: 14195MiB / 128408MiB

Possible Solutions (optional)

Implement a custom role if not present then fallback to default, IE:

libs/agno/agno/models/openai/chat.py
Replace role_map with something like:

    default_role_map = {
        "system": "developer",
        "user": "user",
        "assistant": "assistant",
        "tool": "tool",
        "model": "assistant",
    }

Then on the _format_message we implement the following:

role_mapping = self.role_map if self.role_map is not None else self.default_role_map

Then when we do the call:

agent = Agent(
    model=OpenAIChat(
        id="mistralai/Mistral-Small-24B-Instruct-2501", 
        base_url="https://...../v1", 
        api_key="......",

        role_map={
            "system": "system",      # Maps internal "system" role to API's "system" role
            "user": "user",          # Maps internal "user" role to API's "user" role
            "assistant": "assistant", # Maps internal "assistant" role to API's "assistant" role
            "tool": "tool",          # Maps internal "tool" role to API's "tool" role
            "model": "assistant",    # Maps internal "model" role to API's "assistant" role
            "developer": "system",   # Maps "developer" role to "system" role in the API
            "expert": "assistant"    # Maps "expert" role to "assistant" role in the API
        }
    ),

Additional Context

No response

[linear]

SUPPORT-238 [Bug] Custom role maps

[manuhortet]

Hey @bet0x, thank you for reporting this. You are right and your proposed solution is great!

I opened a PR fixing this: #3355. We will try to release it asap.

Thanks again for putting in the time!

[dirkbrnd]

This was released with 1.5.5!