Skip to main content

​
Installation and Setup

Getting started with ATP involves installing the appropriate SDK for your programming language, configuring your environment, and making your first test connection.

​
SDK Installation

ATP offers client libraries for multiple programming languages. Choose the one that best suits your project:

​
Python

pip install agent-triage-protocol

​
JavaScript/Node.js

npm install @atp/client
# or using yarn
yarn add @atp/client
If your preferred language isn’t listed above, you can use the REST API directly.

​
Authentication Setup

ATP uses API keys for authentication. You’ll need two types of credentials:
  1. Service API Key - For sending notifications
  2. Client Token - For receiving notifications (if you’re building a client application)

​
Obtaining API Keys

  1. Register for an ATP account at https://atp.example.com/signup
  2. Navigate to the “API Keys” section in your dashboard
  3. Generate a new Service API Key for your service
  4. Store this key securely - it won’t be displayed again

​
Environment Configuration

It’s best practice to store your API keys in environment variables: 
# For development
export ATP_API_KEY="sk_test_your_key_here"

# For production
export ATP_API_KEY="sk_live_your_key_here"
For client applications, you’ll typically handle user authentication separately and exchange user tokens for ATP client tokens through your backend.

​
Basic Client Configuration

Once you have your API key, you can initialize the ATP client:

​
Python

from atp import ATPClient

# Initialize with environment variable
client = ATPClient()

# Or explicitly provide the API key
client = ATPClient(api_key="sk_live_your_key_here")

# Configure additional options
client.configure(
    timeout=30,  # Request timeout in seconds
    retry_attempts=3,  # Number of retry attempts
    webhook_url="https://your-service.com/atp/webhook",  # For receiving responses
    environment="production"  # 'production' or 'development'
)

​
JavaScript/Node.js

import { ATPClient } from '@atp/client';

// Initialize with environment variable
const client = new ATPClient();

// Or explicitly provide the API key
const client = new ATPClient({
  apiKey: 'sk_live_your_key_here',
  timeout: 30000, // milliseconds
  retryAttempts: 3,
  webhookUrl: 'https://your-service.com/atp/webhook',
  environment: 'production'
});

​
Service Registration

Before sending notifications, you need to register your service with the ATP server. This only needs to be done once per service: 
# Python example
registration_result = client.register_service({
    "name": "My AI Assistant",
    "description": "AI assistant that helps with file management",
    "icon_url": "https://your-service.com/icon.png",
    "webhook_url": "https://your-service.com/atp/webhook",
    "webhook_secret": "your_webhook_secret"  # For verifying webhook signatures
})

print(f"Service registered with ID: {registration_result['service_id']}")
Store the returned service_id securely - you’ll need it for configuration.

​
Verification Test

Let’s verify your setup by sending a test notification: 
# Python example
try:
    response = client.send_notification({
        "title": "Test Notification",
        "description": "This is a test notification from ATP setup",
        "priority": "normal",
        "actions": [
            {
                "id": "acknowledge",
                "label": "Acknowledge",
                "response_type": "simple"
            }
        ],
        "metadata": {
            "test": True,
            "setup": "initial"
        }
    })
    
    notification_id = response["notification_id"]
    print(f"Test notification sent successfully! ID: {notification_id}")
    
    # In a real application, you would wait for the webhook response
    # For testing, you can use the check_status method
    status = client.check_status(notification_id)
    print(f"Notification status: {status['status']}")
    
except Exception as e:
    print(f"Error sending test notification: {e}")

​
Testing Webhook Responses

If you want to test the full workflow including responses, you’ll need:
  1. A publicly accessible webhook endpoint (use tools like ngrok for development)
  2. A test client application to respond to the notification
For development, ATP also provides a test client that can automatically respond to notifications: 
from atp.testing import TestClient

test_client = TestClient()

# Automatically respond to all notifications with the first action
test_client.auto_respond()

# Or respond to specific notifications
test_client.respond_to(notification_id, "acknowledge")

​
Common Setup Issues

​
API Key Errors

If you receive authentication errors:
  • Verify your API key is correct and not expired
  • Ensure you’re using the right key type (test vs. live)
  • Check that your environment variables are properly set

​
Webhook Configuration

For webhook delivery issues:
  • Ensure your webhook URL is publicly accessible
  • Verify your server properly responds with a 200 OK status
  • Check for firewall or security settings that might block incoming requests

​
Network Issues

If you’re experiencing timeouts or connection problems:
  • Check your network connectivity
  • Verify that outbound connections to the ATP API are allowed
  • Consider increasing the timeout configuration if you have high latency

​
Environment-Specific Considerations

​
Development Environment

  • Use environment="development" in your configuration
  • Use test API keys (prefixed with sk_test_)
  • Set lower timeouts for faster debugging

​
Production Environment

  • Use environment="production" in your configuration
  • Use production API keys (prefixed with sk_live_)
  • Configure appropriate timeouts and retry logic
  • Implement proper error handling and logging

​
Verification: Knowledge Check

Before proceeding, let’s verify your understanding of the ATP setup process: If you understand these concepts and have successfully set up your environment, you’re ready to move on to creating and sending actual notifications.

​
Next Steps

Now that you have your ATP client set up and tested, you’re ready to dive deeper into creating effective notifications and handling responses.

Creating Notifications

Learn how to design and send effective notifications
⌘I