Core Concepts
Understand the building blocks of both APIs: users, services, conversations, tools, workspaces, and skills.
This page defines the fundamental building blocks of the Amigo platform.
Understanding Amigo's architecture These API concepts map to Amigo's deeper architectural components. For a full understanding of how Context Graphs, Dynamic Behaviors, and Functional Memory work together, see the Conceptual Documentation.
The Amigo platform has two API surfaces with shared core concepts. The Classic API is built for text-based digital health products. The Platform API is built for enterprise voice and traditional healthcare.
Classic API
Setup
Service
A configured AI experience with specific agent behavior and business logic.
Purpose: Defined experiences like onboarding, support, or sales
Identification: Unique
service_idDeployment: Version sets (
release,staging, etc.)
Version Sets
Named deployment configurations for services.
Examples:
release,staging,developmentSelection: Specified during conversation creation
Purpose: Environment isolation and controlled rollouts
Tools (Actions)
Custom programs that execute during interactions to perform work beyond conversation.
Execution: Run in isolated environments with custom dependencies
Scope: Organization-scoped and versioned
Purpose: Database queries, API calls, calculations, external system integration
Invocation: Called by agents during interactions to accomplish tasks
Dynamic Behaviors (Triggers)
Runtime events for external system integration.
Emission: Streamed as
dynamic-behavior-triggeredeventsPurpose: Business logic integration and metrics evaluation
Usage: Webhook triggers, system actions, and custom workflows
Users
User
An individual end-user interacting with Amigo.
Identification: Unique
user_idmapped to your internal user IDPermissions: Single role-based access control
Context: Associated user model and preferences
User Model
Amigo-managed knowledge representation of each user.
Management: Automatically maintained and evolved by Amigo
Content: Rich, structured user knowledge and preferences
Extension: Augmentable via
additional_contextparameters
Conversations
Conversation
A time-bounded session between a user and an AI agent.
Scope: User-agent interaction within a service context
Structure: Sequential messages and interactions
Constraint: Maximum one active conversation per user per service
Interaction
A single exchange within a conversation.
Components: Can include user messages, agent messages, agent inner thoughts, and external events
Structure: Typically initiated by a user message, followed by agent processing and response
Delivery: Streaming events via NDJSON (newline-delimited JSON) over HTTP
Events: Real-time status updates, content chunks, and message fragments
Messages
Atomic units of conversation content.
Types: User messages, agent messages, agent inner thoughts, external events
Origin: User-generated, agent-generated, or system-generated
Format: Text or voice based on configuration
Parameters:
request_formatandresponse_format
Understanding system architecture For a detailed look at how Amigo's agent system works internally (Agent Core, Context Graphs, Dynamic Behaviors, Functional Memory, Actions/Tools, and Evaluations), see the Conceptual Documentation.
Platform API
Setup
Workspace
The top-level organizational unit in the Platform API, equivalent to an Organization in the Classic API.
Scoping: All Platform API resources belong to a workspace
Mapping: Links to a Classic API organization via
backend_org_idAuthentication: Workspace-scoped API keys (Bearer token)
Skills
LLM-backed micro-agents that extend agent capabilities.
Configuration: System prompt, input/output schema, model selection
Execution tiers: Direct, orchestrated, autonomous, browser
Different from Classic Tools: Skills are declarative and LLM-native, while Classic Tools are versioned code packages
Voice and Operations
Voice Agent
Phone-based conversational AI for inbound and outbound calls.
Capabilities: Real-time emotion detection, EHR context, operator escalation
Pipeline: Audio capture, STT, context graph engine, TTS, post-call analysis
Different from Classic voice: Classic offers WebSocket streaming for text apps; Platform handles phone calls
Operators
Human agents who can join, monitor, and take over live voice calls.
Modes: Listening (silent monitoring) and on-call (active takeover)
Connection: Phone (PSTN, the Public Switched Telephone Network) or browser (WebRTC)
Escalation: Triggered by safety rules, patient request, or agent uncertainty
Data
World Model
Event-sourced patient data store that unifies information from multiple sources.
Sources: EHR imports, voice conversations, connector sync, manual entry
Confidence scoring: Each data point carries a trust level (EHR, human, AI, inferred)
Different from Classic data access: Classic uses SQL over relational tables; Platform uses event-sourced projections
Connector Runner
Background sync engine for bidirectional data exchange with external systems.
Capabilities: EHR, FHIR store, and CRM polling; outbound writes via handler registry; entity resolution (matching records from different systems to the same real-world entity); deduplication
Safety: Three-layer confidence gates before writing back to external systems
Automated review: LLM-based judge for data quality before sync
Last updated
Was this helpful?

