Module agents.llm.context.items

Classes

class AgentConfigUpdate (**data: Any)

Expand source code

class AgentConfigUpdate(_ChatItemBase):
    """Records a mid-conversation change to an agent's instructions or tools.

    Structural item — excluded from provider conversion; feeds active-config
    resolution.
    """

    id: str = Field(default_factory=lambda: f"cfgupd_{uuid.uuid4().hex[:12]}")
    type: Literal["agent_config_update"] = "agent_config_update"
    instructions: Optional[str] = None
    tools: Optional[List[str]] = None

Records a mid-conversation change to an agent's instructions or tools.

Structural item — excluded from provider conversion; feeds active-config resolution.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• agents.llm.context.items._ChatItemBase
• pydantic.main.BaseModel

Class variables

var id : str

var instructions : str | None

var model_config

var tools : List[str] | None

var type : Literal['agent_config_update']

class AgentHandoff (**data: Any)

Expand source code

class AgentHandoff(_ChatItemBase):
    """Records a transfer of control between agents.

    Structural item — excluded from provider conversion.
    """

    id: str = Field(default_factory=lambda: f"handoff_{uuid.uuid4().hex[:12]}")
    type: Literal["agent_handoff"] = "agent_handoff"
    from_agent: Optional[str] = None
    to_agent: str
    reason: Optional[str] = None

Records a transfer of control between agents.

Structural item — excluded from provider conversion.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• agents.llm.context.items._ChatItemBase
• pydantic.main.BaseModel

Class variables

var from_agent : str | None

var id : str

var model_config

var reason : str | None

var to_agent : str

var type : Literal['agent_handoff']

class ChatMessage (**data: Any)

Expand source code

class ChatMessage(_ChatItemBase):
    """A user, assistant, system, or developer utterance."""

    role: ChatRole
    content: Union[str, List[ChatContent]]
    id: str = Field(default_factory=lambda: f"msg_{uuid.uuid4().hex[:12]}")
    type: Literal["message"] = "message"
    interrupted: bool = False
    extra: dict[str, Any] = Field(default_factory=dict)
    confidence: Optional[float] = None
    metrics: Optional[dict] = None
    audio_instructions: Optional[str] = None
    text_instructions: Optional[str] = None

    def instructions_for_modality(
        self, modality: Literal["audio", "text"]
    ) -> Union[str, List[ChatContent]]:
        """Return the instruction variant for the given input modality.

        Falls back to ``content`` when no modality-specific variant is set.
        """
        if modality == "audio" and self.audio_instructions is not None:
            return self.audio_instructions
        if modality == "text" and self.text_instructions is not None:
            return self.text_instructions
        return self.content

A user, assistant, system, or developer utterance.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• agents.llm.context.items._ChatItemBase
• pydantic.main.BaseModel

Class variables

var audio_instructions : str | None

var confidence : float | None

var content : str | List[str | ImageContent]

var extra : dict[str, typing.Any]

var id : str

var interrupted : bool

var metrics : dict | None

var model_config

var role : ChatRole

var text_instructions : str | None

var type : Literal['message']

Methods

def instructions_for_modality(self, modality: "Literal['audio', 'text']") ‑> str | List[str | ImageContent]

Expand source code

def instructions_for_modality(
    self, modality: Literal["audio", "text"]
) -> Union[str, List[ChatContent]]:
    """Return the instruction variant for the given input modality.

    Falls back to ``content`` when no modality-specific variant is set.
    """
    if modality == "audio" and self.audio_instructions is not None:
        return self.audio_instructions
    if modality == "text" and self.text_instructions is not None:
        return self.text_instructions
    return self.content

Return the instruction variant for the given input modality.

Falls back to content when no modality-specific variant is set.

class ChatRole (*args, **kwds)

Expand source code

class ChatRole(str, Enum):
    """Roles used in chat conversations."""

    SYSTEM = "system"
    DEVELOPER = "developer"
    USER = "user"
    ASSISTANT = "assistant"

Roles used in chat conversations.

Ancestors

• builtins.str
• enum.Enum

Class variables

var ASSISTANT

var DEVELOPER

var SYSTEM

var USER

class FunctionCall (**data: Any)

Expand source code

class FunctionCall(_ChatItemBase):
    """A tool invocation initiated by the language model."""

    id: str = Field(default_factory=lambda: f"call_{uuid.uuid4().hex[:12]}")
    type: Literal["function_call"] = "function_call"
    name: str
    arguments: str
    call_id: str
    metadata: Optional[dict] = None

A tool invocation initiated by the language model.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• agents.llm.context.items._ChatItemBase
• pydantic.main.BaseModel

Class variables

var arguments : str

var call_id : str

var id : str

var metadata : dict | None

var model_config

var name : str

var type : Literal['function_call']

class FunctionCallOutput (**data: Any)

Expand source code

class FunctionCallOutput(_ChatItemBase):
    """The result of a tool execution."""

    id: str = Field(default_factory=lambda: f"output_{uuid.uuid4().hex[:12]}")
    type: Literal["function_call_output"] = "function_call_output"
    name: str
    call_id: str
    output: str
    is_error: bool = False

The result of a tool execution.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• agents.llm.context.items._ChatItemBase
• pydantic.main.BaseModel

Class variables

var call_id : str

var id : str

var is_error : bool

var model_config

var name : str

var output : str

var type : Literal['function_call_output']

class ImageContent (**data: Any)

Expand source code

class ImageContent(BaseModel):
    """Image content in a chat message."""

    model_config = ConfigDict(arbitrary_types_allowed=True)

    id: str = Field(default_factory=lambda: f"img_{uuid.uuid4().hex[:12]}")
    type: Literal["image"] = "image"
    image: Union[av.VideoFrame, str]
    inference_detail: Literal["auto", "high", "low"] = "auto"
    encode_options: EncodeOptions = Field(
        default_factory=lambda: EncodeOptions(
            format="JPEG",
            quality=90,
            resize_options=ResizeOptions(width=320, height=240),
        )
    )

    def to_data_url(self) -> str:
        """Convert the image to a data URL string."""
        if isinstance(self.image, str):
            return self.image
        encoded_image = images.encode(self.image, self.encode_options)
        b64_image = base64.b64encode(encoded_image).decode("utf-8")
        return f"data:image/{self.encode_options.format.lower()};base64,{b64_image}"

Image content in a chat message.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• pydantic.main.BaseModel

Class variables

var encode_options : EncodeOptions

var id : str

var image : av.video.frame.VideoFrame | str

var inference_detail : Literal['auto', 'high', 'low']

var model_config

var type : Literal['image']

Methods

def to_data_url(self) ‑> str

Expand source code

def to_data_url(self) -> str:
    """Convert the image to a data URL string."""
    if isinstance(self.image, str):
        return self.image
    encoded_image = images.encode(self.image, self.encode_options)
    b64_image = base64.b64encode(encoded_image).decode("utf-8")
    return f"data:image/{self.encode_options.format.lower()};base64,{b64_image}"

Convert the image to a data URL string.