Skip to content
AGENTS

agent-quest

Quest management UI and server

agent-quest is a Kadi/AGENTS platform agent that provides a Quest management UI (client) and a server backend to manage quest data and logs. It exists to present a browser UI and an HTTP server that communicates with ArcadeDB for persistent logging and interacts with the Kadi broker for inter-agent messaging and secrets delivery. The package contains a standalone client (Vite) and a server (TypeScript -> dist) and is deployed as a containerized agent that receives required secrets from configured vaults prior to start.

Architecture

Section titled “Architecture”
  • Components
    • client/: Vite-based React/Vue frontend (served separately in development via npm run dev:client, built into client/dist for production).
    • server/: TypeScript server code (entrypoint: server/dist/index.js in production; server/src/index.ts in development).
    • Kadi broker: agent-quest connects to a remote broker (broker.dadavidtseng.com) on networks “quest” and “global”.
    • Secret vaults: Secrets are obtained from vaults named “observer” and “arcadedb” before the agent starts.
    • ArcadeDB: External graph DB used for logs/persistence (host/port configured; used by server).
  • Data flow
    • Agent receives secrets via kadi secret commands (vaults: observer, arcadedb) at container start.
    • Server starts and connects to Kadi broker (remote URL) and ArcadeDB (configured host/port).
    • Frontend communicates with server over HTTP (CORS configured).
    • Server logs events (ability-log) and persists logs to ArcadeDB (arcadedb config).
  • How it fits in AGENTS ecosystem
    • Runs on the Kadi broker networks “quest” and “global” and can both send and receive messages to/from other agents registered on those networks.
    • Uses secret-ability to fetch sensitive config at runtime, avoiding baked-in credentials.
    • Uses ability-log for consistent agent logging and auditability across the ecosystem.

Tools / API

Section titled “Tools / API”

This package relies on and invokes the Kadi CLI and scripts. The following are the key external tools/commands referenced in the source and scripts.

Tool / CommandDescriptionKey parameters / usage shown in source
kadi secret receiveRetrieve secrets from a configured vault into the runtime environment before starting the agent—vault observer —vault arcadedb (see deploy command)
kadi installInstall Kadi-provided packages/abilities into the build/containerkadi install kadi-secret; kadi install ability-log
kadi run startKadi runtime wrapper used to run agent start command after secret deliverykadi run start (used after secret receive in deploy command)
npm scripts (dev/build/start)Local development and build orchestration for client and servernpm run dev, npm run build, npm run start (see scripts in agent.json)
ability-log (ability)Provides structured logging integration for agents (declared in abilities)Configured via logging.LEVEL in config.toml; used by server code (see dependencies)
secret-ability (ability)Provides secret vault integration for agentsVaults configured in config.toml and agent.json deploy.secrets

If you interact with the agent via the Kadi CLI, the deploy image uses the command sequence:

// deploy command (string taken directly from agent.json)
const deployCmd = "kadi secret receive --vault observer --vault arcadedb && kadi run start";

Common npm scripts (taken directly from agent.json scripts):

const scripts = {
  preflight: "node -e \"const fs=require('fs');if(!fs.existsSync('node_modules')){console.error('Dependencies not installed. Run: npm install');process.exit(1)}console.log('✓ Dependencies OK')\"",
  setup: "npm run install:all && npm run build",
  dev: "npx concurrently --raw --kill-others-on-fail \"npm run dev:client\" \"npm run dev:server\"",
  "dev:client": "cd client && npx vite",
  "dev:server": "cd server && npx tsx watch src/index.ts",
  build: "npm run build:client && npm run build:server",
  "build:client": "npm run build --prefix client",
  "build:server": "npm run build --prefix server",
  start: "node server/dist/index.js",
  "install:all": "npm install && npm install --prefix client && npm install --prefix server"
};

Configuration

Section titled “Configuration”

Configuration is read from config.toml (secrets live in a separate secrets.toml that is gitignored). Key configuration fields:

  • [agent]

    • ID: “agent-quest” — agent identifier
    • VERSION: “0.3.7” — release version string used by the agent at runtime

  • [server]

  • [logging]

    • LEVEL: “debug” — logging level used by ability-log

  • [broker.remote]

    • URL: “wss://broker.dadavidtseng.com/kadi” — remote broker URL (the agent connects here)
    • NETWORKS: [“quest”, “global”] — broker networks this agent joins

  • [secrets]

    • VAULTS = [“observer”, “arcadedb”] — vault names the agent expects
    • KEYS = [“OBSERVER_PASSWORD”, “ARCADE_USERNAME”, “ARCADE_PASSWORD”] — secret keys expected from vaults

  • [arcadedb]

    • HOST = “arcadedb.dadavidtseng.com”
    • PORT = 443
    • USERNAME = “root”
    • DATABASE = “agents_logs”

