Skip to main content

Source 1: A config file with a problem

Perception is how the agent sees its environment. An agent without toolsets is blind - it can only use training data. Each toolset you add is a new sensor.

Step 1: Create a project with multiple "perception sources"​

mkdir ~/perception-test && cd ~/perception-test


cat > config.json << 'EOF'
{
  "app_name": "MyApp",
  "version": "2.1.0",
  "database": {
    "host": "localhost",
    "port": 5432,
    "password": "admin123"
  },
  "debug": true,
  "api_key": "sk-1234567890abcdef"
}
EOF

# Source 2: A deployment script
cat > deploy.sh << 'EOF'
#!/bin/bash
echo "Deploying MyApp..."
docker run -e DB_PASSWORD=admin123 -e API_KEY=sk-1234567890abcdef myapp:latest
echo "Deploy complete"
EOF

# Source 3: A README with context
cat > README.md << 'EOF'
# MyApp
Production-ready application. 
Ensure no secrets are hardcoded before deploying.
Run security checks before every release.
EOF

Step 2: Create agent with MULTIPLE perception layers​

# perception.yaml
version: "2"

agents:
  root:
    model: openai/gpt-5-mini
    description: Security auditor with multi-layer perception
    instruction: |
      You are a security auditor. You can perceive the environment through:
      
      1. FILESYSTEM perception - Read all files in the current directory
      2. SHELL perception - Run commands like `grep`, `find`, `cat` to scan
      3. WEB perception - Search for latest security best practices
      
      Audit this project for security issues. Use ALL your senses:
      - Read every file to find hardcoded secrets
      - Run shell commands to scan for patterns like passwords, API keys
      - Search the web for current best practices on secret management
      
      Report what you found using each perception method.
    toolsets:
      - type: filesystem
      - type: shell
      - type: mcp
        ref: docker:duckduckgo

Step 3: Run it​

export OPENAI_API_KEY=<your_key>
cagent run ./perception.yaml

Then type:

Audit this project for security issues. Use filesystem, shell, and web search.

What you should see​

✓ Read    config.json           ← FILESYSTEM perception (sees the file contents)
✓ Read    deploy.sh             ← FILESYSTEM perception (sees hardcoded secrets)
✓ Read    README.md             ← FILESYSTEM perception (sees project context)
✓ Shell   grep -r "password" .  ← SHELL perception (scans for patterns)
✓ Shell   grep -r "api_key" .   ← SHELL perception (finds exposed keys)
✓ Search  "secret management best practices 2025"  ← WEB perception (sees the internet)

Key Teaching Point​

ToolsetWhat it "sees"Analogy
filesystemFiles, code, configs👁 Eyes - reading documents
shellSystem state, grep output, process info👂 Ears - listening to the system
mcp: duckduckgoLive web, latest best practices📡 Radar - sensing the outside world

Remove a toolset = the agent goes partially blind. Try removing the mcp: duckduckgo line and running again - the agent can no longer search the web. That's the proof that each toolset is literally a perception channel.

Bonus: Prove perception matters​

Create a version with NO toolsets:

# blind-agent.yaml
version: "2"

agents:
  root:
    model: openai/gpt-5-mini
    description: Security auditor with NO perception
    instruction: |
      Audit this project for security issues.
    # No toolsets = no perception = blind agent

Run it and compare - the blind agent can only give generic advice. It cannot actually see your code. That's the difference between a chatbot and an agent.