Overview

This guide will help you quickly get started with implementing the Agent Triage Protocol (ATP) in your application. Follow these steps to set up your service, send notifications, and process responses.

Prerequisites

Before you begin, make sure you have:

An API key from an ATP server provider (or your own deployment)
A public endpoint for receiving webhooks (for production use)
Basic knowledge of REST APIs and asynchronous programming

Step 1: Install the SDK

ATP implementations are available for various programming languages. Choose the SDK that best fits your technology stack:

# For Node.js applications
npm install @atp/client

# For Python applications
pip install atp-client

Step 2: Initialize the Client

Create and configure an ATP client in your application:

from atp import ATPClient

# Initialize with your API key
client = ATPClient(
    api_key="sk_live_service_abc123",
    webhook_url="https://your-service.com/atp/webhook"
)

Step 3: Register Your Service

Before sending notifications, register your service with the ATP server:

# Register your service
service_registration = client.register_service(
    name="My AI Assistant",
    description="AI assistant that helps with data analysis",
    icon_url="https://your-service.com/icon.png",
    callback_url="https://your-service.com/atp/webhook"
)

# Store the service ID for future use
service_id = service_registration.service_id

Step 4: Create and Send a Notification

Now you can create and send notifications to users:

from atp import TriageNotification, Action, ResponseType
from datetime import datetime, timedelta

# Create a notification
notification = TriageNotification(
    title="Approve Data Export",
    description="A request to export customer data has been received. Please review and approve.",
    actions=[
        Action(
            id="approve",
            label="Approve",
            response_type=ResponseType.SIMPLE
        ),
        Action(
            id="reject",
            label="Reject",
            response_type=ResponseType.TEXT,
            constraints={"placeholder": "Reason for rejection"}
        )
    ],
    deadline=datetime.now() + timedelta(hours=2),
    priority="high",
    metadata={
        "request_id": "export-12345",
        "data_size": "2.3GB",
        "requester": "data-science-team"
    }
)

# Send the notification
response = client.send_notification(notification)
notification_id = response.notification_id

Step 5: Handle Webhook Responses

Set up a webhook endpoint to receive responses:

# Using Flask as an example web framework
from flask import Flask, request, jsonify
import hmac, hashlib

app = Flask(__name__)

@app.route('/atp/webhook', methods=['POST'])
def handle_webhook():
    # Verify webhook signature
    payload = request.data
    signature = request.headers.get('X-ATP-Signature')
    expected_signature = hmac.new(
        bytes(client.webhook_secret, 'utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()
    
    if not hmac.compare_digest(expected_signature, signature):
        return jsonify({'error': 'Invalid signature'}), 403
    
    # Process the webhook payload
    data = request.json
    notification_id = data.get('notification_id')
    action_id = data.get('action_id')
    response_data = data.get('response_data')
    
    # Handle the response based on your application logic
    print(f"Received response for notification {notification_id}")
    print(f"User selected action: {action_id}")
    print(f"Response data: {response_data}")
    
    # Acknowledge receipt of the webhook
    return jsonify({'status': 'success'}), 200

Step 6: Check Notification Status

You can also check the status of a notification:

# Check notification status
status = client.get_notification_status(notification_id)
print(f"Notification status: {status.state}")
print(f"Responded: {status.responded}")
if status.responded:
    print(f"Action selected: {status.action_id}")
    print(f"Response data: {status.response_data}")

Next Steps

Congratulations! You’ve implemented the basic functionality of the Agent Triage Protocol in your application. Here are some resources to explore next:

Your First Notification

Detailed tutorial on creating and sending your first notification

Response Types

Learn about the different response types and how to use them

Authentication

Understand the authentication mechanisms in ATP

Error Handling

Learn how to handle errors and edge cases

API Reference

View the complete API specification

Documentation Index

​Overview

​Prerequisites

​Step 1: Install the SDK

​Step 2: Initialize the Client

​Step 3: Register Your Service

​Step 4: Create and Send a Notification

​Step 5: Handle Webhook Responses

​Step 6: Check Notification Status

​Next Steps