Skip to content

Install & Setup

This chapter explains how to prepare an environment for building and running agents: what you need, which scripts install the platform, the order to run them in, and how the services are configured.

Two Kinds of Clusters

An AgentGr.id installation uses two kinds of Kubernetes clusters:

  • Platform services cluster. This is where the shared platform services run: the subjects registry, the Delegate API, the policies system, human intervention, the functions and tools registries, communications and their databases. It is installed once. Every agent you deploy relies on these services, and they are shared by all agents in all agent clusters.
  • Agent clusters. This is where agents run. You can have one or more agent clusters, and each is onboarded to the platform separately (see Register an Agent Cluster). Agents are created in the agents namespace of the cluster they are deployed to.

A single Kubernetes cluster can play both roles. That is the simplest setup for development and small installations.

Prerequisites

Tool / infrastructure Used for
Kubernetes cluster(s) and kubectl Running platform services and agents
Docker on the machine you install from Building and pushing images
Public IP of a cluster node Reaching the container registry and the NodePort services
NATS P2P meshes between agents (optional, needed for mesh messaging and events)

MongoDB, Redis and the container registry are installed by the scripts below. Capability-specific backends are only needed when an agent uses them: AIOS for model inference, FrameDB for memory, S3-compatible storage for the persistent store, ArangoDB for the knowledge base, and Weaviate or Pinecone for the vector store.

Ports

The cluster must allow the standard Kubernetes ports on your firewalls and security groups:

Nodes Port Protocol Component
Control plane 6443 TCP Kubernetes API server
Control plane 2379–2380 TCP etcd client and peer API
Control plane 10250 TCP Kubelet API
Control plane 10257 TCP kube-controller-manager
Control plane 10259 TCP kube-scheduler
Workers 10250 TCP Kubelet API
Workers 30000–32767 TCP/UDP NodePort services (all platform services are exposed this way)
All, if you use Flannel 8472 UDP Flannel VXLAN overlay
All, if you use Calico 179 TCP Calico BGP

The Installation Scripts

The platform is installed with the scripts in the agent-automation repository:

agent-automation/
├── docs/installation_steps.md
└── src/
    ├── deploy_base.sh        # step 1: container registry + static file server
    ├── deploy_db.sh          # step 4: MongoDB
    ├── build-all.sh          # step 5: build and push every image
    ├── deploy_services.sh    # step 6: platform services + RBAC
    ├── base/                 # registry and static-server manifests
    ├── db/install.sh         # MongoDB replica set
    ├── yaml/                 # one manifest per platform service
    ├── rbac/                 # role bindings
    └── agents/ delegate/ policies-system/ functions/ tools/ communications/
                              # service sources, each with its own build-images.sh

Run the steps in order. Each one is described below.

Edit two values before you start

  • Kubeconfig. deploy_base.sh, deploy_services.sh and db/install.sh define a kubectl alias with a fixed --kubeconfig path. Change it to the kubeconfig of your platform services cluster.
  • Public IP. The manifests and build scripts contain the IP of the original installation. Replace it everywhere in step 2.

1. Set Up the Base

cd src/
./deploy_base.sh

This creates two things in the cluster:

Component Exposed on Purpose
Container registry (registry:2) <public-ip>:31280 Stores the platform and agent images
Static file server <public-ip>:32555 Serves files such as policy code. It serves a hostPath directory on the node; change path in base/static-server.yaml to a directory you want to use

2. Update the Public IP

Replace the IP of the original installation with the public IP of your cluster in every file under src/, using your editor's find-and-replace across files. For example, 34.93.251.223 becomes 34.93.24.44. The image names in the build scripts and the service URLs in the manifests all use it.

3. Configure the Container Registry

The registry runs without TLS, so both your machine and the cluster nodes must be told to trust it.

On the machine you build from, add it to /etc/docker/daemon.json and restart Docker:

{
  "insecure-registries": ["<public-ip>:31280"]
}
sudo systemctl restart docker

On every cluster node, add the registry to containerd in /etc/containerd/config.toml, then restart containerd:

[plugins."io.containerd.grpc.v1.cri".registry]
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."<public-ip>:31280"]
      endpoint = ["http://<public-ip>:31280"]
  [plugins."io.containerd.grpc.v1.cri".registry.configs]
    [plugins."io.containerd.grpc.v1.cri".registry.configs."<public-ip>:31280".tls]
      insecure_skip_verify = true
sudo systemctl restart containerd

Do the same on the nodes of every agent cluster, so they can pull agent images.

4. Install the Database

Label the node that will hold the MongoDB data, then run the installer:

kubectl label node <node-name> registry=yes
cd src/
./deploy_db.sh

db/install.sh creates a MongoDB replica set (rs0) in the registries namespace, backed by a hostPath volume at /mnt/data/registry-<n> on the labelled node (default size 30Gi). It then runs a one-off pod that initialises the replica set. The services reach it at mongodb://registry-0.registries.svc.cluster.local:27017.

5. Build the Images

Once the registry is configured on your machine and on the nodes:

cd src/
./build-all.sh

build-all.sh runs the build-images.sh script in every service folder, which builds each image and pushes it to <public-ip>:31280:

