Agent tools

Knowledge Base

save_to_knowledge_base

Persist a fact or note to the agent knowledge base for future retrieval. Writes to the agent-notes FAISS sub-index when FAISS is available, and falls back to a JSONL log when it is not.

Parameters:

Returns: Confirmation string on success, or an error message

query_knowledge_base

Search the knowledge base for information from uploaded documents. Searches all available FAISS indexes — both the global CLI index (data/vectordb/faiss_index/) and per-document API indexes (data/api/uploads/{doc_id}/vectordb/faiss_index/).

Requires: Vector store built with python cogtrix.py --ingest or documents uploaded via the API

Auto-activation: When a knowledge base exists, this tool is automatically pinned as active at startup (no need to load it via request_tools). Its description dynamically shows the number of indexes and total size.

Parameters:

Returns: Relevant document chunks with sources

See RAG_GUIDE.md for setup instructions.

Delegation

delegate_task

Delegate a single task to another LLM model.

Parameters:

Model Resolution:

model: "fast"                    → Uses string alias from config
model: "deep"                    → Uses object alias (with context_window, temperature)
model: "ollama/qwen3:8b"         → Direct provider/model
model: "openai/gpt-4.1"           → Direct provider/model

Object entries can override context_window, temperature, and timeout per model. Note: context_window is forwarded to Ollama as num_ctx and silently ignored for other providers. See Configuration: Models section for model entry format details and Delegate section for allowed_models restrictions.

delegate_parallel

Run multiple tasks in parallel across LLM models.

Parameters:

Task Object:

{
  "task": "Summarize this article",
  "model": "fast",
  "context": "Article text here...",
  "provider": "ollama",
  "temperature": 0.5,
  "response_format": "text",
  "use_tools": true
}

Only task is required; other fields are optional.

Returns: List of results from all tasks

Agent Task Management

spawn_agent

Spawn a sub-agent to run a task independently and return a result.

Parameters:

Returns: Task ID and initial status; poll get_task_result for the outcome.

get_task_status

Check the status of a spawned sub-agent task.

Parameters:

Returns: Status string (running, completed, failed, cancelled) and timestamp.

get_task_result

Retrieve the result of a completed sub-agent task.

Parameters:

Returns: Task result (string or object), error message if failed, and completion timestamp.

list_tasks

List all active sub-agent tasks.

Parameters:

Returns: Table of task IDs, descriptions, statuses, and creation times.

cancel_task

Cancel a running sub-agent task.

Parameters:

Returns: Confirmation or error if task already completed.

Agent Messaging

send_to_agent

Send a message to another agent’s inbox.

Parameters:

Returns: Confirmation with delivery timestamp.

read_agent_inbox

Read messages from the current agent’s inbox.

Parameters:

Returns: List of messages with sender, timestamp, content, and read status.

Self-Improvement

self_improve

Analyze recent errors and automatically generate improvements to tool prompts or agent behavior.

Parameters:

Returns: Summary of changes made and which files were updated.

Deep Reasoning

deep_think

Tree-of-Thought with Chain-of-Thought Reflection engine for complex problems.

Also available as: /think <task> slash command (invokes deep_think directly, bypassing agent tool selection).

How It Works:

The engine runs multiple iterations, each with three phases:

1. Branch — Generate N fundamentally different approaches (1 LLM call)
2. Develop — Full Chain-of-Thought for each approach in parallel: Plan → Execute → Observe → Reflect (N parallel LLM calls)
3. Converge — Evaluate all solutions, cross-pollinate best ideas, synthesize an improved solution (1 LLM call)

Between iterations, the reflection output feeds into the next branching phase, progressively refining the solution. Stops when confidence is high or max iterations reached.

Parameters:

LLM calls per iteration: N + 2 (where N = num_branches)

Typical duration: 1-5 minutes depending on model speed and parameters.

Returns: Structured analysis report with:

• Scored approaches from each iteration
• Reflection insights
• Final synthesized solution with confidence rating

When the LLM uses this tool automatically:

The agent is guided to use deep_think when it encounters:

• Problems with multiple valid approaches or significant trade-offs
• Requests for thorough analysis, deep research, or “think step by step”
• Architecture/design decisions, strategy planning
• Complex debugging where the root cause is unclear
• Comparing or evaluating multiple options systematically

In reasoning mode (-M reasoning), the agent receives extra encouragement to use this tool for decisions with trade-offs.

Example:

deep_think(
  task="Design a caching strategy for a microservices architecture
        with 50 services and mixed read/write workloads",
  context="Budget: moderate. Must handle 10K req/s. Latency < 50ms.",
  max_iterations=3,
  num_branches=3
)