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
      }
    }
  ]
}

​
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"}
      }
    }
  ]
}

​
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