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
agentsnamespace 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.shanddb/install.shdefine akubectlalias with a fixed--kubeconfigpath. 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.