> ## Documentation Index
> Fetch the complete documentation index at: https://agentcommunicationprotocol.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Message Metadata

> Learn how ACP uses metadata to provide semantic context and additional information for message parts

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](https://beeai.dev) demonstrates the value of standardized message metadata by exposing these patterns through a clean, intuitive GUI.

For the complete message structure, see [Message Structure](/core-concepts/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.

```python theme={null}
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
```

<CodeGroup>
  ```json JSON Message theme={null}
  {
    "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
        }
      }
    ]
  }
  ```

  ```python Python SDK theme={null}
  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
      )
  )
  ```
</CodeGroup>

### Trajectory Metadata

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

```python theme={null}
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
```

<CodeGroup>
  ```json JSON Message theme={null}
  {
    "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"}
        }
      }
    ]
  }
  ```

  ```python Python SDK theme={null}
  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"}
      )
  )
  ```
</CodeGroup>

## 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