🔧 Agent Configuration

Step-by-step guide to configuring cognitive agents.

Creating an Agent

1. Define the Agent File

Create agents/<name>.agent.yaml:

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
27
28

agentId: "my-analyst"
skill: "document-analysis"
description: "Analyzes documents for key insights"

# Model configuration
model: "claude-sonnet"
maxOutputTokens: 1000
temperature: 0.7

# Available tools
tools:
  - "read-document"
  - "query-knowledge-graph"
  - "write-artifact"

# Output schema (required)
outputSchema:
  type: object
  required: ["findings", "confidence"]
  properties:
    findings:
      type: array
      items:
        type: string
    confidence:
      type: number
      minimum: 0
      maximum: 1

2. Define Output Schema

Create schemas/my-analyst-output.json:

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

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["findings", "confidence"],
  "properties": {
    "findings": {
      "type": "array",
      "items": { "type": "string" },
      "maxItems": 10
    },
    "confidence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    }
  }
}

3. Register in Router

Edit router-config.yaml:

1
2
3
4
5

specialists:
  - agentId: "my-analyst"
    skill: "document-analysis"
    outputSchema: "schemas/my-analyst-output.json"
    maxOutputTokens: 1000

4. Configure Tools

Define tool permissions:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

tools:
  read-document:
    description: "Read document content"
    permissions:
      - "read:documents"
    inputSchema:
      type: object
      properties:
        documentId:
          type: string
  
  query-knowledge-graph:
    description: "Query the Knowledge Graph"
    permissions:
      - "read:kgs"
    inputSchema:
      type: object
      properties:
        sparql:
          type: string

5. Test the Agent

1
2
3
4
5
6
7
8
9
10

# Validate configuration
just cognitive-validate --agent my-analyst

# Test in isolation
just cognitive-test-agent \
  --agent my-analyst \
  --input "Analyze this quarterly report..."

# Check output matches schema
just cognitive-validate-output --agent my-analyst

Configuration Options

Option Type Description
agentId string Unique identifier
skill string Skill name
model string LLM model to use
maxOutputTokens number Token limit
temperature number Creativity (0-1)
tools array Available tools
outputSchema object/ref Output structure

Best Practices

✅ Do

❌ Avoid