🚀 Cognitive Architecture Quick Start

Get started with AI reasoning and agent orchestration.

Prerequisites

Tool Version Purpose
Python 3.11+ Agent runtime
just 1.0+ Task runner
LiteLLM latest LLM provider

1. Configure LLM Provider

1
2
3
4
5
6
7

# Set API keys in .env
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...

# Or use local Ollama
export LLM_PROVIDER=ollama
export OLLAMA_BASE_URL=http://localhost:11434

2. Define an Agent

Create agents/my-analyst.agent.yaml:

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

agentId: "my-analyst"
skill: "document-analysis"
model: "claude-sonnet"
maxOutputTokens: 1000
tools:
  - "read-document"
  - "query-knowledge-graph"
outputSchema:
  type: object
  properties:
    findings:
      type: array
      items:
        type: string
    confidence:
      type: number

3. Create Router Configuration

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

# router-config.yaml
router:
  agentId: "router-v1"
  model: "claude-sonnet"
  maxOutputTokens: 200

specialists:
  - agentId: "my-analyst"
    skill: "document-analysis"
    maxOutputTokens: 1000

aggregator:
  strategy: "weighted-merge"
  conflictResolution: "majority-vote"

execution:
  maxRounds: 3
  convergenceThreshold: 0.95

4. Run Cognitive Workflow

1
2
3
4
5
6
7

# Execute with query
just cognitive-run \
  --config router-config.yaml \
  --query "Analyze the quarterly report"

# View execution trace
just cognitive-trace --workflow-id <id>

5. Verify Output

1
2
3
4
5

# Check governance violations
just cognitive-validate --workflow-id <id>

# Export results
just cognitive-export --workflow-id <id> --format json

Common Issues

Issue Solution
API key not found Set environment variable
Token budget exceeded Reduce maxOutputTokens
Schema validation failed Check output schema
Convergence not reached Increase maxRounds

Next Steps