Reasoning Tools

The problem: Reasoning Agents force systematic thinking on every request. Reasoning Models require specialized models. What if you want reasoning only when needed, tailored to specific contexts? The solution: Reasoning Tools give your agent explicit think() and analyze() tools, and let the agent decide when to use them. The agent chooses when to reason, when to act, and when it has enough information to respond.

Kern provides four specialized reasoning toolkits, each optimized for different domains:

Note: All reasoning toolkits register their think()/analyze() functions under the same names. When you combine toolkits, the agent keeps only the first implementation of each function name and silently drops duplicates. Disable enable_think/enable_analyze (or rename/customize functions) on the later toolkits if you still want them to expose their domain-specific actions without conflicting with the scratchpad tools.

All four toolkits follow the same Think → Act → Analyze pattern but provide domain-specific actions tailored to their use case.

This approach was first popularized by Anthropic in their "Extended Thinking" blog post, though many AI engineers (including our team) were using similar patterns long before.

Why Reasoning Tools?

Reasoning Tools give you the best of both worlds:

1. Works with any model - Even models without native reasoning capabilities
2. Explicit control - The agent decides when to think vs. when to act
3. Full transparency - You see exactly what the agent is thinking
4. Flexible workflow - The agent can interleave thinking with tool calls
5. Domain-optimized - Each toolkit is specialized for its specific use case
6. Natural reasoning - Feels more like human problem-solving (think, act, analyze, repeat)

The key difference: With Reasoning Agents, the reasoning happens automatically in a structured loop. With Reasoning Tools, the agent explicitly chooses when to use the think() and analyze() tools, giving you more control and visibility.

The Four Reasoning Toolkits

1. ReasoningTools - General Purpose Thinking

For general problem-solving without domain-specific tools.

What it provides:

• think() - Plan and reason about the problem
• analyze() - Evaluate results and determine next steps

When to use:

• Mathematical or logical problems
• Strategic planning
• Analysis tasks that don't require external data
• Any scenario where you want structured reasoning

Example:

1from kern.agent import Agent
2from kern.models.openai import OpenAIResponses
3from kern.tools.reasoning import ReasoningTools
4
5agent = Agent(
6    model=OpenAIResponses(id="gpt-5.2"),
7    tools=[ReasoningTools(add_instructions=True)],
8)
9
10agent.print_response(
11    "Which is bigger: 9.11 or 9.9? Explain your reasoning.",
12    stream=True,
13)

2. KnowledgeTools - Reasoning with Knowledge Bases

For searching and analyzing information from knowledge bases (RAG).

What it provides:

• think() - Plan search strategy and refine approach
• search_knowledge() - Query the knowledge base
• analyze() - Evaluate search results for relevance and completeness

When to use:

• Document retrieval and analysis
• RAG (Retrieval-Augmented Generation) workflows
• Research tasks requiring multiple search iterations
• When you need to verify information from knowledge bases

Example:

1from kern.agent import Agent
2from kern.knowledge.pdf import PDFKnowledgeBase
3from kern.models.openai import OpenAIResponses
4from kern.tools.knowledge import KnowledgeTools
5from kern.vectordb.pgvector import PgVector
6
7# Create knowledge base
8knowledge = PDFKnowledgeBase(
9    path="data/research_papers/",
10    vector_db=PgVector(
11        table_name="research_papers",
12        db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
13    ),
14)
15
16agent = Agent(
17    model=OpenAIResponses(id="gpt-5.2"),
18    tools=[KnowledgeTools(knowledge=knowledge, add_instructions=True)],
19    instructions="Search thoroughly and cite your sources",
20)
21
22agent.print_response(
23    "What are the latest findings on quantum entanglement in our research papers?",
24    stream=True,
25)

How it works:

1. Agent calls think(): "I need to search for quantum entanglement. Let me try multiple search terms."
2. Agent calls search_knowledge("quantum entanglement")
3. Agent calls analyze(): "Results are too broad. Need more specific search."
4. Agent calls search_knowledge("quantum entanglement recent findings")
5. Agent calls analyze(): "Now I have sufficient, relevant results."
6. Agent provides final answer

3. MemoryTools - Reasoning about User Memories

