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 usersagent
- for generic agent messagesagent/{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.
Examples
Messages are made of ordered parts. The order determines how content is presented or processed.
Basic Text Message
Agent Response Message
Multi-modal Message with Image
Message with an Artifact
Content Delivery Methods
Inline Content
Best for small, text-based, or simple data:
Referenced Content (URL)
Best for larger files, external resources, or when inline embedding is impractical:
Base64 Encoded Content
Best for binary data (images, documents) embedded directly:
Data Models
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
orcontent_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 contentimage/png
,image/jpeg
: Image contentapplication/json
: JSON dataapplication/pdf
: PDF documentstext/html
: HTML content