Skip to main 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

AttributeRequiredDescription
content_typeYesMIME type (e.g., text/plain, image/png)
content OR content_urlYesContent inline or via URL
content_encodingNo"plain" (default) or "base64"
nameNoMakes this part an Artifact
metadataNoAdditional 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.

​
Examples

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

​
Basic Text Message

{
  "role": "user",
  "parts": [{
    "content_type": "text/plain",
    "content": "Hello, world!"
  }]
}

​
Agent Response Message

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

​
Multi-modal Message with Image

{
  "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

{
  "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: 
{
  "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: 
{
  "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: 
{
  "role": "agent/image-processor",
  "parts": [{
    "content_type": "image/png",
    "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
    "content_encoding": "base64"
  }]
}

​
Data Models

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.
Artifacts inherit all validation rules from MessagePart so they must also have either content or content_url (never both).

​
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
⌘I