Skip to content

ModelClientV2

autogen.llm_clients.client_v2.ModelClientV2 #

Bases: Protocol

Next-generation client interface with rich unified responses.

This protocol extends the current ModelClient interface to support: - Rich content blocks (reasoning, thinking, citations, etc.) - Provider-agnostic response format - Forward compatibility with unknown content types - Backward compatibility via create_v1_compatible()

Design Philosophy: - Returns UnifiedResponse with typed content blocks for direct access - Users should access content via response properties (text, reasoning, etc.) - No message_retrieval() method - use response.text or response.messages directly - For ModelClient compatibility, implementations should inherit ModelClient

Migration Path: 1. Implement create() to return UnifiedResponse 2. Implement create_v1_compatible() for backward compatibility 3. Gradually migrate agents to use UnifiedResponse directly 4. Eventually deprecate v1 compatibility layer

Example Implementation

class OpenAIClientV2: def create(self, params: dict[str, Any]) -> UnifiedResponse: # Call OpenAI API raw_response = openai.chat.completions.create(**params)

    # Transform to UnifiedResponse with rich content blocks
    return self._to_unified_response(raw_response)

def create_v1_compatible(self, params: dict[str, Any]) -> ChatCompletionExtended:
    # Get rich response
    response = self.create(params)

    # Convert to legacy format
    return self._to_v1(response)
Example Usage

client = OpenAIClientV2() response = client.create({"model": "o1-preview", "messages": [...]})

Direct access to rich content#

text = response.text # Get all text content reasoning = response.reasoning # Get reasoning blocks citations = response.get_content_by_type("citation") # Get specific types

RESPONSE_USAGE_KEYS class-attribute instance-attribute #

RESPONSE_USAGE_KEYS = ['prompt_tokens', 'completion_tokens', 'total_tokens', 'cost', 'model']

create #

create(params)

Create a completion and return unified response.

PARAMETER DESCRIPTION
params

Request parameters (messages, model, temperature, etc.)

TYPE: dict[str, Any]

RETURNS DESCRIPTION
UnifiedResponse

UnifiedResponse with rich content blocks preserving all provider features
Source code in autogen/llm_clients/client_v2.py 
67
68
69
70
71
72
73
74
75
76
def create(self, params: dict[str, Any]) -> UnifiedResponse:
    """Create a completion and return unified response.

    Args:
        params: Request parameters (messages, model, temperature, etc.)

    Returns:
        UnifiedResponse with rich content blocks preserving all provider features
    """
    ...

create_v1_compatible #

create_v1_compatible(params)

Backward compatible - returns ChatCompletionExtended. TODO Remove this method after migrating clients to V2.

This method provides backward compatibility during migration by: 1. Calling create() to get UnifiedResponse 2. Converting to ChatCompletionExtended format 3. Flattening rich content to legacy format

PARAMETER DESCRIPTION
params

Request parameters (same as create())

TYPE: dict[str, Any]

RETURNS DESCRIPTION
Any

ChatCompletionExtended for compatibility with existing agents
Note

This method may lose information (reasoning blocks, citations, etc.) when converting to the legacy format. Prefer create() for new code.

Source code in autogen/llm_clients/client_v2.py 
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
def create_v1_compatible(self, params: dict[str, Any]) -> Any:
    """Backward compatible - returns ChatCompletionExtended.
    TODO Remove this method after migrating clients to V2.

    This method provides backward compatibility during migration by:
    1. Calling create() to get UnifiedResponse
    2. Converting to ChatCompletionExtended format
    3. Flattening rich content to legacy format

    Args:
        params: Request parameters (same as create())

    Returns:
        ChatCompletionExtended for compatibility with existing agents

    Note:
        This method may lose information (reasoning blocks, citations, etc.)
        when converting to the legacy format. Prefer create() for new code.
    """
    ...

cost #

cost(response)

Calculate cost from response. TODO Move this method to private after migrating clients to V2.

PARAMETER DESCRIPTION
response

UnifiedResponse from create()

TYPE: UnifiedResponse

RETURNS DESCRIPTION
float

Cost in USD for the API call
Source code in autogen/llm_clients/client_v2.py 
 99
100
101
102
103
104
105
106
107
108
109
def cost(self, response: UnifiedResponse) -> float:
    """Calculate cost from response.
    TODO Move this method to private after migrating clients to V2.

    Args:
        response: UnifiedResponse from create()

    Returns:
        Cost in USD for the API call
    """
    ...

get_usage staticmethod #

get_usage(response)

Extract usage statistics from response. TODO Move this method to private after migrating clients to V2.

PARAMETER DESCRIPTION
response

UnifiedResponse from create()

TYPE: UnifiedResponse

RETURNS DESCRIPTION
dict[str, Any]

Dict with keys from RESPONSE_USAGE_KEYS
Source code in autogen/llm_clients/client_v2.py 
111
112
113
114
115
116
117
118
119
120
121
122
@staticmethod
def get_usage(response: UnifiedResponse) -> dict[str, Any]:
    """Extract usage statistics from response.
    TODO Move this method to private after migrating clients to V2.

    Args:
        response: UnifiedResponse from create()

    Returns:
        Dict with keys from RESPONSE_USAGE_KEYS
    """
    ...