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_id

• Deployment: Version sets (release, staging, etc.)

Version Sets

Named deployment configurations for services.

• Examples: release, staging, development

• Selection: 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-triggered events

• Purpose: 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_id mapped to your internal user ID

• Permissions: 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_context parameters

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_format and response_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_id

• Authentication: 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