DataContent Class

Represents binary data content with an associated media type (also known as a MIME type).

Important

This is for binary data that is represented as a data URI, not for online resources.

Use UriContent for online resources.

Initializes a DataContent instance.

Important

This is for binary data that is represented as a data URI, not for online resources.

Use UriContent for online resources.

Constructor

DataContent()

Keyword-Only Parameters

Name	Description
uri	The URI of the data represented by this instance. Should be in the form: "data:{media_type};base64,{base64_data}". Default value: None
data	The binary data represented by this instance. The data is transformed into a base64-encoded data URI. Default value: None
media_type	The media type of the data. Default value: None
annotations	Optional annotations associated with the content. Default value: None
additional_properties	Optional additional properties associated with the content. Default value: None
raw_representation	Optional raw representation of the content. Default value: None
**kwargs	Any additional keyword arguments.

Examples


   from agent_framework import DataContent

   # Create from binary data
   image_data = b"raw image bytes"
   data_content = DataContent(data=image_data, media_type="image/png")

   # Create from data URI
   data_uri = "data:image/png;base64,iVBORw0KGgoAAAANS..."
   data_content = DataContent(uri=data_uri)

   # Check media type
   if data_content.has_top_level_media_type("image"):
       print("This is an image")

Methods

__init__	Initializes a DataContent instance. Important This is for binary data that is represented as a data URI, not for online resources. Use UriContent for online resources.
__new__
create_data_uri_from_base64	Create a data URI and media type from base64 image data.
detect_image_format_from_base64	Detect image format from base64 data by examining the binary header.
from_dict	Create an instance from a dictionary with optional dependency injection. This method reconstructs an object from its dictionary representation, automatically handling type conversion and dependency injection. It supports three patterns of dependency injection to handle different scenarios where external dependencies need to be provided at deserialization time.
from_json	Create an instance from a JSON string. This is a convenience method that parses the JSON string using `json.loads()` and then calls `from_dict()` to reconstruct the object. All dependency injection capabilities are available through the `dependencies` parameter.
get_data_bytes	Extracts and returns the binary data from the data URI.
get_data_bytes_as_str	Extracts and returns the base64-encoded data from the data URI.
has_top_level_media_type
to_dict	Convert the instance to a dictionary. Extracts additional_properties fields to the root level.
to_json	Convert the instance to a JSON string. This is a convenience method that calls `to_dict()` and then serializes the result using `json.dumps()`. All the same serialization rules apply as in `to_dict()`, including automatic exclusion of injectable dependencies and deep serialization of nested objects.

init

Initializes a DataContent instance.

Important

This is for binary data that is represented as a data URI, not for online resources.

Use UriContent for online resources.

__init__(*, uri: str, annotations: Sequence[CitationAnnotation | MutableMapping[str, Any]] | None = None, additional_properties: dict[str, Any] | None = None, raw_representation: Any | None = None, **kwargs: Any) -> None

Keyword-Only Parameters

Name	Description
uri	The URI of the data represented by this instance. Should be in the form: "data:{media_type};base64,{base64_data}". Default value: None
data	The binary data represented by this instance. The data is transformed into a base64-encoded data URI. Default value: None
media_type	The media type of the data. Default value: None
annotations	Optional annotations associated with the content. Default value: None
additional_properties	Optional additional properties associated with the content. Default value: None
raw_representation	Optional raw representation of the content. Default value: None
**kwargs	Any additional keyword arguments.

new

__new__(**kwargs)

create_data_uri_from_base64

Create a data URI and media type from base64 image data.

static create_data_uri_from_base64(image_base64: str) -> tuple[str, str]

Parameters

Name	Description
image_base64 Required	str Base64 encoded image data

Returns

Type	Description
tuple[str, str]	Tuple of (data_uri, media_type)

detect_image_format_from_base64

Detect image format from base64 data by examining the binary header.

static detect_image_format_from_base64(image_base64: str) -> str

Parameters

Name	Description
image_base64 Required	str Base64 encoded image data

Returns

Type	Description
str	Image format as string (png, jpeg, webp, gif) with png as fallback

from_dict

Create an instance from a dictionary with optional dependency injection.

