Overview

The Agent Triage Protocol defines structured message formats to ensure consistent communication between services, the ATP server, and client applications. This page details the structure of notifications and responses.

Triage Notification Structure

A triage notification encapsulates all information required for an AI service to request human intervention. The notification schema comprises both required and optional fields that collectively define the decision context and available actions.

Core Notification Fields

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "version": "1.0",
  "timestamp": "2025-05-25T10:30:00Z",
  "deadline": "2025-05-25T11:00:00Z",
  "service": {
    "id": "lovelace-ide",
    "name": "Lovelace IDE",
    "icon": "https://lovelace.dev/icon.png"
  },
  "context": {
    "title": "Code Compilation Failed",
    "description": "While tests compiled successfully, the application crashes on startup with a null pointer exception in UserService.initialize().",
    "project": "mobile-app-v2",
    "metadata": {
      "file": "src/services/UserService.java",
      "line": 47,
      "error_type": "NullPointerException",
      "logs_url": "https://lovelace.dev/logs/123456"
    },
    "attachments": [
      // See Attachments section below
    ]
  },
  "actions": [
    // See Actions section below
  ]
}

Field	Type	Required	Description
`id`	string	Yes	Globally unique identifier using UUID v4 format
`version`	string	Yes	Protocol version identifier, currently “1.0”
`timestamp`	datetime	Yes	ISO 8601 formatted creation timestamp
`deadline`	datetime	No	ISO 8601 formatted expiration timestamp

Service Identification Object

"service": {
  "id": "lovelace-ide",
  "name": "Lovelace IDE",
  "icon": "https://lovelace.dev/icon.png"
}

Field	Type	Required	Description
`id`	string	Yes	Service identifier assigned during registration
`name`	string	Yes	Human-readable service name
`icon`	string	No	URL pointing to service icon for client rendering

Context Object

"context": {
  "title": "Code Compilation Failed",
  "description": "While tests compiled successfully, the application crashes on startup with a null pointer exception in UserService.initialize().",
  "project": "mobile-app-v2",
  "metadata": {
    "file": "src/services/UserService.java",
    "line": 47,
    "error_type": "NullPointerException",
    "logs_url": "https://lovelace.dev/logs/123456"
  },
  "attachments": [
    // See next section
  ]
}

Field	Type	Required	Description
`title`	string	Yes	Concise summary of the required decision
`description`	string	Yes	Detailed explanation of the situation
`metadata`	object	No	Arbitrary key-value pairs for additional context
`attachments`	array	No	Additional resources providing context for the decision
`project`	string	No	Identifier for grouping related notifications

Context Attachments

Notifications may include attachments that provide additional context for decision-making without cluttering the main notification body. Attachments support two delivery methods to balance flexibility with performance.

"attachments": [
  {
    "type": "text/plain",
    "description": "Stack trace at point of failure",
    "data": "amF2YS5sYW5nLk51bGxQb2ludGVyRXhjZXB0aW9uCiAgYXQgY29tLmFwcC5Vc2VyU2VydmljZS5pbml0aWFsaXplKFVzZXJTZXJ2aWNlLmphdmE6NDcpCiAgYXQgY29tLmFwcC5BcHBsaWNhdGlvbi5zdGFydHVwKEFwcGxpY2F0aW9uLmphdmE6MjMpCiAgYXQgY29tLmFwcC5NYWluLm1haW4oTWFpbi5qYXZhOjE1KQ=="
  },
  {
    "type": "image/png",
    "description": "IDE state at time of error",
    "uri": "https://lovelace.dev/screenshots/error-12345.png"
  }
]

Field	Type	Required	Description
`type`	string	Yes	MIME type of the attachment content
`description`	string	No	Human-readable description of the attachment’s relevance
`uri`	string	Conditional	External URI reference for the attachment
`data`	string	Conditional	Base64-encoded content for inline delivery

Each attachment must include either a uri or data field, but not both. The choice between URI references and inline data depends on the attachment size, sensitivity, and expected client capabilities.

Action Definition

Each action represents a possible response to the notification. The actions array must contain at least one action object.

"actions": [
  {
    "id": "debug",
    "label": "Open debugger",
    "response_type": "simple",
    "flags": []
  },
  {
    "id": "fix_suggest",
    "label": "Suggest a fix",
    "response_type": "simple",
    "flags": ["experimental"]
  },
  {
    "id": "rollback",
    "label": "Rollback to last working version",
    "response_type": "simple",
    "flags": ["destructive", "irreversible"]
  },
  {
    "id": "how_proceed",
    "label": "How should I proceed?",
    "response_type": "choice",
    "options": [
      {"value": "debug", "label": "Open the debugger at the crash point"},
      {"value": "fix_suggest", "label": "Request an AI-generated fix"},
      {"value": "rollback", "label": "Revert to the last working version"},
      {"value": "ignore", "label": "Continue despite the error"}
    ],
    "flags": []
  }
]

Field	Type	Required	Description
`id`	string	Yes	Unique identifier for the action within this notification
`label`	string	Yes	Human-readable text for UI presentation
`response_type`	string	Yes	Enumerated type defining expected input format
`flags`	array of strings	No	Behavioral characteristics of the action

Action Flags

Action flags communicate important properties that help clients implement appropriate safeguards and user experiences. Multiple flags may be combined to accurately describe an action’s behavior.

Flag	Description
`destructive`	The action will delete, remove, or significantly modify existing data
`irreversible`	The action cannot be undone once executed
`time_sensitive`	The action’s effectiveness or availability depends on prompt execution
`affects_others`	The action impacts other users, systems, or shared resources
`costly`	The action has significant resource consumption or financial implications
`experimental`	The action uses beta features or may have unpredictable results
`requires_confirmation`	The action should always prompt for explicit user confirmation

Response Message Structure

The response message transmits user decisions back to the originating service through the following fields:

{
  "notification_id": "550e8400-e29b-41d4-a716-446655440000",
  "action_id": "rollback",
  "response_data": null,
  "responded_at": "2025-05-25T10:35:12Z",
  "responder": {
    "id": "user_123",
    "type": "human"
  }
}

Field	Type	Required	Description
`notification_id`	string	Yes	UUID of the notification being answered
`action_id`	string	Yes	Selected action identifier from the notification
`response_data`	any	Conditional	User input data, type determined by action’s response_type
`responded_at`	datetime	Yes	ISO 8601 timestamp of response submission
`responder`	object	Yes	Object containing responder identification

The responder object contains:

Field	Type	Required	Description
`id`	string	Yes	Unique identifier of responding entity
`type`	string	Yes	Either “human” or “agent” to indicate responder type

The format of response_data depends on the response_type of the selected action. For simple actions, it must be null. For other response types, it must match the expected structure for that type. See the Response Types page for details on each type.

Fundamentals

Notifications & Message Formats

Overview

Triage Notification Structure

Core Notification Fields

Service Identification Object

Context Object

Context Attachments

Action Definition

Action Flags

Response Message Structure

Fundamentals

​Overview

​Triage Notification Structure

​Core Notification Fields

​Service Identification Object

​Context Object

​Context Attachments

​Action Definition

​Action Flags

​Response Message Structure

Overview

Triage Notification Structure

Core Notification Fields

Service Identification Object

Context Object

Context Attachments

Action Definition

Action Flags

Response Message Structure