Environment variables (exposed/used by deploy configuration)

  • ARCADE_HOST, ARCADE_PORT — provided in deploy.services.app.env to point the agent to ArcadeDB
  • NODE_ENV — configured in images/build for production/development
  • Secrets delivered from vaults map to environment variables:
    • OBSERVER_PASSWORD (vault: observer)
    • ARCADE_USERNAME, ARCADE_PASSWORD (vault: arcadedb)

Secrets and vaults (agent.json deploy.secrets)

  • Two vaults configured:
    • vault “observer” (required: OBSERVER_PASSWORD)
    • vault “arcadedb” (required: ARCADE_USERNAME, ARCADE_PASSWORD)
  • Delivery method: “broker” (secrets delivered via the Kadi broker prior to the start command in the container)

Build-time behavior (from agent.json/build)

  • During build the container executes:
    • NODE_ENV=development npm run install:all
    • kadi install kadi-secret
    • kadi install ability-log
    • Copies secret-ability runtime bits into /app/abilities
    • Runs npm run build
    • Prunes dev deps from server prefix before final image

Code Examples

Section titled “Code Examples”

Below are the key command patterns and script lines used in the project (copied verbatim from agent.json). These show how the agent is run, built, and how it receives secrets.

Start command executed in the production container:

// production start (from agent.json -> deploy.services.app.command)
const containerStart = [
  "sh",
  "-c",
  "kadi secret receive --vault observer --vault arcadedb && kadi run start"
].join(" ");

Build steps used by the package image build (from agent.json.build.run):

const buildSteps = [
  "NODE_ENV=development npm run install:all",
  "kadi install kadi-secret",
  "kadi install ability-log",
  "mkdir -p /app/abilities && cp -a /opt/kadi/abilities/secret-ability@* /app/abilities/",
  "npm run build",
  "npm prune --omit=dev --prefix server",
  "rm -rf client/node_modules"
].join(" && ");

Local development run (from agent.json.scripts):

// run both client and server concurrently for development
const dev = "npx concurrently --raw --kill-others-on-fail \"npm run dev:client\" \"npm run dev:server\"";

Notes for server authors

  • The server entrypoint used in production is server/dist/index.js (see agent.json.entrypoint and start script).
  • The agent expects secrets to be present at startup; the container deploy command ensures kadi secret receive runs before kadi run start.

Dependencies

Section titled “Dependencies”

Declared abilities (runtime)

  • secret-ability: ^0.9.5 — provides secret vault integration; used to retrieve sensitive credentials at runtime (vaults observer and arcadedb).
  • ability-log: ^0.1.7 — logging ability used by the agent to emit structured logs consistent with the AGENTS logging pipeline.

Dev tooling (from package devDependencies)

  • @types/node, concurrently, typescript — used for local development and builds (client and server have their own devDeps not listed here).

What depends on agent-quest

  • No agents in this repository explicitly declare a dependency on agent-quest. At runtime, other agents on Kadi broker networks “quest” and “global” may interact with agent-quest via broker messages and expect it to respond to quest-related topics.

What agent-quest depends on

  • External systems:
    • Kadi broker (remote broker.dadavidtseng.com) for inter-agent messaging and secret delivery.
    • ArcadeDB (arcadedb.dadavidtseng.com) for persistence of logs and agent data.
  • Abilities:
    • secret-ability for runtime secret management
    • ability-log for logging

Notes for Developers

Section titled “Notes for Developers”
  • When making changes to server or client, use the provided npm scripts:
    • npm run dev to run client + server locally
    • npm run build to build both client and server
    • npm run start to run the compiled server
  • Secrets are intentionally not stored in config.toml; provide them via secrets.toml (gitignored) in development or via Kadi vaults in deployment.
  • Ensure any changes that require additional vault keys are reflected in agent.json deploy.secrets and config.toml [secrets].KEYS.
  • If you add new runtime abilities, mirror the kadi install steps into the build.run array in agent.json so the image contains the ability bits.