🤖 Specialist Agents

Bounded skill execution for cognitive workflows.

Overview

Specialist Agents are narrow-skill executors that produce bounded, structured output. Each specialist has a defined capability and contributes to the shared ContextSnapshot.

Agent Catalog

Agent Purpose Output Schema
Semantic Mapper Bind terms to ConceptIDs { "mappings": [...] }
Rule Analyst Evaluate SBVR constraints { "violations": [], "satisfactions": [] }
Architecture Checker CALM boundary checks { "boundaryStatus": "ok" | "violation" }
Retrieval Agent KGS context lookup { "nodes": [], "edges": [] }
Synthesis Agent Combine and transform { "output": {...} }
Code Generator Generate code artifacts { "files": [...] }

Agent Configuration

Basic Structure

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

agentId: "semantic-mapper"
skill: "term-to-concept-binding"
description: "Binds natural language terms to semantic ConceptIDs"

model: "claude-sonnet"
maxOutputTokens: 500

tools:
  - "read-kgs"
  - "query-sbvr"

outputSchema:
  type: object
  required: ["mappings"]
  properties:
    mappings:
      type: array
      items:
        type: object
        properties:
          term:
            type: string
          conceptId:
            type: string
          confidence:
            type: number

Output Contracts

Specialists must produce:

  1. Bounded deltas - Structured JSON, not prose
  2. Schema-conformant - Match declared output schema
  3. Within budget - Not exceed token limit

Example Output

1
2
3
4
5
6

{
  "mappings": [
    { "term": "customer", "conceptId": "sea:customer:001", "confidence": 0.95 },
    { "term": "order", "conceptId": "sea:order:002", "confidence": 0.88 }
  ]
}

Specialist Types

Semantic Mapper

Binds natural language terms to semantic ConceptIDs.

1
2
3
4
5
6
7
8

agentId: "semantic-mapper"
skill: "term-to-concept-binding"
tools: ["read-kgs", "query-semantic-core"]
outputSchema:
  type: object
  properties:
    mappings:
      type: array

Rule Analyst

Evaluates SBVR business rules against context.

1
2
3
4
5
6
7
8
9
10
11
12

agentId: "rule-analyst"
skill: "sbvr-evaluation"
tools: ["query-sbvr"]
outputSchema:
  type: object
  properties:
    violations:
      type: array
    satisfactions:
      type: array
    unknowns:
      type: array

Architecture Checker

Validates CALM architecture boundaries.

1
2
3
4
5
6
7
8
9
10
11

agentId: "arch-checker"
skill: "calm-boundary-validation"
tools: ["read-calm"]
outputSchema:
  type: object
  properties:
    boundaryStatus:
      type: string
      enum: ["ok", "violation"]
    details:
      type: array

Retrieval Agent

Retrieves relevant context from Knowledge Graph.

1
2
3
4
5
6
7
8
9
10
11
12

agentId: "retrieval-agent"
skill: "context-retrieval"
tools: ["read-kgs", "vector-search"]
outputSchema:
  type: object
  properties:
    nodes:
      type: array
    edges:
      type: array
    relevanceScores:
      type: array

Creating Custom Specialists

1. Define the Agent

1
2
3
4
5
6
7
8
9

# agents/custom-analyst.agent.yaml
agentId: "custom-analyst"
skill: "domain-specific-analysis"
model: "claude-sonnet"
maxOutputTokens: 500
tools:
  - "custom-tool"
outputSchema:
  $ref: "schemas/custom-output.json"

2. Register the Agent

1
2
3

# router-config.yaml
specialists:
  - $ref: "agents/custom-analyst.agent.yaml"

3. Define Output Schema

1
2
3
4
5
6
7
8
9

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["result"],
  "properties": {
    "result": { "type": "string" },
    "confidence": { "type": "number" }
  }
}

Best Practices

✅ Do

❌ Avoid