Skip to content
Docs

Documentation navigation

System Tools

Understand built-in web search, code execution, and reasoning tools.

#System Tools Guide

Some capabilities are useful to almost every agent: searching the web, running a quick calculation, and thinking through a hard problem. mAIvn exposes these as built-in system tools when the runtime and your invocation policy allow them.

This guide explains what each system tool does, how the runtime keeps private data safe while they run, and how to control which ones are available.

#Overview

System tools are runtime-provided tools that extend agent capabilities:

ToolDescription
web_searchSearch the web for current information
replExecute Python code in a sandbox
thinkRoute to optimal LLM for complex reasoning
reevaluateInsert a planning checkpoint before continuing execution

These tools are not defined in your SDK code - they're made available by the runtime when appropriate.

#Built-in Capabilities

#Datetime Awareness

The mAIvn runtime has built-in datetime awareness. Agents automatically know the current date and time without needing a custom tool. You do not need to create a get_current_time() tool - the system handles this natively.

Python 
# No need for this - the system already knows the time:
# @agent.toolify()
# def get_current_time() -> dict: ...

# Just ask directly
response = agent.invoke([
    HumanMessage(content='What day of the week is it?')
])

This applies to:

  • Current date and time
  • Timezone information
  • Date calculations and comparisons

#Configuring Timezone

By default, the SDK auto-detects your system's timezone. You can explicitly configure the timezone using the Client:

Python 
from maivn import Agent, Client

# Explicit timezone configuration
client = Client(
    api_key='your-api-key',
    client_timezone='America/New_York',  # IANA timezone identifier
)

agent = Agent(name='scheduler', client=client)
#Timezone Parameters
ParameterTypeDefaultDescription
client_timezonestr | NoneNoneIANA timezone (e.g., 'America/New_York', 'Europe/London')
auto_detect_timezoneboolTrueAuto-detect system timezone when client_timezone is not set
#When to Configure Timezone
  • Server applications: Set explicit timezone for consistent behavior across deployments
  • User-facing apps: Set timezone based on user preferences
  • Scheduled tasks: Ensure time-sensitive operations use the correct timezone
Python 
# Disable auto-detection, use UTC
client = Client(
    api_key='your-api-key',
    client_timezone='UTC',
    auto_detect_timezone=False,
)

# User-specific timezone
client = Client(
    api_key='your-api-key',
    client_timezone=user_preferences.timezone,
)

The agent will use this timezone context when answering time-related questions or performing date calculations.

#Private Data Protection

System-tool calls pass through the runtime's model-input shield: known private values are replaced with placeholders before model-bound prompts are sent, and the request fails closed if a known value remains. This is a defense in depth control, not proof that an arbitrary user string contains no sensitive data.

System-tool availability follows runtime defaults and the environment's policy. Set allowed_tools=[] to disable them for a call or pass an explicit allowlist. Raw private values are not available to system tools by default. allow_private_data=True is an explicit opt-in for supported flows; use it only after reviewing the destination and the exact tool contract.

#Web Search Privacy

web_search sends its final query to the configured search provider. Known private values are shielded from the model that prepares the call, but you should still treat the query as external disclosure: write prompts that use public terms, inspect representative events in your environment, and never put a secret directly in the search request.

Python 
from maivn import SystemToolsConfig

response = agent.invoke(
    [HumanMessage(content='Search the public web for account-security guidance.')],
    system_tools_config=SystemToolsConfig(allowed_tools=['web_search']),
)

#REPL Code Execution Privacy

repl generates Python and runs it in the configured sandbox. The generated code, standard output, and standard error return as tool output. Do not pass private values to it unless the environment supports that flow and you have explicitly enabled it. Keep secrets in your own local tools when a calculation does not need them.

#Think Tool Privacy

think makes a separate model call. Its prompt is protected by the same known-value shield as other model-bound content. Keep allow_private_data off unless a supported workflow truly requires raw values; metadata and placeholders are usually enough.

#Purpose

Search the web for current information, news, or facts.

#How It Works

  1. The agent determines it needs current information
  2. The runtime performs the web search
  3. Search results are returned to the agent
  4. Agent incorporates results into its response

#Example Use Case

Python 
agent = Agent(
    name='research_agent',
    system_prompt='''You are a research assistant.
    When asked about current events or recent information,
    use web search to find accurate data.''',
    api_key='...',
)

response = agent.invoke([
    HumanMessage(content='What are the latest developments in AI?')
])

The runtime can select web_search when it is available and the request calls for current information. A prompt alone does not guarantee a search.

#REPL (Code Execution)

#Purpose

Execute Python code in a secure sandbox.

#How It Works

  1. Agent generates Python code to solve a problem
  2. The runtime executes code in an isolated sandbox
  3. Execution results (stdout, errors) are returned
  4. Agent interprets results and continues

#Example Use Case

Python 
agent = Agent(
    name='data_analyst',
    system_prompt='''You are a data analyst.
    When you need to perform calculations or data analysis,
    write Python code and execute it using the REPL.''',
    api_key='...',
)

response = agent.invoke([
    HumanMessage(content='Calculate the compound interest on $10,000 at 5% for 10 years')
])

The agent might generate and execute:

Python 
principal = 10000
rate = 0.05
years = 10
result = principal * (1 + rate) ** years
print(f"Final amount: ${result:.2f}")

