AI Context Guide¶

ai_context = """
# Data Processing Agent - AI Orchestration Guide

## Endpoints

### 1. Process Data
POST /api/v1/process
Content-Type: application/json

Request:
{
    "data": "string or object - data to process",
    "format": "json|xml|csv - input format (default: json)",
    "output_format": "json|xml|csv - output format (default: json)",
    "async": "boolean - async processing (default: false)",
    "options": {
        "validate": "boolean - validate before processing",
        "transform": "string - transformation to apply",
        "callback_url": "string - webhook for async results"
    }
}

Response (sync):
{
    "status": "success|error",
    "result": "processed data",
    "metadata": {
        "processing_time_ms": 150,
        "items_processed": 100
    }
}

Response (async):
{
    "job_id": "uuid-string",
    "status_url": "/api/v1/status/{job_id}",
    "estimated_completion_time": "ISO-8601 datetime"
}

### 2. Check Status
GET /api/v1/status/{job_id}

Response:
{
    "job_id": "uuid-string",
    "status": "pending|processing|completed|failed",
    "progress": 0-100,
    "result": "available when completed",
    "error": "present if failed"
}

### 3. Batch Processing
POST /api/v1/batch
Content-Type: application/json

Request:
{
    "items": ["array of data items to process"],
    "max_concurrent": 10,
    "options": {...}
}

Response:
{
    "batch_id": "uuid-string",
    "total_items": 100,
    "status_url": "/api/v1/batch/status/{batch_id}"
}

## Orchestration Patterns

### Pattern 1: Quick Sync Processing
Use for: Small payloads (< 1MB), real-time needs
Steps:
1. POST to /process with async=false
2. Receive immediate response
Latency: < 5 seconds

### Pattern 2: Async Processing
Use for: Large payloads, complex processing
Steps:
1. POST to /process with async=true
2. Get job_id
3. Poll /status/{job_id} every 2-5 seconds
4. Retrieve result when status=completed
Latency: Variable, check estimated_completion_time

### Pattern 3: Batch Operations
Use for: Multiple items, efficiency needed
Steps:
1. Collect items (up to 1000 per batch)
2. POST to /batch
3. Get batch_id
4. Poll /batch/status/{batch_id}
5. Download results when ready
Efficiency: 10x faster than individual requests

## Authentication & Security
- Method: Bearer token authentication
- Header: Authorization: Bearer {token}
- Token endpoint: POST /auth/token (requires agent credentials)
- Token lifetime: 1 hour
- Refresh: Use refresh_token or re-authenticate

## Rate Limits
- Standard endpoints: 100 req/min
- Batch endpoint: 10 req/min
- Status checks: 300 req/min
- Headers returned: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

## Error Handling
HTTP Status Codes:
- 200: Success
- 400: Invalid request format
- 401: Authentication required
- 403: Insufficient permissions
- 404: Resource not found
- 429: Rate limit exceeded
- 500: Internal server error
- 503: Service temporarily unavailable

Retry Strategy:
- Retry on: 429, 500, 503
- Don't retry on: 400, 401, 403, 404
- Backoff: Exponential (1s, 2s, 4s, 8s, 16s)
- Max retries: 5 attempts

## Data Formats
Supported Input Formats:
- JSON: Recommended, fastest processing
- XML: Supported, slower than JSON
- CSV: Supported for tabular data
- Parquet: Supported for large datasets

Constraints:
- Max payload size: 100MB
- Max items per batch: 1000
- Max text field length: 1,000,000 characters

## Performance Characteristics
- Processing speed: ~1000 items/second
- Concurrent limit: 50 simultaneous requests
- Queue capacity: 10,000 pending jobs
- Typical latency: 100-500ms (sync), 1-60s (async)

## Integration Best Practices
1. Use batch endpoint for > 10 items
2. Implement exponential backoff for retries
3. Cache authentication tokens (1 hour lifetime)
4. Use async mode for payloads > 1MB
5. Include callback_url for async to avoid polling
6. Monitor X-RateLimit headers to avoid 429 errors
7. Implement timeout: 30s for sync, no timeout for async
8. Use HTTPS for all requests
9. Validate data before sending to reduce errors
10. Log job_id for async operations for debugging

## Webhook Callbacks (Async)
When callback_url provided in async request:
- Agent POSTs result to your URL when complete
- Payload: Same as /status response
- Headers: X-Job-ID, X-Agent-ID
- Signature: X-Signature header (HMAC-SHA256)
- Timeout: 10 seconds
- Retries: 3 attempts with exponential backoff

## Monitoring & Debugging
- Health check: GET /health
- Metrics: GET /metrics (Prometheus format)
- Logs: Include X-Request-ID header to trace requests
- Debug mode: Add ?debug=true for verbose responses
"""

from arcp import ARCPClient

# Create detailed AI Context
ai_context = """
Data Processing Agent v2.0

Endpoints:
- POST /process: Process single data item
  Input: {"data": "...", "format": "json|xml|csv"}
  Output: {"result": "...", "metadata": {...}}

- POST /batch: Process multiple items
  Input: {"items": [...], "max_concurrent": 10}
  Output: {"batch_id": "...", "status_url": "..."}

Orchestration:
- Use /process for real-time (< 5s response)
- Use /batch for large volumes (> 10 items)
- Async mode available: set "async": true

Rate Limits: 100/min (process), 10/min (batch)
Auth: Bearer token required
Max payload: 100MB per request

Error Handling:
- 429: Wait X-RateLimit-Reset seconds
- 5xx: Retry with exponential backoff
- 4xx: Fix request and retry

Best for: Data transformation, format conversion, validation
"""

# Register agent with AI context
client = ARCPClient("https://arcp.example.com")

agent = await client.register_agent(
    agent_id="data-processor-v2",
    name="Data Processor",
    agent_type="processing",
    endpoint="https://api.example.com",
    capabilities=["data-processing", "transformation", "validation"],
    context_brief="Processes and transforms data",  # Human-readable
    ai_context=ai_context,  # AI-readable
    version="2.0.0",
    owner="Data Team",
    public_key="test-public-key-123456789012345678901234567890",
    communication_mode="remote",
    metadata={"version": "2.0", "stable": True},
    agent_key="your-registration-key",
)

print(f"Registered agent: {agent.agent_id}")