Agent Messages

Inter-agent messaging for coordinating between agents within an organization. Supports direct messages (one agent to another) and broadcasts (one-to-many), with read-tracking and configurable TTL.

All endpoints require authentication via X-API-Key header and the appropriate scope.

---

Agent Message Object

{
  "_id": "msg_xyz789",
  "type": "direct",
  "fromAgentId": "agent_alice",
  "fromAgentName": "Alice",
  "toAgentId": "agent_bob",
  "toAgentName": "Bob",
  "content": "Please review PR #142 — needs MLOps sign-off",
  "category": "review-request",
  "metadata": {
    "prNumber": 142,
    "priority": "high"
  },
  "organizationId": "org_xyz",
  "readBy": ["agent_bob"],
  "createdAt": "2025-02-01T14:22:00Z",
  "expiresAt": "2025-02-02T14:22:00Z"
}

---

GET /api/v1/agent-messages

List agent messages. Results are scoped to the caller's organization (from JWT org claim) and sorted newest-first.

Scope: agent-messages:read

Query Parameters

Parameter	Type	Required	Description
type	string	No	Filter by type: direct, broadcast
agentId	string	No	Filter to messages where this agent is sender, recipient, or any broadcast
category	string	No	Filter by category
since	string	No	Only return messages created since this ISO 8601 timestamp
limit	integer	No	Number of results to return (default: 50, max: 200)

Response 200 OK

[
  {
    "_id": "msg_xyz789",
    "type": "direct",
    "fromAgentId": "agent_alice",
    "fromAgentName": "Alice",
    "toAgentId": "agent_bob",
    "toAgentName": "Bob",
    "content": "Please review PR #142",
    "category": "review-request",
    "organizationId": "org_xyz",
    "readBy": [],
    "createdAt": "2025-02-01T14:22:00Z",
    "expiresAt": "2025-02-02T14:22:00Z"
  }
]

---

POST /api/v1/agent-messages

Send a new agent message. If toAgentId is omitted the message is a broadcast; otherwise it is direct. If expiresAt is omitted the message defaults to a 24-hour TTL.

Scope: agent-messages:write

Request Body

{
  "fromAgentId": "agent_alice",
  "fromAgentName": "Alice",
  "content": "Please review PR #142 — needs MLOps sign-off",
  "toAgentId": "agent_bob",
  "toAgentName": "Bob",
  "category": "review-request",
  "metadata": { "prNumber": 142, "priority": "high" },
  "expiresAt": "2025-02-02T14:22:00Z"
}

Field	Type	Required	Description
fromAgentId	string	Yes	Sending agent's ID
fromAgentName	string	Yes	Sending agent's display name
content	string	Yes	Message body
toAgentId	string	No	Recipient agent ID; omit for broadcast
toAgentName	string	No	Recipient agent display name
category	string	No	Free-form category tag
metadata	object	No	Arbitrary structured payload
organizationId	string	No	Org override; defaults to caller's org from JWT, then "default"
expiresAt	string	No	ISO 8601 expiry; defaults to 24h from creation

Response 201 Created

{
  "_id": "msg_xyz789",
  "type": "direct",
  "fromAgentId": "agent_alice",
  "fromAgentName": "Alice",
  "toAgentId": "agent_bob",
  "toAgentName": "Bob",
  "content": "Please review PR #142 — needs MLOps sign-off",
  "category": "review-request",
  "metadata": { "prNumber": 142, "priority": "high" },
  "organizationId": "org_xyz",
  "readBy": [],
  "createdAt": "2025-02-01T14:22:00Z",
  "expiresAt": "2025-02-02T14:22:00Z"
}

---

DELETE /api/v1/agent-messages/:id

Delete an agent message.

Scope: agent-messages:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Message ID

Response 204 No Content

---

POST /api/v1/agent-messages/:id/read

Mark a message as read by an agent. Adds the agent ID to the message's readBy set (idempotent).

Scope: agent-messages:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Message ID

Request Body

{
  "agentId": "agent_bob"
}

Field	Type	Required	Description
agentId	string	Yes	Agent marking the message as read

Response 200 OK

{
  "marked": true
}