Configurator

The Configurator (cosmos-configurator-v3) is the central configuration service of the Cosmos platform. Built on Django and Django REST Framework, it provides APIs for every configurable resource: tools, agents, apps, analyzers, collections, graphs, data sources, skills, templates, guardrails, connectors, evaluations, organization settings, and the library. It is the source of truth for platform configuration; other services read a cached or synced copy of what Configurator owns.

Why It Matters

Nothing in Cosmos runs without Configurator. MCP syncs tools from it, ADK loads agents, apps, skills, and BYOT model credentials from it, and every deploy is a Configurator write that fans out to those services over Kafka. If a resource misbehaves at runtime, Configurator shows what is actually deployed.

Architecture

• Framework: Django 5.2.18 and DRF 3.18.2, using the ViewSet, service layer, and model pattern. The web server runs under uWSGI.
• Multi-tenancy: every resource is scoped by org_id through the get_current_user() thread-local middleware.
• Project scope: when a request sends X-Project-Id, agents, apps, collections, graphs, and analyzers are filtered to resources enabled in that project, and detail routes return 404 for resources that are not enabled. Newly created agents and apps are bound to the project. Enablement is cached locally from the User Service user-project-enablement Kafka events.
• Domain apps: tool, agent, app, analyzer, collection, graph, data_source, skill, template, business_event, org_settings, org, library, guardrails, connector, evaluation, project_enablement, and core.
• Kafka producer: configuration changes emit events to the configurator topic, using the @register_event_serializer pattern. Versioned configurations emit <model>.configuration.added, <model>.configuration.updated, <model>.configuration.deployed, and <model>.deleted (for example agent.configuration.deployed or api_tool.configuration.added). Changes also publish Recent Activity envelopes to the activity topic (KAFKA_ACTIVITY_TOPIC).
• Consumer process: the standalone consumer.py boots Django and dispatches Kafka messages by event_type; it runs as the configurator-consumer container.
• Observability: the web server and consumer run under opentelemetry-instrument and export to Azure Monitor through APPLICATIONINSIGHTS_CONNECTION_STRING. The image installs dependencies into /app/.venv.

Key Capabilities

• Tools, agents, apps: polymorphic tool types (api, db, custom, dispatched through TOOL_TYPE_MAP) and versioned agent and app configurations. Deploys publish Kafka events. Tools can require approval before ADK runs them (requires_approval). See the Tools API, Agents API, and Apps API.
• Agent settings for ADK: agents carry the runtime settings ADK enforces, including context_window_tokens, compaction settings, prompt_caching, prompt_caching_history, dynamic_thinking_enabled, headroom_compression_enabled, thinking mode, and reasoning effort. Workflow agents use type: workflow with workflow_kind (sequential, parallel, loop, or graph).
• Analyzers: versioned analyzers (/api/v1/analyzers/) attach to agent versions through analyzer_id and analyzer_version. They replace agent-level business events, which are read-only on agents.
• Knowledge Base (Collections): RAG document sets backed by cosmos-ragflow-v3, with lifecycle status (pending, indexing, ready, or failed), BYOT-configurable embeddings, and deletion protection while an agent references them.
• Graphs: knowledge graphs built from DMS files through RAGflow, with entity and relationship extraction and the same deletion protection as collections.
• Evals: datasets, metric templates, experiments, and online evaluation policies under /api/v1/evals/. ADK runs experiments and writes results back.
• Business Events: structured domain events with categories, versioned and deployable like other resources.
• Library: prompt, tool, and agent catalogs (/api/v1/prompt-library/, /api/v1/tool-library/, /api/v1/agent-library/) that organization users can browse and clone into their organization.
• Skills and Templates: agentskills.io-spec skills (L1 name and description, L2 instructions, L3 resources and scripts) and placeholder-based templates, both versioned and deployable.
• Guardrails: the schema source of truth for app-level (PII and content filter) and agent-level (content filter) guardrails, validated centrally and consumed by ADK when it builds an agent.
• Organization settings: BYOT model credentials (/api/v1/byot/, /api/v1/byot/schema/), chat configuration, default guardrails, and cost controls. GET /api/v1/cost-control-config/mine/ returns the caller's effective session, weekly, and monthly limits (enabled, limit_usd, is_custom). Administrators manage per-user overrides and limit-increase requests.

API Overview

Other resources live under /api/v1/analyzers/, /api/v1/collections/, /api/v1/graphs/, /api/v1/data-sources/, /api/v1/skills/, /api/v1/templates/, /api/v1/business-events/, /api/v1/guardrails/, /api/v1/connectors/, /api/v1/evals/, /api/v1/org/, the organization settings routes (/api/v1/byot/, /api/v1/chat-config/, /api/v1/guardrails-config/, /api/v1/cost-control-config/, /api/v1/limit-increase-requests/), and the library catalogs. GET /health/ is unauthenticated.

→ Full API reference: Configurator API

Configuration

Permissions are granular per action and resource (for example HasCanCreateToolPermission, HasCanUpdateAgentPermission, HasCanViewAppPermission) and are always organization-scoped. Sharing a resource with the whole organization requires an organization administrator.

Data Model

Soft delete is supported through a base model mixin (deleted_at timestamp; records are retained). Tools, agents, apps, analyzers, skills, templates, and business events keep versioned configuration rows. Updating a resource edits the current draft, or creates a new draft version when the latest version is already deployed (agents and apps move to the next minor or major version depending on what changed). Deploying marks the latest draft as deployed; deployed versions are never edited in place.

Integration Points

Troubleshooting

• "Organization not found": verify COSMOS_SERVICE_CLIENT_ID and COSMOS_SERVICE_CLIENT_SECRET, run ./manage.sh <env> verify-tokens, and if needed ./manage.sh <env> setup-tokens && ./manage.sh <env> restart configurator-web.
• Kafka events not produced: check docker logs cosmos-dev-configurator-web, confirm Kafka connectivity, and make sure the bootstrap server is kafka:9092 inside Docker.
• Resource missing with X-Project-Id: the resource is not enabled in that project. Retry without the header to confirm, then enable it in the project.
• Migrations: run inside the container with docker exec cosmos-dev-configurator-web python manage.py migrate. Deployed environments run migrations as a Helm hook job before the web server rolls out.

Changelog

See Configurator Changelog for verified documentation and service-surface changes.