Message Structure

In the Agent Communication Protocol (ACP), a Message is a sequence of ordered parts, forming complete, structured, multi-modal communications.

​

Message Parts

​

Artifacts

Artifacts are specialized MessageParts identified explicitly by a required name attribute. They typically represent:

• Attachments
• Citations
• Files
• Named results

​

Examples

ACP Messages always consist of ordered parts. The ordering ensures content is presented or processed in the intended sequence.

​

Basic Text Message

{
  "content_type": "text/plain",
  "content": "Hello, world!"
}

​

Multi-modal Message with Image

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

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

Use inline content for small, text-based, or simple data:

{
  "content_type": "text/plain",
  "content": "Direct text content",
  "content_encoding": "plain" // Default if omitted
}

​

Referenced Content

Use referenced content (via URLs) for larger files, external resources, or when inline embedding is impractical:

{
  "content_type": "image/jpeg",
  "content_url": "https://example.com/image.jpg"
}

​

Base64 Encoded Content

Use explicitly for binary data (e.g., images, documents) embedded directly:

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

    # 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):
    parts: list[MessagePart]

​

Validation Rules

• Every part must have a content_type
• Parts must provide either content or content_url, but not both
• MessageParts with a name are considered Artifacts
• Parts are ordered, allowing for structured sequences

​

Common Content Types

Some commonly used content types include:

• text/plain: For plain text content
• image/png, image/jpeg: For image content
• application/json: For JSON data
• application/pdf: For PDF documents
• text/html: For HTML content

Any valid MIME type can be used as appropriate for your content.

​

Extensibility Feature

ACP is designed to be extensible through specialized content types:

• Schema validation via application/json;schema=...
• Special meaning for certain types (trajectory, tool calling, etc.)
• Additional metadata for specific applications