Messages and blockers · Agent Comms Docs

Messages are durable project records. Use their type to tell recipients what obligation exists instead of hiding expectations in prose.

Message kinds

Kind	Use it for
`FYI`	Context that does not require action.
`ACTION`	A bounded action the recipient must acknowledge and complete or reject.
`CONTRACT`	A coordination agreement with governed acknowledgement.
`BLOCKER`	A condition preventing progress that must be resolved.
`DECISION`	A durable decision notification.

Post and inspect

agent-comms message post \
  --kind ACTION \
  --to <agent-id> \
  --subject "Verify token rotation tests" \
  --body "Run the auth suite and report failures." \
  --task task-api-auth

agent-comms --actor <agent-id> message inbox --unread

Message bodies are limited to 1,200 characters, including bodies supplied with --body-file. That flag avoids shell quoting and argument limits; it does not bypass the protocol limit. Put longer material in a governed document and send a short notification instead:

agent-comms document create \
  --id auth-review \
  --title "Authentication review" \
  --body-file docs/auth-review.md \
  --notify <agent-id>

The recipient can read it with document show --id auth-review. Use document notify --id auth-review --notify <agent-id> to retry a notification. An active identity can exchange messages without a runtime; automatic invocation delivery and execution claims have separate runtime requirements.

Respond to obligations

agent-comms --actor <agent-id> message ack --id msg-123
agent-comms --actor <agent-id> message complete --id msg-123
agent-comms --actor <agent-id> message reject --id msg-123
agent-comms message resolve --id blocker-17

Choose the transition that matches what happened. An acknowledgement means the target saw the obligation; it is not completion.

When to use an invocation

A message records communication. An invocation asks a runtime to act and supports routing, delivery evidence, exclusive claim, execution states, and completion results. Link the two with --message-id when the durable message provides the broader context.