Agent Configuration

GitHub Repository | Overview | Architecture

Agents are defined declaratively in TOML files. This enables course designers to create tutoring experiences without writing code.

File Structure

Each course contains an agents.toml file:

config/agents/
└── college-essay.toml
└── math-tutoring.toml
└── cs61A.toml

Full Example: College Essay Tutor

config/courses/college-essay/agents.toml

# =============================================================================
# AGENT DEFINITION
# =============================================================================
[agent]
name = "Essay Coach"
model = "anthropic/claude-sonnet-4"  # OpenRouter model ID
system_prompt = """
You are a college essay coach helping students discover and articulate
their authentic stories. You don't write essays for students—you help
them find what to write about.

Focus on:
- Drawing out specific memories and experiences
- Identifying patterns in what energizes them
- Challenging generic or expected narratives
- Asking questions that reveal character

Review the student's profile before each session. Propose updates when
you learn something significant about them.
"""

# Tools available to this agent
tools = [
  "file_tools",      # FileTools - read/write workspace files
  "shell_tools",     # ShellTools - execute commands
  "honcho_tools",    # HonchoTools - query conversation history
  "memory_blocks",   # MemoryBlockTools - read/propose block edits
  "latex_tools",     # LaTeXTools - generate PDF notes
]

# Memory blocks this agent can access
blocks = ["student", "journey", "essays"]


# =============================================================================
# MEMORY BLOCK SCHEMAS
# =============================================================================
[[block]]
label = "student"           # Unique identifier (used in Dolt)
title = "Student Profile"   # Display name
template = """
## About Me

[Background, interests, personality]

## How I Work

[Learning style, preferences, schedule]

## Current Goals

[What they're working toward]
"""

[[block]]
label = "journey"
title = "Discovery Journey"
template = """
## Key Experiences

[Significant moments and stories]

## Themes & Patterns

[Recurring interests, values, contradictions]

## Essay Ideas

[Potential topics with notes]
"""

[[block]]
label = "essays"
title = "Essay Tracker"
template = """
## Schools

| School | Prompt | Status | Notes |
|--------|--------|--------|-------|

## Drafts

[Links to draft files in workspace]
"""


# =============================================================================
# BACKGROUND TASKS
# =============================================================================
[[task]]
name = "weekly-reflection"
trigger = { type = "cron", schedule = "0 9 * * 1" }  # Monday 9 AM
system_prompt = """
Review this student's activity from the past week. Look for:
- Progress on essays
- New insights about their story
- Areas where they seem stuck

Write a brief reflection in their workspace and propose any
updates to their profile based on what you've observed.
"""
tools = ["honcho_tools", "memory_blocks", "file_tools"]
blocks = ["student", "journey"]


[[task]]
name = "idle-checkin"
trigger = { type = "idle", idle_minutes = 4320, cooldown_minutes = 10080 }  # 3 days idle, 1 week cooldown
system_prompt = """
This student hasn't been active in a few days. Review their
current progress and draft a friendly check-in message suggesting
a next step they could take.
"""
tools = ["honcho_tools", "file_tools"]
blocks = ["student", "essays"]

Schema Reference

Agent Definition

Field	Required	Description
name	Yes	Display name for the agent
model	Yes	OpenRouter model ID (e.g., anthropic/claude-sonnet-4)
system_prompt	Yes	Multi-line prompt defining agent behavior
tools	Yes	List of tool IDs available to the agent
blocks	Yes	List of memory block labels the agent can access

Memory Blocks

Field	Required	Description
label	Yes	Unique identifier (used in Dolt database)
title	Yes	Human-readable display name
template	Yes	Initial markdown content for new users

Background Tasks

Field	Required	Description
name	Yes	Unique task identifier
trigger	Yes	When to run (see Trigger Types below)
system_prompt	Yes	Instructions for the background agent
tools	Yes	Subset of tools available to this task
blocks	Yes	Memory blocks the task can access

Trigger Types

CronTrigger

Standard cron expressions for scheduled execution:

trigger = { type = "cron", schedule = "0 9 * * 1" }  # Monday 9 AM
trigger = { type = "cron", schedule = "0 3 * * *" }  # Daily at 3 AM

IdleTrigger

Fires after user inactivity:

trigger = { type = "idle", idle_minutes = 4320, cooldown_minutes = 10080 }

• idle_minutes: Time since last user activity before triggering
• cooldown_minutes: Minimum time between triggers for same user

Available Tools

Tool ID	Class	Capabilities
file_tools	FileTools	Read, write, list files in workspace
shell_tools	ShellTools	Execute shell commands in workspace
honcho_tools	HonchoTools	Query student’s conversation history
memory_blocks	MemoryBlockTools	List, read, propose edits to blocks
latex_tools	LaTeXTools	Render LaTeX to PDF

Custom tools can be registered by adding to the tool registry.

Block Sharing Across Courses

Multiple agents.toml files can reference the same block label:

# college-essay/agents.toml - DEFINES the student block
blocks = ["student", "essays"]

[[block]]
label = "student"
template = "..."

# math-tutoring/agents.toml - USES the student block (no redefinition)
blocks = ["student", "math-progress"]

[[block]]
label = "math-progress"
template = "..."

Rules:

• Only one agents.toml can define a [[block]] schema for a given label
• Conflicting schema definitions are flagged at startup
• Blocks check if the user already has content before initializing from template
• This enables shared context (like “student”) across different tutoring domains

Compilation and Validation

At startup, the system:

1. Scans config/courses/*/agents.toml for all course definitions
2. Validates each file against the schema
3. Detects conflicts: If two courses define [[block]] with the same label but different schemas, startup fails with an error
4. Registers agents, blocks, and tasks in the runtime registry