For managing and reasoning about user memories with CRUD operations.

What it provides:

• think() - Plan memory operations
• get_memories() - Retrieve user memories
• add_memory() - Store new memories
• update_memory() - Modify existing memories
• delete_memory() - Remove memories
• analyze() - Evaluate memory operations

When to use:

• Personalized agent interactions
• User preference management
• Maintaining conversation context across sessions
• Building user profiles over time

Example:

1from kern.agent import Agent
2from kern.db.postgres import PostgresDb
3from kern.models.openai import OpenAIResponses
4from kern.tools.memory import MemoryTools
5
6db = PostgresDb(
7    db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
8)
9
10agent = Agent(
11    model=OpenAIResponses(id="gpt-5.2"),
12    tools=[MemoryTools(db=db, add_instructions=True)],
13    db=db,
14)
15
16agent.print_response(
17    "I prefer vegetarian recipes and I'm allergic to nuts.",
18    user_id="user_123",
19)

How it works:

1. Agent calls think(): "User is sharing dietary preferences. I should store this."
2. Agent calls add_memory(memory="User prefers vegetarian recipes and is allergic to nuts", topics=["dietary_preferences", "allergies"])
3. Agent calls analyze(): "Memory successfully stored with appropriate topics."
4. Agent responds to user confirming the information was saved

4. WorkflowTools - Reasoning about Workflow Execution

For executing and analyzing complex workflows.

What it provides:

• think() - Plan workflow inputs and strategy
• run_workflow() - Execute a workflow with specific inputs
• analyze() - Evaluate workflow results

When to use:

• Multi-step automated processes
• Complex task orchestration
• When workflows need different inputs based on context
• A/B testing different workflow configurations

Example:

1from kern.agent import Agent
2from kern.models.openai import OpenAIResponses
3from kern.tools.workflow import WorkflowTools
4from kern.workflow import Workflow
5from kern.workflow.step import Step
6
7# Define a research workflow
8research_workflow = Workflow(
9    name="research-workflow",
10    steps=[
11        Step(name="search", agent=search_agent),
12        Step(name="summarize", agent=summary_agent),
13        Step(name="fact-check", agent=fact_check_agent),
14    ],
15)
16
17# Create agent with workflow tools
18orchestrator = Agent(
19    model=OpenAIResponses(id="gpt-5.2"),
20    tools=[WorkflowTools(workflow=research_workflow, add_instructions=True)],
21)
22
23orchestrator.print_response(
24    "Research climate change impacts on agriculture",
25    stream=True,
26)

How it works:

1. Agent calls think(): "I need to run the research workflow with 'climate change agriculture' as input."
2. Agent calls run_workflow(input_data="climate change impacts on agriculture")
3. Workflow executes all steps (search → summarize → fact-check)
4. Agent calls analyze(): "Workflow completed successfully. All fact-checks passed."
5. Agent provides final synthesized answer

Common Pattern: Think → Act → Analyze

All four toolkits follow the same reasoning cycle:

1. THINK - Plan what to do, refine approach, brainstorm
2. ACT (Domain-Specific)
   • ReasoningTools: Direct reasoning
   • KnowledgeTools: search_knowledge()
   • MemoryTools: get/add/update/delete_memory()
   • WorkflowTools: run_workflow()
3. ANALYZE - Evaluate results, decide next action
4. REPEAT - Loop back to THINK if needed, or provide answer

This mirrors how humans solve complex problems: we think before acting, evaluate results, and adjust our approach based on what we learn.

Choosing the Right Reasoning Toolkit

Combining Multiple Reasoning Toolkits

You can use multiple reasoning toolkits together for powerful multi-domain reasoning. Just remember that tool names must stay unique, so disable overlapping think/analyze entries (or rename the later ones) to prevent silent overrides:

1from kern.agent import Agent
2from kern.knowledge.pdf import PDFKnowledgeBase
3from kern.models.openai import OpenAIResponses
4from kern.tools.knowledge import KnowledgeTools
5from kern.tools.memory import MemoryTools
6from kern.tools.reasoning import ReasoningTools
7
8agent = Agent(
9    model=OpenAIResponses(id="gpt-5.2"),
10    tools=[
11        ReasoningTools(add_instructions=True),
12        KnowledgeTools(
13            knowledge=my_knowledge,
14            enable_think=False,
15            enable_analyze=False,
16            add_instructions=False,
17        ),
18        MemoryTools(
19            db=my_db,
20            enable_think=False,
21            enable_analyze=False,
22            add_instructions=False,
23        ),
24    ],
25    instructions="Use reasoning for planning, knowledge for facts, and memory for personalization",
26)