#Safety

  • Code runs in an isolated sandbox
  • No access to host system
  • Time and resource limits applied
  • Output is captured and returned

#Think

#Purpose

Route higher-level analysis tasks to the optimal LLM.

#How It Works

  1. Agent encounters a complex reasoning task
  2. The runtime routes to the best model for the task type
  3. Reasoning is performed with appropriate capabilities
  4. Results are returned to the agent

#When It's Used

  • Interpreting verification results, logs, traces, or conflicting tool outputs
  • Evaluating code, architecture, or trade-offs after evidence has been gathered
  • Complex mathematical reasoning or multi-step logical deduction
  • Tasks requiring extended context or specialized capabilities

Do not use think for direct lookup, simple arithmetic, trivial summaries, or as a substitute for a dedicated function tool. When think receives prior tool results, its output should preserve failed checks, nonzero return codes, tool errors, and unverified assumptions instead of summarizing them as success.

#System Prompt Guidance

Guide the agent to use system tools appropriately:

#For Research Tasks

Python 
agent = Agent(
    name='researcher',
    system_prompt='''You are a research assistant.

    For current information or recent events:
    - Use web search to find up-to-date data
    - Verify information from multiple sources

    For calculations or data analysis:
    - Write and execute Python code
    - Show your work and explain results''',
    api_key='...',
)

#For Analysis Tasks

Python 
agent = Agent(
    name='analyst',
    system_prompt='''You are a data analyst.

    When analyzing data:
    - Use Python code execution for calculations
    - Visualize results when helpful
    - Explain your methodology

    If you discover your initial approach won't work:
    - Adjust your analysis plan accordingly''',
    api_key='...',
)

#Controlling System Tools

You can guide when system tools should (or shouldn't) be used:

Python 
agent = Agent(
    name='calculator',
    system_prompt='''You are a simple calculator.
    Only use basic arithmetic - do NOT use web search or code execution.
    Provide quick mental math answers.''',
    api_key='...',
)

When you need hard runtime boundaries, pass invocation system-tool config:

Python 
from maivn import SystemToolsConfig

response = agent.invoke(
    [HumanMessage(content='Research and calculate the result')],
    system_tools_config=SystemToolsConfig(
        allowed_tools=['web_search', 'repl'],
    ),
)

#Interaction with Your Tools

System tools work alongside your custom tools:

Python 
@agent.toolify(description='Get product catalog')
def get_products() -> dict:
    return {'products': [...]}

@agent.toolify(final_tool=True)
class MarketReport(BaseModel):
    products: list[str]
    market_trends: str  # May come from web_search
    price_analysis: str  # May come from repl calculations

The agent can:

  1. Call get_products (your tool)
  2. Use web_search for market trends
  3. Use repl for price calculations
  4. Combine all into MarketReport

#Event Tracing

See system tool usage with the event builder:

Python 
response = agent.events().invoke(
    [HumanMessage(content='Research AI trends and analyze market data')],
)

Output might show:

Plain text 
[SYSTEM] Using web_search for: AI trends 2024
[SYSTEM] Executing Python code in sandbox
[TOOL] Calling get_products
[FINAL] Generating MarketReport

#Privacy Controls and Auditing

#Audit Trail

System-tool lifecycle events show which tool ran and whether it completed. Do not treat an event alone as proof that a query or result contained no sensitive data; test the configured provider and policy boundary with representative non-secret fixtures.

#Final Privacy Boundary

Known registered private values are shielded from model-bound system-tool prompts, and raw private_data is withheld unless you explicitly authorize a supported flow. This boundary does not classify every arbitrary string a user might enter. web_search sends its final query to an external provider, so keep sensitive content out of that query and verify the configured boundary with non-secret fixtures. Runtime events identify system-tool activity without providing a way to retrieve resolved private values.

#Configuration

System tools are still provisioned by the runtime, but developers can influence use at the SDK layer:

  • Deployment administrators control availability, quotas, and deployment policy
  • Invocation system_tools_config.allowed_tools can narrow which system tools may run for a session

Contact your administrator for:

  • Enabling/disabling specific system tools
  • Rate limits and quotas

#Best Practices

#1. Design for Privacy

Python 
agent = Agent(
    name='secure_analyst',
    system_prompt='''Use web search for public information.
    Use REPL only for calculations that do not need customer data.''',
    api_key='...'
)

# Private data configuration
agent.private_data = {
    'customer_id': '12345',
    'api_key': 'sk-xxx-secret'
}

#2. Keep Secrets Out of Results

Python 
@agent.toolify()
@depends_on_private_data(data_key='secret_key', arg_name='key')
def process_data(data: dict, key: str) -> dict:
    result = external_api_call(data, key)
    return {
        'processed': True,
        'result': remove_sensitive_fields(result),
    }

#3. Combine Privacy Capabilities

Python 
# System tools work together while maintaining privacy
@agent.toolify(description='Get user profile')
def get_user_profile(user_id: str) -> dict:
    return {'user_id': user_id, 'preferences': [...]}

# Agent can:
# 1. Get profile (your tool)
# 2. Use web_search for public info about preferences
# 3. Use repl for analysis calculations
# 4. Tool results are minimized before returning

#4. Verify the Boundary

Use non-secret canary values to verify the configured provider, event, and output paths. Assert that canaries do not appear in captured model requests, search queries, tool results, or user-facing events. Do not use production secrets as test values.

#Next steps