Agents

Create, configure, deploy, and monitor your AI workforce

Overview

The Agents page (AgentsPage) is the primary management interface for your AI agent fleet. It provides a tabular listing of all agents in the current organization context, a multi-step creation wizard with role templates ("souls"), a deployment modal supporting multiple infrastructure targets, and navigation into each agent's detail view for deep monitoring and configuration.

The page is organization-aware — when an org is selected via the org context switcher, only agents belonging to that organization are displayed. Agents can be filtered, restarted, and navigated to their full detail pages directly from the list.

How It Works

1. Browse agents — The page loads all agents via GET /api/agents, filtered by the current organization context and user permissions.
2. Create a new agent — Click "Create Agent" to open the 7-step wizard. Choose a role template, configure identity, persona, skills, permissions, deployment target, and review.
3. Deploy the agent — Use the Deploy Modal to push the agent to Docker, VPS, Fly.io, or Railway with stored credentials.
4. Monitor & manage — Click any agent name to access its detail page with activity logs, email inbox, sessions, workforce schedule, and journal.
5. Restart agents — Hit the refresh button on any agent row to trigger a restart via the engine API.

Key Concepts

Soul Templates (Role Templates)

Souls are pre-built role configurations that auto-populate an agent's personality, skills, permissions, and behavior. They are loaded from the engine's /souls/by-category endpoint and organized into categories (e.g., Customer Support, Engineering, Sales). Selecting a soul pre-fills the wizard but all fields remain editable.

Skill Suites

Suites are bundles of related skills (e.g., "Google Workspace" includes Gmail, Calendar, Drive). Toggling a suite adds or removes all its skills at once. Individual skills can also be toggled independently. Skills are loaded from /skills/by-category and /skills/suites.

Permission Presets

Pre-configured security profiles (e.g., "Strict", "Standard", "Autonomous") that set max risk level, blocked side effects, approval requirements, and rate limits. Loaded from /profiles/presets.

Draft Auto-Save

The creation wizard auto-saves progress to localStorage on each step change. If the browser is closed mid-creation, the draft is restored on next visit. Drafts are cleared after successful agent creation.

Create Agent Wizard

The CreateAgentWizard is a 7-step modal wizard:

Agent Creation API

POST /api/engine/bridge/agents
Content-Type: application/json

{
  "orgId": "org-abc123",
  "name": "Sarah Chen",
  "email": "sarah.chen@yourdomain.com",
  "role": "Customer Support Lead",
  "soulId": "customer-support-lead",
  "model": { "provider": "anthropic", "modelId": "claude-sonnet-4-20250514" },
  "deployment": { "target": "fly" },
  "skills": ["email", "calendar", "knowledge-search"],
  "permissions": {
    "maxRiskLevel": "medium",
    "blockedSideEffects": ["deletes-data", "financial"],
    "requireApproval": {
      "enabled": true,
      "forRiskLevels": ["high", "critical"],
      "forSideEffects": ["sends-email"]
    },
    "rateLimits": {
      "toolCallsPerMinute": 30,
      "toolCallsPerHour": 500
    }
  },
  "persona": {
    "gender": "female",
    "language": "en-us",
    "traits": { "communication": "direct", "humor": "warm" }
  }
}

Deploy Modal

The DeployModal is a 3-step wizard for deploying an existing agent to infrastructure:

Deploy credentials are loaded from the engine's /deploy-credentials endpoint and filtered by target type. The deployment is triggered via:

POST /api/agents/{agentId}/deploy
{
  "targetType": "fly",
  "credentialId": "cred-xyz",
  "config": { "region": "iad" },
  "deployedBy": "dashboard"
}

Deployment Progress

The DeploymentProgress component connects to a Server-Sent Events stream (/api/engine/activity/stream) and renders a real-time timeline of deployment phases. Each phase shows status (pending, active, completed, failed) with timestamps and messages.

Agent List & Filtering

The main agent list displays a table with columns: Name, Email, Role, Status, Created, and Actions. Features include:

• Org context filtering — Agents are filtered by the selected organization via useOrgContext()
• Permission-based filtering — If the logged-in user has restricted permissions, only allowed agents are shown
• Quick actions — "View Details" navigates to the agent detail page; the refresh icon triggers a restart
• Empty state — When no agents exist, a prompt encourages creating the first one

API Reference

Permissions & Security

Side Effects Reference

Rate Limits

Best Practices

• Start with a soul template — Templates provide battle-tested configurations. Customize from there rather than building from scratch.
• Use permission presets first — Start with "Strict" and loosen as you build trust with the agent's behavior.
• Enable auto-onboarding — The onboarding pipeline ensures agents go through compliance checks and guardrail verification before going live.
• Set meaningful rate limits — Prevent runaway agents by setting appropriate per-minute and per-hour limits.
• Use sandbox mode for testing — Enable sandbox in execution constraints to simulate actions without real side effects.
• Save drafts — For complex agents, use the "Save Draft" button. Drafts persist across browser sessions.
• Deploy to Fly.io for production — Fly.io provides auto-scaling, TLS, and health checks out of the box.

Troubleshooting