This method reconstructs an object from its dictionary representation, automatically handling type conversion and dependency injection. It supports three patterns of dependency injection to handle different scenarios where external dependencies need to be provided at deserialization time.

from_dict()

Positional-Only Parameters

Name	Description
value Required

Parameters

Name	Description
value Required	MutableMapping[str, Any] The dictionary containing the instance data (positional-only). Must include a 'type' field matching the class type identifier.
dependencies Required	MutableMapping[str, Any] \| None

Keyword-Only Parameters

Name	Description
dependencies	A nested dictionary mapping type identifiers to their injectable dependencies. The structure varies based on injection pattern: Simple injection: `{"<type>": {"<parameter>": value}}` Dict parameter injection: `{"<type>": {"<dict-parameter>": {"<key>": value}}}` Instance-specific injection: `{"<type>": {"<field>:<value>": {"<parameter>": value}}}` Default value: None

Returns

Type	Description
<xref:agent_framework._serialization.TClass>	New instance of the class with injected dependencies.

Exceptions

Type	Description
ValueError	If the 'type' field in the data doesn't match the class type identifier.

Examples

Simple Client Injection - OpenAI client dependency injection:


   from agent_framework.openai import OpenAIChatClient
   from openai import AsyncOpenAI


   # OpenAI chat client requires an AsyncOpenAI client instance
   # The client is marked as INJECTABLE = {"client"} in OpenAIBase

   # Serialized data contains only the model configuration
   client_data = {
       "type": "open_ai_chat_client",
       "model_id": "gpt-4o-mini",
       # client is excluded from serialization
   }

   # Provide the OpenAI client during deserialization
   openai_client = AsyncOpenAI(api_key="your-api-key")
   dependencies = {"open_ai_chat_client": {"client": openai_client}}

   # The chat client is reconstructed with the OpenAI client injected
   chat_client = OpenAIChatClient.from_dict(client_data, dependencies=dependencies)
   # Now ready to make API calls with the injected client

Function Injection for Tools - AIFunction runtime dependency:


   from agent_framework import AIFunction
   from typing import Annotated


   # Define a function to be wrapped
   async def get_current_weather(location: Annotated[str, "The city name"]) -> str:
       # In real implementation, this would call a weather API
       return f"Current weather in {location}: 72°F and sunny"


   # AIFunction has INJECTABLE = {"func"}
   function_data = {
       "type": "ai_function",
       "name": "get_weather",
       "description": "Get current weather for a location",
       # func is excluded from serialization
   }

   # Inject the actual function implementation during deserialization
   dependencies = {"ai_function": {"func": get_current_weather}}

   # Reconstruct the AIFunction with the callable injected
   weather_func = AIFunction.from_dict(function_data, dependencies=dependencies)
   # The function is now callable and ready for agent use

Middleware Context Injection - Agent execution context:


   from agent_framework._middleware import AgentRunContext
   from agent_framework import BaseAgent

   # AgentRunContext has INJECTABLE = {"agent", "result"}
   context_data = {
       "type": "agent_run_context",
       "messages": [{"role": "user", "text": "Hello"}],
       "is_streaming": False,
       "metadata": {"session_id": "abc123"},
       # agent and result are excluded from serialization
   }

   # Inject agent and result during middleware processing
   my_agent = BaseAgent(name="test-agent")
   dependencies = {
       "agent_run_context": {
           "agent": my_agent,
           "result": None,  # Will be populated during execution
       }
   }

   # Reconstruct context with agent dependency for middleware chain
   context = AgentRunContext.from_dict(context_data, dependencies=dependencies)
   # Middleware can now access context.agent and process the execution

This injection system allows the agent framework to maintain clean separation between serializable configuration and runtime dependencies like API clients, functions, and execution contexts that cannot or should not be persisted.

from_json

Create an instance from a JSON string.

This is a convenience method that parses the JSON string using json.loads() and then calls from_dict() to reconstruct the object. All dependency injection capabilities are available through the dependencies parameter.

from_json()

Positional-Only Parameters

Name	Description
value Required

Parameters

Name	Description
value Required	str The JSON string containing the instance data (positional-only). Must be valid JSON that deserializes to a dictionary with a 'type' field.
dependencies Required	MutableMapping[str, Any] \| None

