agents

name	agents
description	Manage and develop AI agents using kubani CLI. Use for checking agent health, versions, deployment status, running tests, evaluations, and managing Nexus proactive background missions.

AI Agents Management

Manage AI agents using the kubani CLI and cluster tools.

Quick Commands

# Create a new agent automatically (NEW!)
kubani agent draft --name my-agent --description "..."

# Check agent creation status
kubani agent status my-agent

# List all agents with status
kubani agents list

# Run agent locally with hot-reload
kubani run k8s-monitor --hot-reload

# Run agent tests
kubani test k8s-monitor

# Run evaluation suite
kubani eval k8s-monitor

# View execution traces
kubani trace k8s-monitor

# Start observability dashboard
kubani dashboard

Nexus Proactive Missions

The Nexus agent supports background missions — scheduled, autonomous tasks that run without user interaction. Missions are dispatched by the NexusHeartbeatWorkflow Temporal Schedule (every 1 minute) and executed as bounded run_mission_agent_turn activities.

Mission Management

# Register the heartbeat Temporal Schedule (run once on cluster setup)
python -c "
from kubani.nexus.orchestrator.worker import register_heartbeat_schedule
import asyncio
asyncio.run(register_heartbeat_schedule())
"

# Apply the missions DB schema migration
kubectl apply -f infrastructure/gitops/apps/nexus/missions-migration-job.yaml

# View active missions
psql $NEXUS_DATABASE_URL -c "SELECT id, title, status, schedule, next_run_at FROM nexus_missions WHERE status='active';"

# View recent mission runs
psql $NEXUS_DATABASE_URL -c "SELECT mission_id, status, tool_calls_made, found_anomaly, duration_ms FROM nexus_mission_runs ORDER BY started_at DESC LIMIT 20;"

# Pause the heartbeat schedule (stops all missions)
temporal schedule pause --schedule-id nexus-heartbeat

# Resume the heartbeat schedule
temporal schedule unpause --schedule-id nexus-heartbeat

Mission Policies

Policy	Allowed MCP Servers	Use Case
nexus	memory, skills, fetch	Safe missions (research, summarisation)
nexus-proactive	+ kubernetes, discord, temporal	Cluster monitoring missions

Destructive operations in nexus-proactive (delete, scale, exec) require HITL approval.

Arguments

• agent-name: Optional specific agent name for detailed info

Instructions

List All Agents

cd /home/al/git/kubani
echo "=== AI Agents ==="
echo ""

for earthfile in agents/*/Earthfile; do
    agent_dir=$(dirname "$earthfile")
    agent_name=$(basename "$agent_dir")
    [ "$agent_name" = "core" ] && continue

    # Get version from pyproject.toml
    version=$(grep '^version = ' "$agent_dir/pyproject.toml" | sed 's/version = "\(.*\)"/\1/')

    # Get deployed image
    deployed=$(KUBECONFIG=/home/al/.kube/config kubectl get deploy $agent_name -n ai-agents -o jsonpath='{.spec.template.spec.containers[0].image}' 2>/dev/null || echo "not deployed")

    # Get pod status
    status=$(KUBECONFIG=/home/al/.kube/config kubectl get pods -n ai-agents -l app.kubernetes.io/name=$agent_name -o jsonpath='{.items[0].status.phase}' 2>/dev/null || echo "unknown")

    echo "$agent_name"
    echo "  Source version: $version"
    echo "  Deployed image: $deployed"
    echo "  Pod status: $status"
    echo ""

Development Workflow

Use kubani for agent development:

# Initialize configuration (one-time)
kubani init

# Run agent with hot-reload
kubani run k8s-monitor --hot-reload

# Run with mock services (for offline development)
kubani run k8s-monitor --mock-mcp --mock-redis

# Run tests
kubani test k8s-monitor --coverage

# Run evaluation suite
kubani eval k8s-monitor

# Run specific evaluation layer
kubani eval k8s-monitor --layer llm

Detailed Agent Info

For a specific agent, show detailed information:

AGENT_NAME="k8s-monitor"

# Pod details
KUBECONFIG=/home/al/.kube/config kubectl get pods -n ai-agents -l app.kubernetes.io/name=$AGENT_NAME -o wide

# Recent logs
KUBECONFIG=/home/al/.kube/config kubectl logs -n ai-agents -l app.kubernetes.io/name=$AGENT_NAME --tail=20

# Recent deployment history
git log --oneline -5 gitops/apps/ai-agents/$AGENT_NAME/deployment.yaml

# View traces
kubani trace $AGENT_NAME --last 10

# View metrics
kubani metrics $AGENT_NAME

Build and Deploy

# Build agent container
kubani build k8s-monitor

# Deploy to cluster
kubani deploy k8s-monitor

# Rollback deployment
kubani deploy k8s-monitor --rollback

Create New Agent

# Create from default template
kubani new my-agent

# Create with federated template
kubani new my-agent --template federated

Framework

The kubani/framework/ package provides shared functionality:

# Key modules:
# - config.py: Unified configuration system
# - events/: Event bus with hybrid event types
# - mcp/: MCP client
# - llm.py: LLM integration
# - registry/: Service registry

Architecture

kubani/
├── framework/                # Core framework
│   ├── config.py            # Unified configuration
│   ├── events/              # Event bus (hybrid types)
│   ├── mcp/                 # MCP client
│   └── registry/            # Service registry
├── agents/                   # Reusable agent implementations
│   ├── _base/               # Base agent class (KubaniAgent)
│   ├── critic/              # Execution evaluation (learning)
│   ├── reflection/          # Cross-agent insights (learning)
│   ├── skill_synthesizer/   # Skill proposal (learning)
│   ├── event_classifier/    # Event classification
│   ├── remediator/          # Remediation actions
│   └── ...                  # Other specialized agents
├── syndicates/               # Multi-agent orchestration
│   ├── _base/               # Base syndicate class
│   ├── k8s_monitor/         # Kubernetes monitoring
│   ├── news_digest/         # News aggregation
│   └── learning_system/     # Continuous learning (Critic + Reflection + Synthesizer)
├── nexus/                    # Nexus agent (always-on, proactive)
│   ├── orchestrator/        # Temporal workflows and activities
│   │   ├── workflow.py      # NexusOrchestratorWorkflow (proactive_mission signal)
│   │   ├── heartbeat_workflow.py  # NexusHeartbeatWorkflow (cron dispatcher)
│   │   ├── activities.py    # run_agent_turn, run_mission_agent_turn
│   │   └── worker.py        # Worker + register_heartbeat_schedule
│   ├── missions/            # Mission CRUD, scheduler, activities
│   ├── models/              # NexusMission, NexusMissionRun models
│   └── tools/               # MCP clients (policy-aware), security
└── mcp/servers/              # MCP server implementations

Learning System

The continuous learning system runs as a syndicate (kubani/syndicates/learning_system/):

from kubani.syndicates.learning_system import LearningSystemSyndicate
from kubani.agents.critic import CriticAgent
from kubani.agents.reflection import ReflectionAgent
from kubani.agents.skill_synthesizer import SkillSynthesizerAgent

# Run the full learning system
syndicate = LearningSystemSyndicate()
await syndicate.start()