🧩 Agent Patterns

Best practices for cognitive agent design.

Specialist Agent Patterns

Narrow Skill Pattern

Each agent has ONE focused skill:

1
2
3
4
5
6
7

# ✅ Good: Single responsibility
agentId: "term-binder"
skill: "term-to-concept-binding"

# ❌ Avoid: Multiple responsibilities
agentId: "do-everything"
skill: "bind-terms-and-evaluate-rules-and-check-architecture"

Bounded Output Pattern

Always define strict output limits:

1
2
3
4
5
6
7
8

agentId: "analyst"
maxOutputTokens: 500
outputSchema:
  type: object
  properties:
    findings:
      type: array
      maxItems: 10  # Bounded!

Router Patterns

Normalized Weights

Router weights MUST sum to 1.0:

1
2
3
4
5
6
7

{
  "distribution": [
    { "agentId": "a", "weight": 0.4 },
    { "agentId": "b", "weight": 0.35 },
    { "agentId": "c", "weight": 0.25 }
  ]
}

Dynamic Tool Scoping

Grant minimum necessary permissions:

1
2
3
4

{
  "distribution": [...],
  "toolPermissions": ["read-kgs"]  // Only what's needed
}

Aggregation Patterns

Delta-Only Updates

Agents produce changes, not full state:

1
2
3
4
5

{
  "operation": "add",
  "path": "$.bindings.customer",
  "value": "sea:customer:001"
}

Conflict Resolution

When specialists disagree:

1
2
3

aggregator:
  conflictResolution: "majority-vote"
  # Options: majority-vote, highest-weight, union, expert-override

Governance Patterns

Fail-Fast Validation

Check critical invariants early:

1
2
3
4
5
6

validator:
  checks:
    - type: "schema"        # First: format
    - type: "identity"      # Second: invariants
    - type: "policy"        # Third: business rules
  onViolation: "block"

HITL Escalation

Escalate high-risk decisions:

1
2
3
4
5

escalation:
  triggers:
    - severity: "critical"
    - agentId: "high-risk-agent"
  handler: "hitl-approval"

Prompt Patterns

Structured Output Instruction

1
2
3
4
5
6
7

Your output MUST be valid JSON matching:
{
  "findings": ["string"],
  "confidence": 0.0-1.0
}

DO NOT include any text before or after the JSON.

Role Anchoring

1
2
3
4
5
6
7
8

You are a **Semantic Mapper** agent. Your ONLY job is:
- Bind natural language terms to ConceptIDs
- Provide confidence scores

You are NOT responsible for:
- Evaluating business rules
- Generating code
- Making decisions

Anti-Patterns

❌ Unbounded Output

1
2
3
4

# Bad: No limits
agentId: "verbose-agent"
# No maxOutputTokens
# No schema constraints

❌ Identity Drift

1
2
3

# Bad: Allows concepts to rename
validator:
  checks: []  # No identity check

❌ Infinite Loops

1
2
3

# Bad: No round limit
execution:
  maxRounds: null  # Could run forever

❌ Political Arbitration

1
2
3
4

# Bad: No normalized weights
# "Loudest agent wins"
aggregator:
  strategy: "first-response"

Composition Pattern

Chain workflows for complex tasks:

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

workflow:
  name: "document-analysis"
  stages:
    - name: "extraction"
      router: "extraction-router.yaml"
      output: "extracted-data"
    
    - name: "validation"
      router: "validation-router.yaml"
      input: "extracted-data"
      output: "validated-data"
    
    - name: "synthesis"
      router: "synthesis-router.yaml"
      input: "validated-data"