Keyword-Only Parameters

Name	Description
dependencies	A nested dictionary mapping type identifiers to their injectable dependencies. See from_dict for detailed structure and examples of the three injection patterns (simple, dict parameter, and instance-specific). Default value: None

Returns

Type	Description
<xref:agent_framework._serialization.TClass>	New instance of the class with any specified dependencies injected.

Exceptions

Type	Description
JSONDecodeError	If the JSON string is malformed.
ValueError	If the parsed data doesn't contain a valid 'type' field.

get_data_bytes

Extracts and returns the binary data from the data URI.

get_data_bytes() -> bytes

Returns

Type	Description
bytes	The binary data as bytes.

get_data_bytes_as_str

Extracts and returns the base64-encoded data from the data URI.

get_data_bytes_as_str() -> str

Returns

Type	Description
str	The binary data as str.

has_top_level_media_type

has_top_level_media_type(top_level_media_type: Literal['application', 'audio', 'image', 'text']) -> bool

Parameters

Name	Description
top_level_media_type Required	Literal['application', 'audio', 'image', 'text']

Returns

Type	Description
bool

to_dict

Convert the instance to a dictionary.

Extracts additional_properties fields to the root level.

to_dict(*, exclude: set[str] | None = None, exclude_none: bool = True) -> dict[str, Any]

Parameters

Name	Description
exclude Required	set[str] \| None
exclude_none Required	bool

Keyword-Only Parameters

Name	Description
exclude	Set of field names to exclude from serialization. Default value: None
exclude_none	Whether to exclude None values from the output. Defaults to True. Default value: True

Returns

Type	Description
dict[str, Any]	Dictionary representation of the instance.

to_json

Convert the instance to a JSON string.

This is a convenience method that calls to_dict() and then serializes the result using json.dumps(). All the same serialization rules apply as in to_dict(), including automatic exclusion of injectable dependencies and deep serialization of nested objects.

to_json(*, exclude: set[str] | None = None, exclude_none: bool = True, **kwargs: Any) -> str

Parameters

Name	Description
exclude Required	set[str] \| None
exclude_none Required	bool
kwargs Required	Any

Keyword-Only Parameters

Name	Description
exclude	Additional field names to exclude from serialization. Default value: None
exclude_none	Whether to exclude None values from the output. Defaults to True. Default value: True
**kwargs	Additional keyword arguments passed through to `json.dumps()`. Common options include `indent` for pretty-printing and `ensure_ascii` for Unicode handling.

Returns

Type	Description
str	JSON string representation of the instance.

Attributes

uri

The URI of the data represented by this instance, typically in the form of a data URI. Should be in the form: "data:{media_type};base64,{base64_data}".

media_type

The media type of the data.

type

The type of content, which is always "data" for this class.

annotations

Optional annotations associated with the content.

annotations: list[CitationAnnotation] | None

additional_properties

Optional additional properties associated with the content.

raw_representation

Optional raw representation of the content.

DEFAULT_EXCLUDE

DEFAULT_EXCLUDE: ClassVar[set[str]] = {'additional_properties', 'raw_representation'}

INJECTABLE

INJECTABLE: ClassVar[set[str]] = {}

Feedback

Was this page helpful?

Share via

DataContent Class

Constructor

Keyword-Only Parameters

Examples

Methods

__init__

Keyword-Only Parameters

__new__

create_data_uri_from_base64

Parameters

Returns

detect_image_format_from_base64

Parameters

Returns

from_dict

Positional-Only Parameters

Parameters

Keyword-Only Parameters

Returns

Exceptions

Examples

from_json

Positional-Only Parameters

Parameters

Keyword-Only Parameters

Returns

Exceptions

get_data_bytes

Returns

get_data_bytes_as_str

Returns

has_top_level_media_type

Parameters

Returns

to_dict

Parameters

Keyword-Only Parameters

Returns

to_json

Parameters

Keyword-Only Parameters

Returns

Attributes

uri

media_type

type

annotations

additional_properties

raw_representation

DEFAULT_EXCLUDE

INJECTABLE

Feedback

init

new