Compass — Agent Provisioning Service¶

Service name in code

Compass is the internal name for ai-provisioning-service, registered in Call Service as @FeignClient(name = "ai-provisioning-service") and referenced in Atlas via env var LIVEKIT_AI_PROVISIONING_API_URL.

Language: Python 3.9+
Framework: FastAPI
Source: ~/PycharmProjects/AI/compass

Purpose¶

Compass is the control plane for AI agent lifecycle management. It stores and serves agent configuration records, manages the knowledge base, handles prompt component assembly, and provisions human agents and SIP trunks.

Responsibilities¶

Responsibility	Implementation
Agent CRUD	`POST/GET/PATCH/DELETE /tenants/agents`
Prompt assembly	Modular `prompt_components` table, assembled at read time
Knowledge base	Categories, articles, vector embeddings (Qdrant)
Skills / tool registration	`agent_skills` table, returned in agent config
Human agent provisioning	WebRTC + SIP config, LiveKit SIP trunk management
Multi-tenant isolation	`tenant_id` on all tables, enforced via `x-tenantId` header
Agent insights	Audit log, config history, analytics

Agent Data Model¶

`agents` table¶

Field	Type	Description
`agent_id`	UUID	Primary key
`tenant_id`	VARCHAR	Multi-tenant isolation key
`agent_name`	VARCHAR	Unique agent identifier
`agent`	VARCHAR	Agent role (e.g. `"customer support agent"`)
`agent_prompt`	TEXT	Main system prompt (STT-LLM-TTS pipeline mode)
`prompt_realtime`	TEXT	Assembled prompt for audio-native model (realtime mode)
`agent_type`	VARCHAR	`inbound` or `outbound`
`agent_category`	VARCHAR	`ai_ivr`, `ai_agent`, or `human_agent`
`status`	VARCHAR	`active`, `inactive`, `provisioning`, `failed`
`model`	VARCHAR	Default LLM model (e.g. `models/gemini-2.5-flash-live-preview`)
`language`	JSONB	Array of BCP-47 codes (e.g. `["en", "ar"]`)
`base_greeting`	JSONB	Per-language greetings: `{"en": "Hello!", "default": "Hi!"}`
`mcp_server_url`	VARCHAR	MCP tool orchestration server URL
`outbound_purpose`	TEXT	Objective for outbound agents
`outbound_variables`	JSONB	Runtime variable templates: `[{key, label}]`
`human_in_loop`	TEXT	Transfer trigger condition (e.g. `"Transfer when caller is frustrated"`)
`metadata`	JSONB	See metadata structure below
`routing_config`	JSONB	Call routing rules
`config_version`	INT	Incremented on every update

`metadata` structure¶

{
  "voice_config": {
    "voice": "Zephyr",
    "language": "en-IN",
    "temperature": 0.6,
    "max_output_tokens": 10240,
    "llm_model": "gemini-3-flash-preview",
    "stt_provider": "groq",
    "tts_provider": "google",
    "pipeline_mode": "stt_llm_tts"
  },
  "avatar_url": "https://...",
  "personality": {
    "tone": ["professional", "empathetic"],
    "authority": ["inform", "recommend"],
    "communication": ["clear", "concise"]
  },
  "organization_name": "Nexivo"
}

pipeline_mode is either stt_llm_tts (default) or realtime (audio-native model, lower latency).

Prompt Component System¶

Prompts are stored as modular components rather than monolithic strings. Atlas assembles them at runtime by sorting on priority and concatenating.

Component Type	Priority	Purpose
`base`	10–30	Core agent identity
`base_prompt_voice`	11	Voice/audio channel rules
`base_prompt_chat`	12	Text/chat channel rules
`feature`	50	Optional capabilities
`language`	60	Per-language conversation styles
`escalation`	90	Human handoff rules
`guard`	100	Hallucination / security guardrails
`tool_prompt`	110+	Per-tool usage instructions

Assembly: Atlas fetches components sorted by priority, concatenates them, and injects into the LLM system message. The prompt_realtime field is a pre-assembled final prompt used for audio-native models (immutable per session).

Agent Skills¶

Skills are registered tools the LLM can call. Returned in the agent config as agent_skills.

{
  "skill_id": "uuid",
  "agent_id": "uuid",
  "tenant_id": "string",
  "title": "Appointment Booking",
  "tool_name": "appointment_booking",
  "description": "Books medical appointments",
  "is_active": true,
  "activation_mode": "always | on_demand",
  "prompt": "Tool-specific usage instructions..."
}

Atlas registers active skills (is_active=true) as RawFunctionTools and makes them available to the LLM via the MCP tool server.

Knowledge Base¶

Structure¶

knowledge_categories  (1:many)  knowledge_articles
       |
