Messages

The AgentOpera message system provides the communication infrastructure that powers agent interactions within the platform. Built on Pydantic models for type safety and serialization support, the system enables structured and versatile exchanges between agents, tools, and human users.

BaseMessage
├── BaseChatMessage
│   ├── TextMessage
│   ├── MultiModalMessage
│   ├── StopMessage
│   ├── HandoffMessage
│   └── ToolCallSummaryMessage
└── BaseAgentEvent
    ├── ToolCallRequestEvent
    ├── ToolCallExecutionEvent
    ├── MemoryQueryEvent
    ├── UserInputRequestedEvent
    ├── ModelClientStreamingChunkEvent
    └── ThoughtEvent

Core Concepts

Universal Message Properties

All messages in AgentOpera share these fundamental attributes:

• Source: Identifies the agent that created the message

• Model Usage: Tracks computational resources utilized

• Metadata: Stores additional contextual information.

# Common structure of all messages
{
    "source": "AgentName",
    "models_usage": {...},  # Optional
    "metadata": {...},      # Optional
    "type": "MessageType"   # Discriminator field
}

Communication Channels

AgentOpera distinguishes between two separate communication channels:

1. External Channel: For agent-to-agent or agent-to-user communication

2. Internal Channel: For recording operations within an agent's workflow

This separation maintains clear boundaries between what agents communicate externally and what they process or do internally.

External Communication (BaseChatMessage)

External messages represent the explicit, user-facing communication between agents.

TextMessage

The most basic communication unit containing plain text.

TextMessage(
    content="I've analyzed the data you provided.",
    source="AnalystAgent"
)

MultiModalMessage

A communication unit that contains both text and visual elements.

MultiModalMessage(
    content=[
        "Here's the chart showing quarterly revenue:",
        Image(data=chart_bytes, mime_type="image/png")
    ],
    source="DataVisualizationAgent"
)

Control Messages

Special message types that direct the flow of conversation:

• StopMessage: Terminates the current conversation flow

• HandoffMessage: Transfers control to another agent with context

• ToolCallSummaryMessage: Provides human-readable summaries of tool operations

Internal Operations (BaseAgentEvent)

Events record the internal operations of agents, tools, and systems.

Tool Interaction Events

• ToolCallRequestEvent: Record tool invocation requests

• ToolCallExecutionEvent: Capture tool execution results

ToolCallRequestEvent(
    content=[FunctionCall(name="search_database", arguments={"query": "revenue 2023"})],
    source="ResearchAgent"
)

Runtime Events

• ModelClientStreamingChunkEvent: Tracks streaming model outputs

• UserInputRequestedEvent: Signals when user input is needed

Example: Complete Interaction

# User sends a query
user_msg = TextMessage(content="What's the stock performance of ACME Corp?", source="User")

# Agent processes query and executes a tool
# (internally generates ToolCallRequestEvent and ToolCallExecutionEvent)

# Agent responds with analysis including a chart
response = MultiModalMessage(
    content=[
        "ACME Corp stock has grown 12% YTD. Here's the trend:",
        stock_chart_image
    ],
    source="FinancialAgent"
)

This exchange shows how messages support complex workflows while keeping visible conversation and internal processing separate.