Core Concepts

This page explains the fundamental building blocks of the Cosmos platform. Understanding these concepts is essential for creating and deploying AI agents.

Organizations

An Organization is the top-level tenant boundary in Cosmos. All resources (agents, tools, apps, users) are scoped to an organization. Every API request must include an X-Org-Id header identifying the target organization. Organizations are managed by the User Service and support multi-tenant isolation — one Cosmos deployment can serve multiple independent organizations.

Projects

A Project groups resources and members inside an organization. Projects have their own roles, and each resource is either shared across the organization or kept inside one project. In the UI, the workspace selector scopes lists to the selected project.

Agents

An Agent is an AI entity that can converse with users, execute tools, and make decisions. Agents are configured in the Configurator with a prompt, an LLM provider/model, and a set of tools. At runtime, the ADK builds agents using Google ADK's agent framework, supporting multiple agent types:

• LlmAgent — standard conversational agent backed by an LLM
• SequentialAgent — runs sub-agents in sequence
• ParallelAgent — runs sub-agents in parallel
• LoopAgent — runs a sub-agent in a loop until a condition is met

Agents can be nested to form multi-agent hierarchies (orchestrator → specialists).

Tools

A Tool is an action an agent can invoke during a conversation. Tools are the bridge between an LLM's reasoning and the real world. Cosmos supports three tool types:

API Tools

REST API wrappers. You configure a URL, HTTP method, headers, and parameters in the Configurator. At runtime, MCP executes the HTTP call and returns the result to the agent.

Database Tools

SQL query tools. Configure a database connection (PostgreSQL, MySQL, Oracle, or SQL Server) or a set of CSV/XLSX files, and the agent can query data directly. The query is parameterized and executed by MCP.

Custom Tools

Pre-built integrations with external services (Twilio, Google Search, Salesforce, etc.). Custom tools use a @custom_tool decorator pattern and expose a configSchema for per-organization configuration.

Connector Tools

External MCP servers (GitHub, Gmail, Stripe, SAP HANA) configured per-organization. Connectors proxy tool calls to remote MCP-compatible servers.

💡 Tip: Tool names in MCP follow the format {org}-{type}-{name}-{major}_{minor} (e.g., test_organization-api-weather_tool-1_0).

Skills

A Skill is a reusable capability that can be attached to agents at runtime. Skills come from agentskills.io and follow a progressive discovery model (L1 → L2 → L3), where higher levels expose more detailed tool sets. Skills are integrated via Google ADK's SkillToolset.

Apps

An App is a deployable package that combines an orchestrator agent with configuration, guardrails, and metadata. Apps represent the top-level business entity that end users interact with, on a chat, voice, email, or WhatsApp channel. An app has:

• An orchestrator agent (the root of the agent hierarchy)
• A communication channel and its settings
• Guardrails (PII masking, content filtering)
• Industry and Framework metadata
• A version for deployment tracking

Collections (Knowledge Bases)

A Collection is a vector-indexed set of documents used for Retrieval-Augmented Generation (RAG). Collections are managed by the Configurator and processed by RAGflow. Documents are chunked, embedded, and stored in PostgreSQL with pgvector. Agents can search collections during conversations to ground their responses in organizational knowledge.

Graphs

A Graph is a structured knowledge representation that defines entity relationships. Graphs can be attached to agents to provide structured context beyond what RAG collections offer. They are managed in the Configurator.

Templates

A Template is a reusable configuration pattern for agents, tools, or prompts. The Configurator's library module provides a catalog of pre-built templates that can be cloned and customized. Templates accelerate the creation of common agent configurations.

Guardrails

Guardrails are safety mechanisms applied at the app or agent level. Cosmos supports:

• PII Masking — detects and masks personally identifiable information using Microsoft Presidio. Configured with entity types to detect and custom entity definitions.
• LLM-based Content Filtering — before/after model callbacks that evaluate content against safety policies.
• Rate Limiting — per-provider rate limits to prevent LLM API abuse.

Guardrails are configured in the Configurator and enforced at runtime by the ADK's GuardrailEngine.

BYOT (Bring Your Own Technology)

BYOT allows organizations to configure their own provider credentials for LLMs, STT, TTS, and other AI services. Instead of using platform-default credentials, organizations register their API keys through the Configurator's org settings. BYOT configurations are validated against provider-specific YAML schemas (byot_schemas/) and the credentials are resolved at runtime by ADK via the Configurator API.

Business Events

Business Events are domain-specific events defined per organization. They allow agents to trigger and respond to business workflows. Events have categories and are managed through the Configurator.

Org Settings

Org Settings are organization-level configuration values including BYOT credentials, default chat settings, and default guardrail configurations. These settings provide organization-wide defaults that individual agents and apps can override.

Library

The Library is a curated catalog of reusable agent templates, tool templates, and prompt templates. It provides a starting point for organizations to quickly build agents without starting from scratch. Library items can be browsed and cloned into an organization's own resources.

How Concepts Relate