Folder Images Role
agents/ agents/db Subjects service: subjects, runtime subjects, deployers, workflow registry and deploy APIs
agents/deployer Agent deployer, installed into each agent cluster by the subjects service
agents/executor Per-agent executor: admission policies, load balancing, auto-scaling
agents/scouter Per-agent job scouter: registers the agent on the job-exchange service listed in runtime.exchanges (Xchange exchanges use explicit subject registration)
agents/his-db Human intervention service
delegate/ agents/delegation Delegate API: synchronous submit-and-wait between agents
policies-system/ policies/system, policies/executor, policies/jobs-runner, policies/functions-server Policies system and policy executors
functions/ functions/registry Functions registry
tools/ tools/registry Tools registry
communications/ communications/fanout, communications/logger, communications/deployer Message fan-out, message logging and the communications deployer

6. Deploy the Platform Services

cd src/
./deploy_services.sh

This applies every manifest in yaml/ and the role bindings in rbac/:

Manifest Service Namespace NodePort
subjects-db.yaml Subjects service (agents-db) registries 30721
delegate-system.yaml Delegate API, with a Redis sidecar delegate 30725 (API), 30726 (Redis)
policies-db.yaml Policies system registries 30102
human-intervention.yaml Human intervention service registries 30608
functions-registry.yaml Functions registry registries 30701
tools-registry.yaml Tools registry registries 30702
communications.yaml Communications deployer registries 30707
RBAC file Grants
rbac/binding.yaml cluster-admin to the default service account in agent-deployer, so the agent deployer can create agents
rbac/all_permissions.yaml cluster-admin to the default service account in policies-system, so policy jobs can run
rbac/sbc.yaml Permission to write bootstrap tokens in kube-system

The subjects service and the Delegate API are required. Install the others for the capabilities you use. Further optional services (task exchange, DSL registry, chat server, metrics collector, social choice and voting) have manifests in services/agents/k8s/global-services/ in the agents codebase.

Configuring the Subjects Service

The subjects service creates deployers, executors and workflow executors, so its manifest sets the images and the URLs of the other services. After step 2 these already point at your registry and public IP; check them if you changed ports:

Variable Description
MONGODB_URI MongoDB connection string (default mongodb://localhost:27017)
SUBJECTS_DB_NAME Database name (default aios)
SUBJECT_DB_URL Public URL of the subjects service itself, passed to deployers and agents
POLICY_DB_URL URL of the policies system
JOB_EXCHANGE_API_URL URL of the task exchange gateway
AGENT_DEPLOYER_IMAGE_NAME Deployer image installed into agent clusters
EXECUTOR_IMAGE_NAME Agent executor image
JOB_SCOUTER_IMAGE_NAME Job scouter image
WORKFLOW_EXECUTOR_IMAGE_NAME Workflow executor image

The Delegate API needs RUNTIME_SUBJECTS_API_URL (the subjects service URL), REDIS_URL (its sidecar), and REDIS_PUBLIC_HOST / REDIS_PUBLIC_PORT (the address agents use to reach that Redis).


7. Register an Agent Cluster

Onboard each cluster that will run agents by registering an agent deployer for it. The subjects service uses the kubeconfig you send to create the agent-deployer namespace and the deployer in that cluster:

export SUBJECT_DB_URL=http://<public-ip>:30721

curl -sS -X POST "$SUBJECT_DB_URL/api/agent-deployers" -H "Content-Type: application/json" \
  -d '{"kubeconfig": {...}, "deployer_id": "deployer-1", "deployer_name": "deployer-1",
       "deployer_cluster_id": "cluster-1", "deployer_public_ip": "<node-public-ip>"}'

The deployer needs permission to create agents, which the subjects service does not grant. Apply rbac/binding.yaml in every agent cluster (step 6 already applies it to the platform services cluster):

kubectl --kubeconfig <agent-cluster-kubeconfig> apply -f src/rbac/binding.yaml

See Agent Deployment for the fields and for running agents across several clusters.

8. Verify

You can check that the installation is up by calling the health endpoints of the two required services. Each should return HTTP 200:

curl -s http://<public-ip>:30721/api/subjects/health     # subjects service
curl -s http://<public-ip>:30725/healthz                 # Delegate API

These calls are a quick sample check, not a complete test of the installation. To check the other services, list the pods (kubectl get pods -A) and call the services your agents use. The end-to-end check is to create, register and deploy a first agent, and test it.


Agent Libraries

Agent images install the SDK libraries they use from services/agents/libs in the agents codebase:

Library Package Install Provides
agents-sdk core copy into the image Agent runtime, context, streaming, sub-agent spawning
llm-interface agents_llm pip install ./libs/llm-interface Model backends, selection, streaming
agent-workflows agent_workflows pip install ./libs/agent-workflows LLM-planned workflow engine
agents-skills agents_skills pip install ./libs/agents-skills Skills and the skill store
agents-eval agents_eval pip install ./libs/agents-eval Evaluation and self-refinement
agents-adapters agents_adapters pip install ./libs/agents-adapters Third-party framework adapters
codegen-sdk agents_codegen pip install ./libs/codegen-sdk Code generation and artifacts
core-libs agent_core_libs pip install ./libs/core-libs Profile manager, persistent store, metrics
agents-addons agent_addons pip install ./libs/agents-addons Vector and graph stores, RAG

Local Development

To develop an agent you only need a registered subject, a local Redis and the agents SDK. See Running the Agent Locally.