Core Concepts

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 comprehensive understanding of how Context Graphs, Dynamic Behaviors, and Functional Memory work together, see our Conceptual Documentation.

Platform Architecture

The Amigo platform consists of API entities (how you interact with the system) and architectural components (how the system works internally).

API Entity Relationships

Understanding System Architecture For a comprehensive understanding of how Amigo's Agent System works internally (Agent Core, Context Graphs, Dynamic Behaviors, Functional Memory, Actions/Tools, and Evaluations), see our Conceptual Documentation.

Core Components

User

Represents 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

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.)

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 user message, followed by agent processing and response

• Delivery: Streaming events via NDJSON 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

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

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

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