> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/getting-started/core-concepts.md).
# 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
%%{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/platform-overview/how-it-works).
{% endhint %}
## Platform API
```mermaid
%%{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 · REST Sources]
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)
Agent
The conversational persona that drives sessions in a workspace.
* **Configuration**: A core persona (identity, tone, guardrails) plus a context graph that structures conversation flow
* **Extension**: Skills attach to agents to add capabilities
* **Deployment**: Services bind an agent to a channel; version sets control which configuration is live
Context Graph
A state machine that structures conversation flow and agent reasoning.
* **Structure**: Each state defines what the agent focuses on and which tools it can call at that point in the conversation
* **Transitions**: Rules that move the conversation between states as it progresses
* **Reference**: See [Context Graphs](https://docs.amigo.ai/agent/context-graphs) in the conceptual documentation
Skills
LLM-backed micro-agents that extend agent capabilities.
* **Configuration**: System prompt, input/output schema, model selection
* **Execution**: Skills run as multi-turn LLM agents that can call their configured static and integration tools - see [Skills](/developer-guide/platform-api/workspaces/skills.md) for the configuration surface
* **Different from Classic Tools**: Skills are declarative and LLM-native, while Classic Tools are versioned code packages
Phone Numbers
Provisioned phone numbers that route inbound calls to a service.
* **Routing**: Each number maps to a service, which determines the agent and configuration that answers the call
**Service** and **Version Set** carry the same definitions as in the Classic API above: a service is a configured AI experience, and version sets control which configuration is deployed.
### 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**: supported EHR, FHIR, REST, and workspace-data polling; policy-eligible delivery through connector-specific handlers; entity resolution; and source-specific deduplication
* **Safety**: Source eligibility, confidence, schema, and destination rules on unattended writes
* **Human approval**: Selected destinations can stage a private-preview external write proposal for an authorized reviewer; this decision is separate from event confidence
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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, and the optional `goal` query parameter:
```
GET https://docs.amigo.ai/developer-guide/getting-started/core-concepts.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.