Skip to main content

​
Welcome to ATP Development

The Agent Triage Protocol (ATP) enables AI services to request human input through a standardized notification system. This comprehensive guide will walk you through implementing ATP in your applications, from basic setup to advanced patterns.

​
What You’ll Learn

This guide is designed for developers who want to integrate ATP into their applications. By the end of this guide, you will be able to:
  • Set up and configure ATP clients for your environment
  • Register services and handle authentication
  • Create and send notifications with various response types
  • Process responses securely
  • Implement advanced patterns like the decorator-based approach
  • Follow best practices for security, performance, and user experience
Each section builds on the previous ones, taking you from a complete beginner to an advanced ATP implementer.

​
Core Concepts for Developers

Before diving into implementation details, let’s review the key concepts from a developer’s perspective:

​
The ATP Architecture

ATP consists of three main components:
  1. AI Services (Senders) - Applications that need human input
  2. ATP Servers - Central coordination points that manage notifications
  3. Client Applications (Receivers) - Applications that display notifications to users
As a developer, you’ll typically work with the first component (AI Services) to send notifications and process responses. The ATP Server handles the delivery to clients, and the Client Applications present notifications to users and collect their responses.

​
How ATP Works for Developers

From a developer’s perspective, the typical ATP workflow looks like this:

​
Key Benefits for Developers

Using ATP provides several advantages:
  • Simplified User Interaction: Focus on your core service logic instead of building notification systems
  • Standardized Response Collection: Reliable, type-safe ways to collect user input
  • Asynchronous Workflows: Enable AI services to continue running while waiting for human input
  • Cross-Platform Support: Reach users on any device that has an ATP-compatible client
  • Separation of Concerns: Decouple your service logic from user notification handling

​
Types of ATP Integrations

There are several ways to integrate ATP into your applications:

​
1. Service Integration

This is the most common use case, where your AI service sends notifications and processes responses: 
# Example of a basic service integration
from atp import ATPClient

client = ATPClient(api_key="sk_live_service_abc123")

# Send a notification
response = client.send_notification({
    "title": "Approve File Deletion",
    "description": "AI assistant wants to delete unused files to free up space",
    "actions": [
        {"id": "approve", "label": "Approve", "response_type": "simple"},
        {"id": "reject", "label": "Reject", "response_type": "simple"}
    ]
})

# Store notification_id for correlating with webhook responses
notification_id = response["notification_id"]

​
2. Client Integration

Building client applications that display ATP notifications to users: 
// Example of a client integration
import { ATPClient } from '@atp/client';

const client = new ATPClient({
  token: 'user_auth_token',
  transport: 'websocket'
});

// Listen for notifications
client.onNotification((notification) => {
  // Display the notification to the user
  displayNotification(notification);
});

// Submit user responses
function submitResponse(notificationId, actionId, responseData) {
  client.respond(notificationId, actionId, responseData)
    .then(() => console.log('Response submitted'))
    .catch(err => console.error('Error submitting response', err));
}

​
3. Hybrid Integration

Applications that both send notifications and receive responses: 
# Example of a hybrid integration
from atp import ATPClient

# Initialize with both service and client capabilities
client = ATPClient(
    api_key="sk_live_service_abc123",  # For sending notifications
    user_token="user_token_xyz"        # For receiving notifications
)

# Send notifications as a service
notification_id = client.send_notification({...})

# And also listen for notifications as a client
client.start_listening()
client.on_notification(handle_notification)

​
Who Should Use This Guide

This guide is designed for:
  • AI Service Developers: Building AI systems that need human input
  • DevOps Engineers: Setting up ATP infrastructure and integrations
  • Application Developers: Integrating ATP into existing applications
  • Platform Developers: Building systems that will use ATP for user interaction
You should have basic knowledge of:
  • REST APIs and asynchronous programming
  • Your preferred programming language (Python, JavaScript, etc.)
  • Web development concepts like webhooks and authentication

​
Learning Path

This guide is organized to take you through the complete journey of implementing ATP:
  1. Getting Started - Installation and basic setup
  2. Service Registration - Registering your service with an ATP server
  3. Creating Notifications - Designing and sending effective notifications
  4. Processing Responses - Handling user responses securely
  5. Advanced Patterns - Using advanced features like decorators
  6. Client Implementation - Building applications that display notifications
  7. Best Practices - Ensuring security, performance, and user experience
  8. Troubleshooting - Solving common issues
Each section includes practical examples and verification steps to ensure you’re on the right track.

​
Verification: Knowledge Check

Before proceeding, let’s verify your understanding of ATP’s core concepts: If you understand these concepts, you’re ready to move on to the next section and start implementing ATP in your applications.

​
Next Steps

Now that you understand the core concepts of ATP, you’re ready to begin setting up your environment and installing the necessary tools.

Getting Started with ATP

Learn how to install, configure, and test your ATP client setup
⌘I