Skip to content
⚗️ Crucible

Agents & Protocols

Crucible connects AI agents to your knowledge. This page explains how that connection works.

What is an Agent?

Section titled “What is an Agent?”

An agent is an AI that can take actions - not just answer questions, but search your notes, create files, and use tools. Agents have:

  • A model - The AI (like Claude, GPT-4, or Llama)
  • Tools - Actions they can take (search, read, create)
  • Context - Information they can access (your kiln)

Agent Cards

Section titled “Agent Cards”

An agent card configures how an AI behaves:

name: Researcher
model: claude-3-opus
tools:
  - semantic_search
  - read_note
instructions: |
  You help explore and synthesize knowledge.
  Always cite sources using [[wikilinks]].

See Agent Cards for full details.

Protocols: MCP and ACP

Section titled “Protocols: MCP and ACP”

Crucible uses two protocols for agent communication:

MCP (Model Context Protocol)

Section titled “MCP (Model Context Protocol)”

MCP is a standard for AI tools. It defines how agents discover and use capabilities.

Use MCP when:

  • Connecting external tools (GitHub, databases, APIs)
  • Sharing tools between different AI systems
  • Building general-purpose integrations

See MCP Gateway for connecting MCP servers.

ACP (Agent Context Protocol)

Section titled “ACP (Agent Context Protocol)”

ACP extends MCP with features for continuous agent interaction:

  • Session persistence
  • Multi-turn conversations
  • Workflow orchestration

Use ACP when:

  • Building complex agent workflows
  • Agents need to coordinate
  • Long-running tasks with state

Using Agents

Section titled “Using Agents”

Start a chat session:

Terminal window
cru chat

Use a specific agent:

Terminal window
cru chat --agent Researcher

Context Management

Section titled “Context Management”

Agents need context to work effectively, but context windows are finite and attention degrades in long conversations.

Key strategies:

  1. File-as-state: Store progress in files (like TASKS.md) instead of accumulating message history
  2. Cached prefixes: Put static context (system prompt, task definitions) at the start—cached tokens are 75% cheaper
  3. Curated handoffs: Pass summaries between agents, not full conversation history

See Task Management for implementation details.

Tool Execution

Section titled “Tool Execution”

When an agent calls a tool during a session, the daemon dispatches the call through a ToolDispatcher that routes to the correct executor (built-in tools, Lua plugins, or MCP servers).

Timeout: Every tool call has a hard 30-second timeout. If a tool doesn’t return within 30 seconds, the call is cancelled and the agent receives an error message like Tool 'semantic_search' timed out after 30 seconds. The agent can then retry or try a different approach.

This timeout prevents runaway tool calls from blocking a session indefinitely. It applies uniformly to all tool types: built-in Rust tools, Lua plugin tools, and tools proxied from external MCP servers.

See Also

Section titled “See Also”