# Core Concepts
This page defines the fundamental building blocks of the Amigo platform.
{% hint style="info" %}
**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](https://docs.amigo.ai).
{% endhint %}
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
{% @mermaid/diagram content="%%{init: {"flowchart": {"useMaxWidth": true, "nodeSpacing": 50, "rankSpacing": 60}, "theme": "base", "themeVariables": {"primaryColor": "#D4E2E7", "primaryTextColor": "#100F0F", "primaryBorderColor": "#083241", "lineColor": "#575452", "textColor": "#100F0F", "clusterBkg": "#F1EAE7", "clusterBorder": "#D7D2D0"}}}%%
flowchart TB
U\[User]
UM\[User Model]
S\[Service]
VS\[Version Set]
```
C[Conversation]
I[Interaction]
subgraph Messages[Message Types]
M1[User Message]
M2[Agent Message]
M3[Inner Thought]
M4[External Event]
end
T[Tools/Actions]
U -->|initiates| C
U -.has.-> UM
S -->|defines behavior| C
S -.configured by.-> VS
C -->|contains| I
I -->|streams| Messages
I -->|executes| T
UM <-->|personalizes| I
style U fill:#DDE3DB,stroke:#2c3827,color:#100F0F,stroke-width:3px
style S fill:#D4E2E7,stroke:#083241,color:#100F0F,stroke-width:3px
style C fill:#E8E2EB,stroke:#C5BACE,color:#100F0F,stroke-width:3px
style I fill:#E8E2EB,stroke:#C5BACE,color:#100F0F,stroke-width:3px
style T fill:#F0DDD9,stroke:#AA412A,color:#100F0F,stroke-width:3px
style UM fill:#D4E2E7,stroke:#083241,color:#100F0F,stroke-width:3px
style VS fill:#F1EAE7,stroke:#D7D2D0,color:#100F0F,stroke-width:2px
style Messages fill:#F0DDD9,stroke:#AA412A,color:#100F0F,stroke-width:1px
style M1 fill:#F0DDD9,stroke:#AA412A,color:#100F0F,stroke-width:1px
style M2 fill:#F0DDD9,stroke:#AA412A,color:#100F0F,stroke-width:1px
style M3 fill:#F0DDD9,stroke:#AA412A,color:#100F0F,stroke-width:1px
style M4 fill:#F0DDD9,stroke:#AA412A,color:#100F0F,stroke-width:1px" %}
```
### 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`
{% hint style="info" %}
**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](https://docs.amigo.ai/getting-started/amigo-overview/system-components).
{% endhint %}
## Platform API
{% @mermaid/diagram content="%%{init: {"flowchart": {"useMaxWidth": true, "nodeSpacing": 50, "rankSpacing": 60}, "theme": "base", "themeVariables": {"primaryColor": "#D4E2E7", "primaryTextColor": "#100F0F", "primaryBorderColor": "#083241", "lineColor": "#575452", "textColor": "#100F0F", "clusterBkg": "#F1EAE7", "clusterBorder": "#D7D2D0"}}}%%
flowchart TB
W\[Workspace]
AG\[Agent]
SK\[Skills]
SV\[Service]
VS\[Version Set]
VA\[Voice Agent
Phone Calls]
OP\[Operators]
WM\[World Model
Patient Data]
CR\[Connector Runner
EHR · FHIR Store · CRM Sync]
PN\[Phone Numbers]
```
W -->|contains| AG
W -->|contains| SK
W -->|contains| SV
SV -.configured by.-> VS
AG -->|powers| VA
SK -->|extend| AG
VA -->|escalates to| OP
VA -->|reads/writes| WM
CR -->|syncs| WM
PN -->|routes to| SV
style W fill:#DDE3DB,stroke:#2c3827,color:#100F0F,stroke-width:3px
style AG fill:#D4E2E7,stroke:#083241,color:#100F0F,stroke-width:3px
style SK fill:#F0DDD9,stroke:#AA412A,color:#100F0F,stroke-width:3px
style SV fill:#D4E2E7,stroke:#083241,color:#100F0F,stroke-width:3px
style VS fill:#F1EAE7,stroke:#D7D2D0,color:#100F0F,stroke-width:2px
style VA fill:#E8E2EB,stroke:#C5BACE,color:#100F0F,stroke-width:3px
style OP fill:#E8E2EB,stroke:#C5BACE,color:#100F0F,stroke-width:3px
style WM fill:#D4E2E7,stroke:#083241,color:#100F0F,stroke-width:3px
style CR fill:#D4E2E7,stroke:#083241,color:#100F0F,stroke-width:3px
style PN fill:#F0DDD9,stroke:#AA412A,color:#100F0F,stroke-width:2px" %}
```
### 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
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.amigo.ai/developer-guide/getting-started/core-concepts.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.