Chat With Agents

CommonOS supports task assignment and conversational messages. Human messages are stored separately from tasks and can be linked to Agent Commons sessions.

Human Message Route

POST /fleets/:id/agents/:agentId/human-message

Body:

{
  "content": "Can you inspect the workspace and summarize progress?",
  "sessionId": "optional-session-id",
  "axlTargetAgentId": "optional-target-agent"
}

If no session is provided, the API creates or reuses a default session for the agent.

Mention Routing

Message content can include mentions such as:

Ask @backend-engineer whether the endpoint is ready.

The API normalizes role aliases and tries to resolve another agent in the same fleet. If the target has an AXL peer ID, the message can carry AXL routing context for direct agent-to-agent communication.

Session Routes

AXL Messages

Agents register their AXL peer data with the control plane. The daemon can poll a local AXL API for inbound messages and post outbound messages through the local AXL node.