Appearance
Architecture & Tech Stack
This page is the contract between Agentcy and your infrastructure. It describes what each component does, the requirements it imposes, and which managed services satisfy those requirements on each cloud.
Component Diagram
What Each Component Does
agentcy-api (Rust / Axum)
The single backend binary. It is a Cargo workspace with focused crates:
| Crate | Responsibility |
|---|---|
kg-api | HTTP routes, JWT/OIDC middleware, OpenAPI |
kg-auth | Provider-agnostic auth (Local + OIDC) |
kg-core | Domain types, tenancy, permission catalog |
kg-db | Postgres queries via sqlx |
kg-graph | Neo4j queries via neo4rs |
kg-chat | Agent loop, tool catalog, approval registry |
kg-rag | Embeddings, vector search, hybrid scoring |
kg-ingest | ETL pipelines for connectors |
kg-worker | Job runners — scheduled tasks, syncs |
kg-policy | Rego evaluation (zero-trust) |
kg-agents | Channels, triggers, workflows |
Stateless. Migrations run on startup. Scale by adding replicas.
agentcy-frontend (Next.js 16, React 19)
UI for chat, connectors, policies, channels, and the orchestrator. Stateless — JWTs travel with each request, sessions live in Postgres. Renders fine at any number of replicas.
PostgreSQL 16
Source of truth. Stores users, organizations, connectors (encrypted creds), conversations, messages, tasks, jobs, policies, audit log, embeddings, and (with pgvector) all RAG vectors.
Required extensions:
vector(pgvector) — embedding similarity searchpg_trgm— fuzzy / hybrid lexical searchuuid-ossp(orpgcrypto) — UUID generation
Minimum version: Postgres 14 works; 16 is recommended for HNSW index improvements and partition perf.
Context Engine
Holds the knowledge graph — entities ingested from connectors (commits, files, services, infra resources, people, channels, …) and the relationships between them. Realms partition the graph by domain. Application code targets the provider-agnostic agentcy-graph interface; the engine choice is opaque to callers.
Two providers ship behind the same interface:
| Provider | Backed by | Query languages | Where it ships |
|---|---|---|---|
| Basic (default for self-host) | Embedded graph store, Neo4j-compatible | Cypher | Ships with every self-hosted install. Single-node by default; Neo4j Enterprise causal cluster or AuraDB if you want HA on the Basic provider. |
| Advanced | kyma — Rust-based columnar engine on S3-compatible object storage, plus pgvector for embeddings | KQL (Kyma Query Language), SQL, plus the same Cypher surface | Agentcy Cloud and on-premise Enterprise deployments. |
Both providers expose the same ContextEngine trait and the same Explore UI. Selecting Advanced unlocks structured KQL/SQL, time-series queries, schema evolution, multi-billion-node scale, and native Apache Arrow output (Flight gRPC). See Context Engine & Realms for the capability matrix.
kyma in one line
"Production knowledge, as a query." kyma is a Kusto-style columnar data engine purpose-built as the answer layer for agents — OTLP / REST / Kafka in, KQL / SQL / PromQL out, Arrow Flight gRPC streaming, with object storage as the source of truth. See getkyma.dev and the project repo for the full architecture.
Redis 7
Job queues (sync runs, scheduled tasks), the approval registry's pub/sub channel for agent-loop pauses, and short-lived caches (rate limiters, ephemeral OAuth state). No durability requirement, but enabling AOF persistence is recommended.
Optional sidecars
| Sidecar | When to deploy |
|---|---|
| OpenFang | When you use sub-agents, the orchestrator, or templates |
| Grafana | If you want pre-built dashboards rather than wiring /metrics to your existing stack |
| CIAB (Code-In-A-Box) | If you use the Coding Agents feature on EC2 / on-prem |
Managed-Service Equivalents
Agentcy's data tier is plain Postgres / Neo4j / Redis, so any managed equivalent works as long as it can be reached over the network and supports the listed extensions / versions.
PostgreSQL
| Provider | Service | Pgvector | Multi-AZ | Notes |
|---|---|---|---|---|
| AWS | RDS for PostgreSQL | Yes (PG ≥ 15.2) | Yes | Default choice for AWS |
| AWS | Aurora PostgreSQL | Yes (PG ≥ 15.3) | Yes | Better for very large datasets / read replicas |
| GCP | Cloud SQL for PostgreSQL | Yes (set cloudsql.enable_pgvector=on) | Yes | Use Cloud SQL Auth Proxy from inside VPC |
| GCP | AlloyDB for PostgreSQL | Yes | Yes | Faster vector search than Cloud SQL on large indexes |
| Azure | Azure Database for PostgreSQL — Flexible Server | Yes | Yes | Enable the vector extension via azure.extensions |
| Supabase | Supabase Postgres | Yes (built-in) | Yes (Pro+) | Easiest "just works" PG with pgvector — fine for self-host |
| Neon / Crunchy / Render / Railway | Managed Postgres | Yes | Varies | All work — confirm Postgres ≥ 14 and pgvector availability |
Verify your provider supports pgvector and pg_trgm. Both are required.
Supabase as your Postgres
Supabase's hosted Postgres is a perfectly valid backing store for self-hosted Agentcy. You only use the Postgres part — Agentcy doesn't depend on Supabase Auth, Realtime, or Storage. Set DATABASE_URL to the Supabase connection string and you're done.
Redis
| Provider | Service | Persistence | Notes |
|---|---|---|---|
| AWS | ElastiCache for Redis | RDB + AOF | Standard pick on AWS |
| AWS | MemoryDB for Redis | Strong durability | Overkill for our usage; ElastiCache is enough |
| GCP | Memorystore for Redis | RDB | Standard pick on GCP |
| Azure | Azure Cache for Redis | RDB + AOF | |
| Upstash / Aiven / Redis Cloud | Managed Redis | Configurable | All fine. We use a small subset of Redis features (no Streams, no modules required). |
| Self-hosted | OSS Redis 7 | AOF on | StatefulSet on Kubernetes works |
Agentcy uses Redis for queues, pub/sub, and cache. We don't depend on Redis Streams or any module — any standards-compliant Redis ≥ 6 works.
Context Engine — Basic provider (graph store)
The Basic provider runs an embedded graph store with a Neo4j-compatible Bolt interface. Most self-hosters never need to think about it — docker compose up brings it online.
| Option | When to use |
|---|---|
| Bundled with Agentcy (default) | Self-host on Docker Compose / Kubernetes. Single-node, ships in the chart. |
| Neo4j AuraDB Free | Demos, ≤200K nodes, ≤400K relationships. Useful on Railway. |
| Neo4j AuraDB Pro / Enterprise | Production, ≥1M nodes, automatic backups. |
| Self-hosted Neo4j Community on EC2 / GCE / EBS | Air-gapped, single-node fine, you handle backups. |
| Self-hosted Neo4j Enterprise causal cluster | When you need HA on the Basic provider without AuraDB. Requires an Enterprise license. |
Run only one writer instance of Community Edition — it's not built for replication. Use Enterprise, AuraDB, or switch to Advanced if you need HA.
Context Engine — Advanced provider (kyma)
The Advanced provider runs kyma as a sidecar (or shared cluster) instead of the embedded graph store. kyma stores everything as columnar Arrow on S3-compatible object storage you own; the catalog lives in Postgres; compute is stateless. You get Cypher, KQL, and SQL against the same engine, plus OTLP/REST/Kafka ingest paths and Arrow Flight gRPC reads.
| Option | When to use |
|---|---|
| Agentcy Cloud | Managed end-to-end. kyma + S3 + pgvector are provisioned per tenant. No ops on your side. |
| On-prem Enterprise | Run kyma yourself alongside Agentcy. We ship a Helm chart and docker-compose --profile context_advanced profile. Bring your own S3-compatible bucket — AWS S3, GCS, Cloudflare R2, MinIO all work via the object_store crate. |
| Self-host (community) | The kyma source is open (getkyma.dev) — single-binary mode runs alongside an Agentcy instance for evaluation. Multi-node and federation come online without a rewrite. |
To enable Advanced on a self-hosted install:
bash
export CONTEXT_ENGINE=advanced
export KYMA_BASE_URL=http://kyma:8080
export KYMA_TOKEN=...
export KYMA_DATABASE=kyma
# Optional — semantic search via pgvector
export EMBEDDINGS_DATABASE_URL=postgresql://postgres:...@postgres:5432/kymaMigration from Basic to Advanced is one-way (background backfill into kyma). See Knowledge Graph & Realms for the full migration flow.
Object Storage (optional)
Some connectors (file drops, attachments, exports) and the Advanced Context Engine use object storage. Agentcy speaks the S3 API — anything compatible works:
- AWS S3
- GCS (via S3 interop or native client)
- Cloudflare R2
- Azure Blob (via S3-compatible gateway, or native)
- MinIO (self-hosted)
Bring your own bucket
On Agentcy Cloud, the Advanced Context Engine can be configured to use your bucket for data residency. Self-hosted deployments use whichever bucket you point the connectors at — no Agentcy-controlled storage involved.
Object Storage by Cloud
| Provider | Service | Notes |
|---|---|---|
| AWS | S3 | First-class. IAM via task role / IRSA. |
| GCP | GCS | Use HMAC keys for S3-compat, or the native client. |
| Azure | Blob Storage | S3-compatible via azurite or third-party gateways. |
| Cloudflare | R2 | Zero egress, S3-compatible. Great for the Advanced Engine BYO-bucket. |
| Self-host | MinIO | Drop-in for air-gapped sites. |
LLM Provider
Agentcy is provider-agnostic at the LLM layer. Out of the box:
| Provider | Auth | Notes |
|---|---|---|
| Anthropic | LLM_API_KEY=sk-ant-... | Default; recommended for tool-calling quality |
| OpenAI | LLM_API_KEY=sk-... | Set LLM_PROVIDER=openai |
| AWS Bedrock | IAM (IRSA on EKS) | LLM_PROVIDER=bedrock |
| GCP Vertex AI | Workload Identity | LLM_PROVIDER=vertex |
| Ollama / vLLM / any OpenAI-compatible | URL + optional key | Set LLM_BASE_URL |
You can mix providers per agent — the orchestrator chooses based on the agent's model field.
Why These Choices
Why Rust for the backend?
- The agent loop holds open WebSocket / SSE streams to many concurrent clients. Tokio's per-stream cost is in the kilobytes — orders of magnitude leaner than node/Python.
- Single static binary — easy to ship for desktop, Lambda-on-FPM, or embedded use cases.
- Zero-cost abstractions matter once you're shoveling 10k+ LLM tool-call results per minute through hot paths.
Why Postgres and a Context Engine?
They answer different questions:
- Postgres: "What did the user click?" "Which conversation has unread messages?" "Show me audit events for tenant X yesterday." Tabular OLTP.
- Context Engine: "Which services depend on this S3 bucket?" "Walk three hops from this PR to find the team that owns the affected service." Graph traversals.
Cypher-style traversals on a relational schema are slow and unreadable. Storing user records in a graph is overkill. Two stores, two strengths.
The Basic provider is a graph store optimized for traversals (Cypher). The Advanced provider — kyma — keeps the same logical graph model but adds columnar / time-series / OTLP-native paths so the same engine answers both "walk this graph" and "summarize these spans for the last 90 days" without bolting on a separate observability stack.
Why pgvector instead of a dedicated vector DB?
- One fewer system to operate.
- Hybrid search (vector + lexical via
pg_trgm) is one query. - HNSW indexes in pgvector are competitive with Pinecone / Qdrant for the data sizes most teams have (≤10M vectors).
If you scale past pgvector's comfort zone, the embedding write path is pluggable — talk to us about Qdrant / Pinecone backends.
Why Redis (and not a queue like SQS or Pub/Sub)?
- Latency. Approval channels and the agent-loop pause/resume need ms-level wakeups.
- We use Redis for cache and queue, so it's already there.
- For purely background jobs you can plug your own queue in via the worker config — Redis is the default, not the lock-in.
Why no built-in object storage?
It would force a choice no one wants. Keep it boring: speak the S3 API and let users point at S3, R2, GCS, or MinIO.
Network Requirements
| Direction | Source | Destination | Why |
|---|---|---|---|
| Inbound | Internet | ALB / GCLB / Ingress :443 | User traffic |
| Internal | Frontend pods | API pods :8080 | API calls |
| Internal | API pods | Postgres :5432 | All relational data |
| Internal | API pods | Context Engine :7687 (Basic, Bolt) or :8080 (Advanced, kyma HTTP + Flight gRPC) | Graph queries |
| Internal | API pods | Redis :6379 | Queues + cache |
| Egress | API pods | LLM provider endpoints (Anthropic, OpenAI, …) | Inference |
| Egress | API pods | Connector endpoints (GitHub, AWS APIs, …) | Tool execution |
| Optional | API pods | OpenFang :4200 | Sub-agents |
Lock all egress to a known list if your security posture requires it — Agentcy's connectors honor HTTPS_PROXY and per-source URL pins.
Versions Reference
| Component | Min | Recommended |
|---|---|---|
| Linux kernel (host) | 4.19 | 5.15+ |
| Docker / containerd | 24 / 1.6 | latest |
| Kubernetes | 1.27 | 1.30+ |
| PostgreSQL | 14 | 16 |
| pgvector | 0.5 | 0.8+ |
| Neo4j (Basic provider) | 5.13 | 5.x latest |
| kyma (Advanced provider) | latest from getkyma.dev | latest |
| Redis | 6 | 7 |
| Node.js (frontend runtime) | 20 | 22 LTS |
| Rust (building from source) | 1.83 | latest stable |
See Also
- Overview — pick a deployment path
- Environment Variables — the full config surface
- Database Schema — what's in Postgres
- Crate Map — Rust workspace layout