OpenResponses Types

2.3.0.post1 · active · verified Fri Apr 17

The `openresponses-types` library provides a Python SDK for the OpenResponses specification, offering standardized data types and models for structured interactions, particularly for AI agents. It leverages Pydantic for robust data validation, serialization, and deserialization of response and prompt structures. The current version is 2.3.0.post1, with releases aligning with updates to the underlying OpenResponses specification.

Common errors

```
ModuleNotFoundError: No module named 'openresponses_types'
```
cause Attempting to import directly from the PyPI package name (openresponses-types) instead of the actual installed Python package (openresponses).

fix Change your import statements from `from openresponses_types import ...` to `from openresponses.types import ...`.
```
AttributeError: 'AgentResponse' object has no attribute 'json'
```
cause This error typically occurs when using Pydantic V1 methods (`.json()`, `.dict()`) on Pydantic V2 models. `openresponses-types` uses Pydantic V2.

fix Replace `.json()` with `.model_dump_json()` and `.dict()` with `.model_dump()` to align with Pydantic V2 API changes.
```
pydantic.ValidationError: X validation error for Y
```
cause The data provided to construct or validate an OpenResponse model does not conform to the schema (e.g., missing required fields, incorrect types, invalid enum values).

fix Carefully review the traceback to identify the specific field causing the error. Check the OpenResponses specification or the model definitions (`.model_json_schema()`) to ensure your data matches the expected structure and types.

Warnings

gotcha The PyPI package name (`openresponses-types`) is different from the top-level Python package name you import (`openresponses`). Always use `from openresponses.types import ...`.
Fix: Ensure your imports start with `from openresponses.types` or `from openresponses.types.model` etc., not `openresponses_types`.
breaking This library explicitly requires Pydantic V2. Projects using Pydantic V1 will encounter conflicts and `pydantic.ValidationError` or `AttributeError` if Pydantic V1 methods are used.
Fix: Upgrade Pydantic to version 2 or greater (`pip install 'pydantic>=2.0.0'`) and update your Pydantic model usage (e.g., `model_dump_json()` instead of `json()`, `model_validate()` instead of direct class instantiation from dict).
gotcha The `OpenResponse` specification is strict. Any data provided that does not conform to the defined schemas will result in `pydantic.ValidationError`.
Fix: Consult the OpenResponses specification and ensure all fields, types, and constraints (e.g., enum values, regex patterns) are strictly followed when constructing objects or deserializing data.

Install

pip install openresponses-types Install stable version

Imports

OpenResponse
wrong:
```
from openresponses_types import OpenResponse
```
correct:
```
from openresponses.types import OpenResponse
```
The PyPI package `openresponses-types` installs the Python package `openresponses`. Types are found under `openresponses.types`.

AgentResponse

from openresponses.types import AgentResponse

HumanResponse

from openresponses.types import HumanResponse

ChatMLMessage
wrong:
```
from openresponses.types import ChatMLMessage
```
correct:
```
from openresponses.types.model import ChatMLMessage
```
Specific model components are often nested in `openresponses.types.model`.

Action

from openresponses.types.action import Action

Quickstart

This quickstart demonstrates how to create an `AgentResponse` containing a `ChatMLMessage`, embed it within an `OpenResponse`, and then serialize and deserialize the entire structure using Pydantic's V2 methods.

from openresponses.types import AgentResponse, OpenResponse
from openresponses.types.model import ChatMLMessage

# Create an AgentResponse
agent_msg = ChatMLMessage(role="assistant", content="Hello, how can I help you?")
agent_response = AgentResponse(
    model_name="gpt-4",
    messages=[agent_msg]
)

# Create an OpenResponse containing the agent's response
open_response = OpenResponse(
    response=agent_response,
    prompt_hash="example_hash_123"
)

# Print the OpenResponse object (serialized to JSON)
print("OpenResponse object created:")
print(open_response.model_dump_json(indent=2))

# Example of deserialization from JSON string
json_data = open_response.model_dump_json()
reconstructed_response = OpenResponse.model_validate_json(json_data)
print("\nOpenResponse object deserialized:")
print(reconstructed_response.model_dump_json(indent=2))

view raw JSON →