Skip to main content
Version: v1.0.0 (Draft)

Quick Start Guide

Get up and running with UAICP in minutes. This guide will walk you through the basics of understanding and using UAICP.

What You'll Learn​

  • How UAICP fits into the AI ecosystem
  • Core components and their roles
  • Basic usage patterns
  • Next steps for implementation

Understanding UAICP​

UAICP acts as a universal bridge between different AI systems and protocols. Instead of forcing everyone to use a single protocol, UAICP provides:

graph TB
    A[Your Application] --> B[UAICP Layer]
    B --> C[OpenAI API]
    B --> D[Anthropic MCP]
    B --> E[Google A2A]
    B --> F[Custom AI Service]

Core Components Overview​

1. Universal Discovery Mesh​

What it does: Finds AI services across different protocols and platforms.

// Example: Finding AI services that can handle text generation
const services = await discoveryMesh.findServices([
  { type: 'text-generation', quality: 'high' }
]);

2. Protocol Translation Hub​

What it does: Translates between different AI communication formats.

// Example: Translate OpenAI format to MCP format
const translated = await translationHub.translateMessage(
  openAIRequest, 
  'openai', 
  'mcp'
);

3. Adaptive Router​

What it does: Routes requests to the best available AI service.

// Example: Route based on capabilities and performance
const result = await router.routeMessage(request, {
  priority: 'high',
  fallbackAllowed: true
});

4. Capability Negotiator​

What it does: Matches your needs with available AI capabilities.

// Example: Find compatible capabilities
const compatibility = await negotiator.negotiateCapabilities(
  requiredCapabilities,
  availableCapabilities
);

Basic Usage Pattern​

Here's how a typical UAICP interaction works:

Step 1: Discover Services​

import { UAICP } from '@uaicp/client';

const uaicp = new UAICP();

// Find services that can handle your request
const services = await uaicp.discovery.findServices({
  capabilities: ['text-generation'],
  modalities: ['text'],
  quality: 'high'
});

Step 2: Route Your Request​

// Send your request through UAICP
const response = await uaicp.send({
  type: 'text-generation',
  content: 'Explain quantum computing',
  options: {
    maxTokens: 500,
    temperature: 0.7
  }
});

Step 3: Handle Response​

// UAICP handles all the protocol translation automatically
console.log(response.content); // Your AI-generated response
console.log(response.metadata.provider); // Which service actually handled it

Real-World Example​

Let's build a simple AI chat application that works with multiple providers:

import { UAICP } from '@uaicp/client';

class AIChat {
  private uaicp: UAICP;
  
  constructor() {
    this.uaicp = new UAICP({
      // Configure discovery preferences
      discovery: {
        preferredProviders: ['openai', 'anthropic', 'local'],
        fallbackEnabled: true
      }
    });
  }
  
  async chat(message: string): Promise<string> {
    try {
      // UAICP automatically finds the best available service
      const response = await this.uaicp.send({
        type: 'chat-completion',
        messages: [{ role: 'user', content: message }],
        options: {
          stream: false,
          maxTokens: 1000
        }
      });
      
      return response.content;
    } catch (error) {
      // UAICP provides detailed error context
      console.error('Chat failed:', error.details);
      throw error;
    }
  }
}

// Usage
const chat = new AIChat();
const response = await chat.chat("What's the weather like?");

Integration Examples​

With Existing OpenAI Code​

// Before: Direct OpenAI integration
const openai = new OpenAI({ apiKey: 'your-key' });
const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello' }]
});

// After: UAICP integration (with fallbacks to other providers)
const uaicp = new UAICP();
const response = await uaicp.send({
  type: 'chat-completion',
  messages: [{ role: 'user', content: 'Hello' }],
  hints: { preferredProvider: 'openai' } // Optional
});

With MCP Tools​

// UAICP can integrate with MCP tools seamlessly
const response = await uaicp.send({
  type: 'tool-use',
  tool: 'web-search',
  parameters: { query: 'UAICP documentation' },
  context: { source: 'mcp-compass' }
});

What Makes UAICP Different​

Traditional ApproachUAICP Approach
Lock-in to one providerMulti-provider flexibility
Manual failoverAutomatic routing & fallbacks
Protocol-specific codeUniversal interface
Limited discoveryCross-protocol discovery
Individual securityUnified security model

Next Steps​

Now that you understand the basics, here's where to go next:

📖 Learn More​

🛠️ Start Building​

🤝 Get Involved​

Need Help?​

Ready for the deep dive? Check out the complete specification next!