agent_knowledge_assignments  (many:many with agents)
       |
agent_knowledge_chunks  (vector embeddings via Qdrant)

Vector Search¶

Articles are chunked (smart or simple strategy) and embedded via Google Gemini
Embeddings stored in Qdrant (768-dim vectors), one collection per {tenant}_{agent_id}
Semantic search via GET /knowledge/search
Embedding pipeline: article created/updated → embedding_outbox job → background worker → Qdrant upsert

Article Types¶

Type	Description
Standard	Title + text content
Table	Structured row/column data
Imported	Scraped from URL / parsed from PDF or DOCX via Firecrawl

REST API¶

Agents¶

Method	Path	Purpose
`POST`	`/tenants/agents`	Create agent (multipart/form-data)
`GET`	`/tenants/agents`	List agents for tenant
`GET`	`/tenants/agents/{agent_id}`	Get agent by ID (used by Atlas at call start)
`GET`	`/tenants/agents/name/{agent_name}`	Get agent by name
`PATCH`	`/tenants/agents/{agent_id}`	Update agent
`DELETE`	`/tenants/agents/{agent_id}`	Delete agent

Agent create fields (multipart): agent, agent_name, agent_prompt, mcp_server_url, agent_type, language (JSON array string), model, metadata (JSON), base_greeting, outbound_purpose, outbound_variables, human_in_loop, avatar_file, voice_file

Skills¶

Method	Path	Purpose
`POST`	`/tenants/agents/{agent_id}/skills`	Register a tool skill
`GET`	`/tenants/agents/{agent_id}/skills`	List skills
`PATCH`	`/tenants/agents/{agent_id}/skills/{skill_id}`	Update skill
`DELETE`	`/tenants/agents/{agent_id}/skills/{skill_id}`	Delete skill

Knowledge¶

Method	Path	Purpose
`POST/GET/PATCH/DELETE`	`/knowledge/categories`	Category management
`POST/GET/PATCH/DELETE`	`/knowledge/articles`	Article management
`POST`	`/knowledge/articles/import`	Import from URL / PDF / DOCX
`POST`	`/knowledge/assign`	Assign category to agent
`DELETE`	`/knowledge/assign`	Unassign category from agent
`GET`	`/knowledge/search`	Vector semantic search

Human Agents & SIP¶

Method	Path	Purpose
`POST`	`/human-agents`	Create human agent (WebRTC or SIP)
`GET`	`/tenants/{tenant_id}/human-agents`	List tenant's human agents
`POST/GET/PATCH/DELETE`	`/tenants/sip-trunks`	SIP trunk management

Tenants & Health¶

Method	Path	Purpose
`POST`	`/tenants/`	Create tenant
`GET`	`/health`	Health check
`GET`	`/metrics`	Prometheus metrics

Agent Creation Flow¶

sequenceDiagram
    participant Client
    participant Compass
    participant Gemini
    participant DB as PostgreSQL
    participant Qdrant

    Client->>Compass: POST /tenants/agents (multipart)
    Compass->>Compass: Validate prompt (malicious content check)
    Compass->>Compass: Map language names → BCP-47 codes
    Compass->>DB: INSERT agent (status=provisioning)
    Compass-->>Client: AgentResponse (status=provisioning)

    Note over Compass,Gemini: Background prompt generation
    Compass->>Gemini: Generate prompt components
    Gemini-->>Compass: Components (base, language, escalation, guards)
    Compass->>DB: INSERT prompt_components
    Compass->>DB: UPDATE agent (status=active)

External Dependencies¶

Dependency	Purpose
PostgreSQL + pgvector	Agent config, knowledge articles, prompt components
Qdrant	Vector embeddings for knowledge search
Google Gemini	Prompt generation, text embeddings
Groq Whisper	STT (referenced in voice_config)
Google Cloud TTS	TTS (referenced in voice_config)
LiveKit Agents SDK	Human agent / SIP trunk provisioning
S3-compatible storage	Avatar and voice file uploads
Tool Management Service	External tool registry (`TOOL_MANAGEMENT_SERVICE_URL`)
Firecrawl API	Web scraping for article import

Key Environment Variables¶

POSTGRES_HOST=postgres
POSTGRES_DB=atlas_agents
POSTGRES_USER=atlas_user
POSTGRES_PASSWORD=...

QDRANT_URL=http://qdrant:6333
GEMINI_API_KEY=...
GEMINI_VECTOR_SIZE=768

LIVEKIT_URL=http://localhost:7880
LIVEKIT_API_KEY=...
LIVEKIT_API_SECRET=...

TOOL_MANAGEMENT_SERVICE_URL=http://localhost:8081
BASE_MCP_URL=https://mcp.nexivo.dev.cognitry.io/mcp/