How to Use NucleusIQ Standard Mode With Tools (Practical Guide)

TL;DR

Standard mode is the best default for most production agent workflows.
Create tools using BaseTool.from_function() with clear names and descriptions.
Use execute_stream() for real-time token and tool visibility.
Add ToolCallLimitPlugin, ModelCallLimitPlugin, and ToolRetryPlugin for reliability.
GitHub: NucleusIQ

Why Standard Mode Is the Default for Tool Workflows

In NucleusIQ, Standard mode is designed for multi-step tasks where the agent needs to call tools, reason over outputs, and continue until completion.

Use Standard mode when you need:

tool-assisted responses,
iterative task completion,
better reliability than a single-pass response,
balanced cost and quality.

For many production assistants, Standard mode is the right baseline.

Step 1: Create Tools With `BaseTool.from_function`

NucleusIQ lets you convert regular Python functions into tools.

from nucleusiq.tools import BaseTool

def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

def multiply(a: int, b: int) -> int:
    """Multiply two numbers."""
    return a * b

add_tool = BaseTool.from_function(add, name="add", description="Add two numbers")
multiply_tool = BaseTool.from_function(
    multiply,
    name="multiply",
    description="Multiply two numbers",
)

Tool descriptions matter. Clear names and descriptions help the model choose the right tool reliably.

Step 2: Build a Standard Mode Agent With Tools

import asyncio
from nucleusiq.agents import Agent
from nucleusiq.agents.config import AgentConfig, ExecutionMode
from nucleusiq_openai import BaseOpenAI

agent = Agent(
    name="math_assistant",
    role="Tool-enabled assistant",
    objective="Solve calculations with tool support",
    llm=BaseOpenAI(model_name="gpt-4o-mini"),
    tools=[add_tool, multiply_tool],
    config=AgentConfig(execution_mode=ExecutionMode.STANDARD),
)

async def main():
    await agent.initialize()
    result = await agent.execute(
        {"id": "std1", "objective": "Calculate (12 + 8) * 3 using tools."}
    )
    print(result)

asyncio.run(main())

In this setup, the agent can decide when to call add and multiply, then synthesize the final answer.

Step 3: Add Streaming for Tool Visibility

Use execute_stream() to expose tokens and tool activity in real time.

import asyncio
from nucleusiq.streaming.events import StreamEventType

async def run_stream():
    await agent.initialize()
    task = {"id": "std2", "objective": "Find 25 * 4 and explain each step."}

    async for event in agent.execute_stream(task):
        if event.type == StreamEventType.TOKEN:
            print(event.token, end="", flush=True)
        elif event.type == StreamEventType.TOOL_CALL_START:
            print(f"\n[Tool start: {event.tool_name}]")
        elif event.type == StreamEventType.TOOL_CALL_END:
            print(f"[Tool end: {event.tool_name}]")
        elif event.type == StreamEventType.COMPLETE:
            print(f"\n\nFinal: {event.content}")

asyncio.run(run_stream())

This is useful for chat UI, observability dashboards, and debugging tool behavior.

Step 4: Add Safety Limits for Production

Standard mode should include guardrails:

from nucleusiq.plugins.builtin import ModelCallLimitPlugin, ToolCallLimitPlugin, ToolRetryPlugin

agent = Agent(
    name="safe_tool_agent",
    llm=BaseOpenAI(model_name="gpt-4o-mini"),
    tools=[add_tool, multiply_tool],
    config=AgentConfig(execution_mode=ExecutionMode.STANDARD),
    plugins=[
        ToolCallLimitPlugin(max_calls=10),
        ModelCallLimitPlugin(max_calls=12),
        ToolRetryPlugin(max_retries=2, base_delay=0.5, max_delay=5.0),
    ],
)

This reduces runaway loops, controls cost, and improves resilience against transient tool errors.

Tool Design Best Practices in NucleusIQ

Keep tools focused and deterministic.
Use clear schemas via typed parameters.
Return compact, parseable outputs.
Avoid mixing unrelated responsibilities inside one tool.
Add retries only where failures are transient.

Think of tools as stable system APIs, not ad hoc helper functions.

Common Tooling Anti-Patterns

1) Vague Tool Names

Names like do_task create confusion and increase wrong tool calls.

2) Overloaded Tools

One mega-tool handling everything reduces reliability and traceability.

3) Missing Limits

No call limits can lead to expensive loops.

4) No Fallback Path

If a tool fails, define retry or recovery behavior.

How the Standard Mode Tool Loop Works

In NucleusIQ Standard mode, the agent is expected to reason, call tools, observe outputs, and continue until it can produce a useful answer. This loop is the reason Standard mode is more reliable than a simple one-pass approach for practical tasks.

A typical cycle looks like:

Build context from prompt + memory.
Call model with available tool specs.
Receive either text output or tool calls.
Execute tool calls through the framework executor.
Feed tool results back into conversation context.
Repeat until completion condition is met.

Because NucleusIQ makes this process explicit, teams can log, test, and tune each stage.

Fully Annotated Standard Mode Example

The following code shows a production-oriented setup with code comments.

import asyncio
from nucleusiq.agents import Agent
from nucleusiq.agents.config import AgentConfig, ExecutionMode
from nucleusiq.plugins.builtin import (
    ModelCallLimitPlugin,
    ToolCallLimitPlugin,
    ToolRetryPlugin,
)
from nucleusiq.tools import BaseTool
from nucleusiq_openai import BaseOpenAI

def add(a: int, b: int) -> int:
    # Keep tools focused and deterministic.
    return a + b

def multiply(a: int, b: int) -> int:
    # Clear type hints improve tool schema quality.
    return a * b

