Nexus Agent

Nexus is the conversational personal intelligence (PI) agent — a single agentic loop using the Strands Agent SDK, orchestrated by Temporal.

Architecture

UI (WebSocket) → Nexus Gateway (FastAPI) → Temporal Signal
    → Orchestrator Workflow → run_agent_turn Activity
        → Strands Agent (think → act → observe loop)
            → Core Tools (read/write/edit/bash)
            → MCP Tools (memory, skills, fetch)
            → Custom Tools (web_search)
        → Response via Redis PubSub → Gateway → UI

Key Differences from Syndicates

Components

Entity Workflow Pattern

The orchestrator uses a long-running Temporal entity workflow:

• Receives messages via Temporal signals
• Processes each message in a run_agent_turn activity
• Uses continue-as-new after 100 iterations to prevent history growth
• Maintains conversation state across turns

Key Files

• activities.py — run_agent_turn(): Creates Strands Agent, builds system prompt, executes agent loop
• workflow.py — Entity workflow with signal handling and continue-as-new
• worker.py — Temporal worker entry point
• tools/core.py — Core tools (file ops, bash, etc.)
• tools/extra_tools.py — MCP client tools (fetch, web_search)

Local Development

# Setup
cd kubani/nexus/orchestrator
cp ../../nexus/.env.example .env  # Edit with credentials

# Run worker locally
source .env && python -m kubani.nexus.orchestrator.worker

# Run gateway (separate terminal)
cd kubani/nexus/gateway
source .env && python -m kubani.nexus.gateway.main

See kubani/nexus/.env.example for all required environment variables.

Configuration

Nexus uses direct environment variables (NOT the kubani config system):

Building & Deploying

# Build container
earthly +nexus-orchestrator

# Smoke test
docker run --rm --env-file .env <image> python -c "from kubani.nexus.orchestrator.worker import *; print('OK')"

# Deploy via GitOps
# Update image tag in infrastructure/gitops/apps/nexus/orchestrator-deployment.yaml
# Commit and push (Flux auto-deploys)

Testing Changes

1. Prompt changes: Edit activities.py system prompt, run worker locally, send test message via UI
2. Tool changes: Edit tools, run worker locally, test tool invocation
3. Workflow changes: Edit workflow.py, restart worker, verify signal handling
4. Always follow the 4-stage workflow: local test → integration → container build → deploy