With this setup:

• ReasoningTools supplies the shared think/analyze scratchpad.
• KnowledgeTools still exposes search_knowledge() (and any other unique methods) without trying to register duplicate scratchpad functions.
• MemoryTools contributes the CRUD memory tools while inheriting the same central thinking loop.

If you need separate scratchpads per domain, create custom wrappers around think()/analyze() so each toolkit registers uniquely named functions (e.g., knowledge_think, memory_analyze).

Configuration Options

Enable/Disable Specific Tools

You can control which reasoning tools are available:

1# Only thinking, no analysis
2ReasoningTools(enable_think=True, enable_analyze=False)
3
4# Only analysis, no thinking
5ReasoningTools(enable_think=False, enable_analyze=True)
6
7# Both (default)
8ReasoningTools(enable_think=True, enable_analyze=True)
9
10# Shorthand for both
11ReasoningTools()

Add Instructions Automatically

Many toolkits ship with pre-written guidance that explains how to use their tools. Setting add_instructions=True injects those instructions into the agent prompt (when the toolkit actually has any):

1ReasoningTools(add_instructions=True)

• ReasoningTools, KnowledgeTools, MemoryTools, and WorkflowTools all include Kern-authored instructions (and optional few-shot examples) describing their Think → Act → Analyze workflow.
• Other toolkits may not define default instructions; in that case add_instructions=True is a no-op unless you supply your own instructions=....

The built-in instructions cover when to use think() vs analyze(), how to iterate, and best practices for each domain. Turn them on unless you plan to provide custom guidance.

Add Few-Shot Examples

Want to show your agent some examples of good reasoning? Some toolkits come with pre-written few-shot examples that demonstrate the workflow in action. Turn them on with add_few_shot=True:

1ReasoningTools(add_instructions=True, add_few_shot=True)

Right now, ReasoningTools, KnowledgeTools, and MemoryTools have built-in examples. Other toolkits won't use add_few_shot=True unless you provide your own examples.

These examples show the agent how to iterate through problems, decide on next actions, and mix thinking with actual tool calls.

When should you use them?

• You're using a smaller or cheaper model that needs extra guidance
• Your reasoning workflow has multiple stages or is complex
• You want more consistent behavior across different runs

Custom Instructions

Provide your own custom instructions for specialized reasoning:

1custom_instructions = """
2Use the think and analyze tools for rigorous scientific reasoning:
3- Always think before making claims
4- Cite evidence in your analysis
5- Acknowledge uncertainty
6- Consider alternative hypotheses
7"""
8
9ReasoningTools(
10    instructions=custom_instructions,
11    add_instructions=False  # Don't include default instructions
12)

Custom Few-Shot Examples

You can also write your own examples tailored to your domain:

1medical_examples = """
2Example: Medical Diagnosis
3
4User: Patient has fever and cough for 3 days.
5
6Agent thinks:
7think(
8    title="Gather Symptoms",
9    thought="Need to collect all symptoms and their duration. Fever and cough suggest respiratory infection. Should check for other symptoms.",
10    action="Ask about additional symptoms",
11    confidence=0.9
12)
13"""
14
15ReasoningTools(
16    add_instructions=True,
17    add_few_shot=True,
18    few_shot_examples=medical_examples  # Your custom examples
19)

Monitoring Your Agent's Thinking

Use show_full_reasoning=True and stream_events=True to display reasoning steps in real-time. See Display Options in Reasoning Agents for details and Reasoning Reference for programmatic access to reasoning steps.

Reasoning Tools vs. Reasoning Agents

Both approaches add reasoning to any model, but they differ in control and automation:

Rule of thumb:

• Use Reasoning Tools when you want the agent to control its own reasoning process
• Use Reasoning Agents when you want guaranteed systematic thinking for every request