Message Metadata - Agent Communication Protocol

Message metadata provides semantic context and additional information for message parts. ACP supports two types: citations for source attribution and trajectory data for transparency into agent operations. The BeeAI platform demonstrates the value of standardized message metadata by exposing these patterns through a clean, intuitive GUI. For the complete message structure, see Message Structure.

Metadata Types

Each metadata object has a kind field that identifies its type.

Citation Metadata

Citations attribute content to original sources. Essential for research and RAG agents.

class CitationMetadata(BaseModel):
    kind: Literal["citation"] = "citation"
    start_index: Optional[int] = None      # Start of text range
    end_index: Optional[int] = None        # End of text range  
    url: Optional[str] = None              # Source URL
    title: Optional[str] = None            # Source title
    description: Optional[str] = None      # Source description or snippet

{
  "role": "agent/researcher",
  "parts": [
    {
      "content_type": "text/plain", 
      "content": "According to a recent study, AI adoption has increased by 40% this year.",
      "metadata": {
        "kind": "citation",
        "url": "https://example.com/ai-study-2024",
        "title": "AI Adoption Report 2024",
        "description": "Comprehensive analysis of AI adoption trends across industries",
        "start_index": 15,
        "end_index": 27
      }
    }
  ]
}

yield MessagePart(
    content="According to recent studies, AI adoption has increased by 40% this year.",
    metadata=CitationMetadata(
        url="https://example.com/ai-study-2024",
        title="AI Adoption Report 2024",
        description="Comprehensive analysis of AI adoption trends across industries",
        start_index=15,
        end_index=27
    )
)

Trajectory Metadata

Trajectory metadata provides transparency into agent decision-making and tool usage.

class TrajectoryMetadata(BaseModel):
    kind: Literal["trajectory"] = "trajectory"
    message: Optional[str] = None               # Internal reasoning or thoughts
    tool_name: Optional[str] = None             # Name of executed tool
    tool_input: Optional[dict] = None           # Tool input parameters
    tool_output: Optional[dict] = None          # Tool output result

{
  "role": "agent/assistant",
  "parts": [
    {
      "content_type": "text/plain",
      "content": "It's currently 72°F and sunny in San Francisco.",
      "metadata": {
        "kind": "trajectory",
        "tool_name": "weather_api",
        "tool_input": {"location": "San Francisco, CA"},
        "tool_output": {"temperature": 72, "condition": "sunny"}
      }
    }
  ]
}

yield MessagePart(
    content="It's currently 72°F and sunny in San Francisco.",
    metadata=TrajectoryMetadata(
        tool_name="weather_api",
        tool_input={"location": "San Francisco, CA"},
        tool_output={"temperature": 72, "condition": "sunny"}
    )
)

Best Practices

Metadata is additional data - Never put conversation content in metadata; it’s for context and transparency only
Keep metadata focused and purposeful for debugging, attribution, or system information

​Metadata Types

​Citation Metadata

​Trajectory Metadata

​Best Practices

Metadata Types

Citation Metadata

Trajectory Metadata

Best Practices