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

> A minimal, multi-modal structure for exchanging content

A Message is how agents send and receive information in ACP. Messages consists of a sequence of ordered parts, forming complete, structured, multi-modal communications.

## Message Role

Each message must specify a `role` that identifies the sender. Valid role formats are:

* `user` - for messages from users
* `agent` - for generic agent messages
* `agent/{name}` - for specific agent messages where name can contain alphanumeric characters, underscores, and hyphens (e.g. `agent/image-analyzer`, `agent/chat_bot`)

## Message Parts

| Attribute                  | Required | Description                                                               |
| :------------------------- | :------- | :------------------------------------------------------------------------ |
| `content_type`             | Yes      | MIME type (e.g., `text/plain`, `image/png`)                               |
| `content` OR `content_url` | Yes      | Content `inline` or via `URL`                                             |
| `content_encoding`         | No       | `"plain"`  (default) or `"base64"`                                        |
| `name`                     | No       | Makes this part an **Artifact**                                           |
| `metadata`                 | No       | Additional metadata to provide additional context or semantic information |

## Artifacts

**Artifacts** are specialized MessageParts with a `name` attribute. They represent important outputs like:

* Attachments
* Citations
* Files
* Named results

## Metadata

MessageParts can include optional `metadata` to provide additional context or semantic information. ACP supports standardized metadata types for citations and trajectory information.

For detailed information about metadata types, usage patterns, and examples, see [Message Metadata](/core-concepts/message-metadata).

## Examples

Messages are made of ordered parts. The order determines how content is presented or processed.

### Basic Text Message

```json theme={null}
{
  "role": "user",
  "parts": [{
    "content_type": "text/plain",
    "content": "Hello, world!"
  }]
}
```

### Agent Response Message

```json theme={null}
{
  "role": "agent/assistant",
  "parts": [{
    "content_type": "text/plain",
    "content": "Hello! How can I help you today?"
  }]
}
```

### Multi-modal Message with Image

```json theme={null}
{
  "role": "agent/image-analyzer",
  "parts": [
    {
      "content_type": "text/plain",
      "content": "This is a cute cat:"
    },
    {
      "content_type": "image/png",
      "content_url": "https://s3.example.com/12345678901234567890/image.png"
    },
    {
      "content_type": "text/plain",
      "content": "Would you like me to send more images of cats?"
    },
    {
      "name": "/sources/1.url",
      "content_type": "text/url",
      "content": "https://example.com/cat-facts"
    }
  ]
}
```

### Message with an Artifact

```json theme={null}
{
  "role": "agent/report-generator",
  "parts": [
    {
      "content_type": "text/plain",
      "content": "Here's the report you requested:"
    },
    {
      "name": "/report.pdf",
      "content_type": "application/pdf",
      "content_url": "https://example.com/report.pdf"
    }
  ]
}
```

## Content Delivery Methods

### Inline Content

Best for small, text-based, or simple data:

```json theme={null}
{
  "role": "user",
  "parts": [{
    "content_type": "text/plain",
    "content": "Direct text content",
    "content_encoding": "plain" // Default if omitted
  }]
}
```

### Referenced Content (URL)

Best for larger files, external resources, or when inline embedding is impractical:

```json theme={null}
{
  "role": "agent/file-processor",
  "parts": [{
    "content_type": "image/jpeg",
    "content_url": "https://example.com/image.jpg"
  }]
}
```

### Base64 Encoded Content

Best for binary data (images, documents) embedded directly:

```json theme={null}
{
  "role": "agent/image-processor",
  "parts": [{
    "content_type": "image/png",
    "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
    "content_encoding": "base64"
  }]
}
```

## Data Models

```python theme={null}
class MessagePart(BaseModel):
    name: Optional[str] = None
    content_type: str
    content: Optional[str] = None
    content_encoding: Optional[Literal["plain", "base64"]] = "plain"
    content_url: Optional[AnyUrl] = None
    metadata: Optional[CitationMetadata | TrajectoryMetadata] = None

    # Validation ensures either content or content_url is provided, but not both

class Artifact(MessagePart):
    name: str  # Name is required for Artifacts

class Message(BaseModel):
    role: Literal["user"] | Literal["agent"] | str  # str must match pattern "^(user|agent(\/[a-zA-Z0-9_\-]+)?)$"
    parts: list[MessagePart]
```

For detailed metadata type definitions, see [Message Metadata](/core-concepts/message-metadata).

<Note>`Artifacts` inherit all validation rules from `MessagePart` so they must also have either `content` or `content_url` (never both).</Note>

## Validation Rules

* Every part must have a `content_type`
* Parts must provide either `content` or `content_url` (not both)
* MessageParts with a `name` are Artifacts
* Parts are processed in order

## Common Content Types

Any valid MIME type can be used as content. Some common ones are:

* `text/plain`: Plain text content
* `image/png`, `image/jpeg`: Image content
* `application/json`: JSON data
* `application/pdf`: PDF documents
* `text/html`: HTML content