Organisms and Agents

What you'll learn

How to create multiple agents in one organism, name them, and understand the organism::agent namespace.

Organisms vs Agents

• Organism = namespace. Like a database server that holds multiple databases.
• Agent = a named strand with its own Ed25519 keypair and encryption key.

One SapixDB process serves one organism. An organism can have unlimited agents. Each agent is a separate, cryptographically isolated chain of records.

Create a second agent

# agents are created via the /v1/organisms/:org/agents endpoint
curl -s -X POST http://localhost:7475/v1/organisms/myorg/agents \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
  -d '{"id": "users", "description": "User profile records"}' \
  | python3 -m json.tool

Create a third: `bash curl -s -X POST http://localhost:7475/v1/organisms/myorg/agents \ -H "Content-Type: application/json" \ -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \ -d '{"id": "orders", "description": "Order records"}' \ | python3 -m json.tool `

List all agents

curl -s http://localhost:7475/v1/agents \
  -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
  | python3 -m json.tool

Write to a specific agent

curl -s -X POST http://localhost:7475/v1/agents/users/write \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
  -d '{"payload": {"name": "Alice", "email": "alice@example.com", "plan": "pro"}}' \
  | python3 -m json.tool

Each agent has its own strand. Writing to users does not affect orders. There is no shared sequence counter.

Naming conventions

Good agent names are lowercase, hyphenated, descriptive: - user-profiles - order-events - payment-ledger - audit-log

Agents work like tables in spirit, but with important differences: they have identity, history, and can own their data domain autonomously.

Pre-load agents at startup

Instead of creating agents via API, you can define them in your docker-compose.yml:

environment:
  SAPIX_AGENTS: |
    [
      {"id": "users",   "description": "User profiles"},
      {"id": "orders",  "description": "Order events"},
      {"id": "payments","description": "Payment ledger"}
    ]

Challenge

1. Create three agents: products, reviews, inventory
2. Write one record to each
3. Confirm with GET /v1/health that record_count reflects writes across all agents

---