STEP 4 OF 8

Agents

The Agents page (/agents in the sidebar) is a workforce roster of named AI engineers — Atlas, Marcus, Maya, Felix, and others — not a bare list of generic agent records. Each engineer has a role, a vertical, a tier (1–4, evidence-gated), and a skill list. This guide covers the roster, hiring an engineer onto an engagement, and the KG-suggested pre-built agents panel. The API behind all of this is /api/v1/workforce/* (app/api/v1/endpoints/workforce.py), a distinct system from the generic /api/v1/agents CRUD used in Getting Started.

The roster

curl "https://your-control-plane-host/api/v1/workforce/agents" \
  -H "Authorization: Bearer $TOKEN"

Each engineer carries tier, status (available / engaged / retired), skills (SkillCredentialSummary[]), engagements_completed, and avg_rating. Tiers are earned, not assigned — cleared eval-gauntlet tasks, per components/workforce/TierBadge.tsx:

| Tier | Label | Gate | |------|-------|------| | 1 | Apprentice | 50+/200 graded tasks — drafts only, no unsupervised production actions | | 2 | Production-Ready | 130+/200 across two evaluators — reversible production actions unsupervised | | 3 | Expert | 180+/200 plus a domain compliance harness (HIPAA, SOX-404) — regulated scopes with audit | | 4 | Specialist | Full 200-task gauntlet plus an adversarial harness — can adjudicate disputes, set Rule Book precedent |

Hiring an engineer

"Hiring" assigns an existing roster engineer to an engagement's pod — it does not create a new agent:

curl -X POST https://your-control-plane-host/api/v1/workforce/hire \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<engineer_id>",
    "engagement_id": "<engagement_id>",
    "role_on_pod": "Lead Engineer",
    "reason": "Prior Snowflake migration experience"
  }'

# See who's assigned to an engagement
curl https://your-control-plane-host/api/v1/workforce/engagements/{engagement_id}/pod \
  -H "Authorization: Bearer $TOKEN"

KG-suggested pre-built agents

The "Suggested from your knowledge graph" panel at the top of /agents is generated, not curated — it reads real entities and relationships already promoted into your Knowledge Graph (Step 2) and turns each domain into a starting agent persona. Click Generate suggestions to call:

curl -X POST https://your-control-plane-host/api/v1/workforce/agents/suggest-from-kg \
  -H "Authorization: Bearer $TOKEN"

Each candidate card shows why_suggested (e.g. "Grounded in your 'Finance' knowledge-graph domain (42 entities, 67 relationships)"), a handful of sample_entity_labels, and a Use this button. If your graph has no promoted content yet, the panel says so explicitly and links back to Memory rather than fabricating a suggestion — this is the reason Steps 1–2 come before this one in the track.

Clicking Use this POSTs a CreateCustomAgentBody with created_via: "kg_generated":

curl -X POST "https://your-control-plane-host/api/v1/workforce/agents?tenant_id=$TENANT_ID" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "Finance Analyst",
    "role": "Finance Domain Specialist",
    "vertical": "Finance",
    "tier": 3,
    "persona_prompt": "...",
    "created_via": "kg_generated"
  }'

Creating a custom agent from scratch

/agents/new is the same workforceApi.create() call with a blank persona editor (Monaco, markdown) instead of a KG-derived one — set name, role, vertical, starting tier, a persona prompt, and optionally seed skills (skill_keys: [{skill, level, evidence_url}]) at creation time.

What's next

Step 5 — Skills & Code: open any engineer's /edit page to customize persona, skills, code, and model/tool behavior, and test the change before saving.