add_tool = BaseTool.from_function(add, name="add", description="Add two integers")
multiply_tool = BaseTool.from_function(
    multiply,
    name="multiply",
    description="Multiply two integers",
)

agent = Agent(
    name="std_math_agent",
    role="Math assistant with governed tools",
    objective="Solve multi-step calculations with transparent tool usage",
    llm=BaseOpenAI(model_name="gpt-4o-mini"),
    tools=[add_tool, multiply_tool],
    config=AgentConfig(
        execution_mode=ExecutionMode.STANDARD,
        # Optional: adjust tool-call limit at config level when needed.
        max_tool_calls=20,
    ),
    plugins=[
        ToolCallLimitPlugin(max_calls=12),  # Prevent infinite tool loops.
        ModelCallLimitPlugin(max_calls=15),  # Control model call budget.
        ToolRetryPlugin(max_retries=2, base_delay=0.5, max_delay=5.0),  # Handle transient tool failures.
    ],
)

async def main():
    await agent.initialize()
    task = {"id": "std-101", "objective": "Solve (18 + 7) * 4 and explain your steps."}
    result = await agent.execute(task)
    print(result)

asyncio.run(main())

Streaming + Tool Event Trace (What You Should See)

For debugging and UI visibility, stream events while Standard mode runs.

import asyncio
from nucleusiq.streaming.events import StreamEventType

async def run_with_trace(agent):
    await agent.initialize()
    task = {"id": "std-stream-1", "objective": "Calculate 42 * 3 and show concise explanation."}

    async for event in agent.execute_stream(task):
        if event.type == StreamEventType.TOKEN:
            print(event.token, end="", flush=True)
        elif event.type == StreamEventType.TOOL_CALL_START:
            # Useful for frontend progress UI and logs.
            print(f"\n[tool:start] {event.tool_name} args={event.tool_args}")
        elif event.type == StreamEventType.TOOL_CALL_END:
            print(f"[tool:end] {event.tool_name} result={event.tool_result}")
        elif event.type == StreamEventType.COMPLETE:
            print("\n[complete]")

# asyncio.run(run_with_trace(agent))

Example trace excerpt:

[tool:start] multiply args={"a": 42, "b": 3}
[tool:end] multiply result=126
The result is 126.
[complete]

These traces are valuable for QA because they show exactly which tools were used and in what order.

Real-World Tool Pattern: Retrieval + Computation

Many production tasks combine lookup and transformation. For example:

retrieve policy information,
compute thresholds,
format final answer with clear structure.

A lightweight approach is to create separate tools:

search_docs(query) for retrieval,
calculate_metric(x, y) for deterministic computation,
format_report(data) for final formatting.

This decomposition improves observability and allows selective plugin controls (for example, retries on retrieval tools only).

Expected Results and Acceptance Criteria

When validating a Standard-mode tool workflow, define objective checks:

Functional checks

Correct final numeric or factual output
Correct use of at least one expected tool
No forbidden tool usage

Reliability checks

Tool failures recover within retry budget
Call limits are respected
Agent returns meaningful fallback when tools fail

User-quality checks

Response format is readable
Explanation is concise and accurate
Turnaround is within SLA

Sample acceptance result record:

Task ID: std-101
Final answer: PASS
Tool usage: PASS (add -> multiply)
Retry behavior: PASS (0 retries needed)
Latency SLA: PASS (2.1s under 3.0s target)

Standard Mode Debugging Playbook

Problem: Wrong tool selected

Improve tool names and descriptions.
Narrow tool list for that endpoint.
Add ToolGuardPlugin allowlist if needed.

Problem: Too many tool calls

Lower max_tool_calls.
Add ToolCallLimitPlugin.
Tighten prompt instruction to avoid unnecessary loops.

Problem: Tool output parsing issues

Return structured formats (JSON-like strings or strict text patterns).
Keep tool return schema consistent.

Problem: Latency too high

Reduce available tool count.
Use smaller model for non-critical steps.
Route easy requests to Direct mode before Standard mode.

Operational Metrics for Tool Workflows

Track these metrics at minimum:

tool-call count distribution per task
retry rate by tool name
tool failure rate by endpoint
latency impact by tool combination
answer correction rate after tool-assisted replies

Standard mode becomes predictable when tool behavior is measured continuously.

Production Hardening Checklist for Tooling Endpoints

Before shipping Standard mode to production, verify these technical controls:

Tool schema quality
- every tool has explicit typed inputs and focused responsibility,
- every tool has deterministic output shape.
Policy and limits
- ToolCallLimitPlugin and ModelCallLimitPlugin configured per endpoint,
- risky tools restricted through allowlist/blocklist controls.
Resilience behavior
- transient failure simulation validates retry logic,
- final error message remains user-friendly after retry exhaustion.
Traceability
- tool start/end events are logged in staging and production,
- task ID and tool chain can be reconstructed for incident analysis.
Performance gates
- p95 latency target met under expected traffic,
- cost per successful task stays within budget.

This checklist reduces hidden failure modes that usually appear after launch, not before.

Where Standard Mode Fits in Your Mode Strategy

A practical policy:

Direct for simple low-risk requests,
Standard for most production workflows,
Autonomous for high-stakes, high-complexity tasks.

If you are unsure, start with Standard mode, measure outcomes, and route up/down as needed.

Final Takeaway

NucleusIQ Standard mode with tools is the practical center of production agent design. It gives you multi-step capability without the full cost of autonomous orchestration.

Start with clear tools, add streaming and limits, and then layer plugins and memory as your workflows evolve.

Footnotes:

Additional Reading

OK, that’s it, we are done now. If you have any questions or suggestions, please feel free to comment. I’ll come up with more topics on Machine Learning and Data Engineering soon. Please also comment and subscribe if you like my work, any suggestions are welcome and appreciated.

Post Views: 9