Tool Config

Tool Config controls how tools run — their timeout, retry behavior, output limits, and whether large results get stored as artifacts.

By default an agent can only call the tools you list in tools=[...]. If you rely on @tool-decorated callables being auto-discovered from anywhere in the process, opt in with ToolConfig(allow_global_tools=True).

from praisonaiagents import Agent, ExecutionConfig
from praisonaiagents.config.feature_configs import ToolConfig

agent = Agent(
    name="DataAgent",
    instructions="You analyze data using tools.",
    tools=[my_data_tool],
    tool_config=ToolConfig(
        timeout=60,
        enable_artifacts=True,
    ),
    execution=ExecutionConfig(parallel_tool_calls=True),
)

result = agent.start("Analyze the sales data and generate a report")
print(result)

ToolConfig.parallel is a deprecated alias for ExecutionConfig.parallel_tool_calls, the single source of truth for running batched LLM tool calls in parallel. Prefer execution=ExecutionConfig(parallel_tool_calls=True). ToolConfig(parallel=True) still works, but do not set both spellings to conflicting values — that raises TypeError.

The user asks the agent to use tools; ToolConfig controls timeouts, retries, parallel execution, and artifact storage for those calls.

Quick Start

Simple Usage

Use ToolConfig() defaults to get retry protection and safe output limits:

from praisonaiagents import Agent
from praisonaiagents.config.feature_configs import ToolConfig

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant with tools.",
    tools=[search_tool],
    tool_config=ToolConfig()
)

agent.start("Search for recent AI news")

With Custom Settings

Configure timeout and output limits on ToolConfig, and enable parallel tool calls with ExecutionConfig:

from praisonaiagents import Agent, ExecutionConfig
from praisonaiagents.config.feature_configs import ToolConfig

agent = Agent(
    instructions="You are a multi-source research agent.",
    tool_config=ToolConfig(
        timeout=60,
        output_limit=32000,
    ),
    execution=ExecutionConfig(parallel_tool_calls=True),
)
agent.start("Get weather, news, and stock data for San Francisco.")

With Artifact Storage

from praisonaiagents import Agent
from praisonaiagents.config.feature_configs import ToolConfig

agent = Agent(
    instructions="You are a data analysis agent.",
    tool_config=ToolConfig(
        enable_artifacts=True,
        artifact_retention_days=14,
        output_limit=32000,
    ),
)
agent.start("Analyze this large CSV file and summarize the findings.")

How It Works

Phase	What happens
1. Execute	Tool runs within the configured timeout
2. Retry	Failed executions retry with exponential backoff
3. Output	Large outputs spill to artifact storage
4. Respond	Agent uses tool output to form the final answer

Configuration Options

ToolConfig SDK Reference

Full parameter reference for ToolConfig

Precedence ladder:

# Level 1: Bool (enable with defaults)
agent = Agent(tool_config=True)

# Level 2: ToolConfig (full control)
agent = Agent(tool_config=ToolConfig(
    timeout=60,
    enable_artifacts=True,
))

Option	Type	Default	Description
`timeout`	`int \| None`	`None`	Per-tool timeout in seconds
`retry_policy`	`RetryPolicy \| None`	`None`	Retry with exponential backoff
`parallel`	`bool`	`False`	Deprecated alias for `ExecutionConfig.parallel_tool_calls`. Prefer `execution=ExecutionConfig(parallel_tool_calls=True)`. Setting both to conflicting values raises `TypeError`.
`output_limit`	`int`	`16000`	Max bytes before spilling to artifact store
`output_max_lines`	`int \| None`	`None`	Max lines before spilling
`output_direction`	`str`	`"both"`	Truncation direction: `"head"`, `"tail"`, or `"both"`
`enable_artifacts`	`bool`	`False`	Enable artifact storage for large outputs
`artifact_retention_days`	`int`	`7`	Days to keep artifacts before cleanup
`artifact_store`	`Any \| None`	`None`	Custom artifact store instance
`redact_secrets`	`bool`	`True`	Redact secrets from artifacts
`allow_global_tools`	`bool`	`False`	Allow resolving tool calls via the process-global `@tool` registry when a tool name is not in this agent’s declared `tools=[...]`. Off by default so an agent is scoped strictly to its own tools (safe by default); opt in for plugin-host style dynamic dispatch.

Legacy keyword arguments for tools now raise TypeError. Always use ToolConfig for tool configuration. See the migration guide if upgrading from an older version.

Common Patterns

Pattern 1 — Timeout for slow external APIs

from praisonaiagents import Agent
from praisonaiagents.config.feature_configs import ToolConfig

agent = Agent(
    name="DataAnalyzer",
    instructions="Analyze large datasets and return summaries.",
    tools=[run_sql_query],
    tool_config=ToolConfig(
        output_limit=32000,          # Larger inline limit
        enable_artifacts=True,       # Store huge outputs as files
        artifact_retention_days=14,  # Keep for 2 weeks
    )
)

agent.start("Run the monthly sales report query")

Parallel tool execution:

from praisonaiagents import Agent, ExecutionConfig
from praisonaiagents.config.feature_configs import ToolConfig

agent = Agent(
    name="ResearchAgent",
    instructions="Search multiple sources simultaneously.",
    tools=[search_news, search_arxiv, search_wikipedia],
    tool_config=ToolConfig(timeout=15),          # Fail fast if any tool is slow
    execution=ExecutionConfig(parallel_tool_calls=True),  # Run all three at once
)

agent.start("Research the current state of quantum computing")

Set parallel tool calls in one place. Setting ToolConfig(parallel=...) and ExecutionConfig(parallel_tool_calls=...) to conflicting values raises TypeError at Agent(...) construction:

# Raises TypeError: both name the same setting and they disagree.
Agent(
    tool_config=ToolConfig(parallel=False),
    execution=ExecutionConfig(parallel_tool_calls=True),
)

Tail-only output for log tools:

from praisonaiagents import Agent
from praisonaiagents.config.feature_configs import ToolConfig

agent = Agent(
    name="LogAnalyzer",
    instructions="Check system logs for errors.",
    tools=[get_system_logs],
    tool_config=ToolConfig(
        output_direction="tail",  # Keep the most recent log lines
        output_max_lines=500,
    )
)

agent.start("Check recent server error logs for anomalies.")

Plugin-host: allow global @tool discovery:

from praisonaiagents import Agent
from praisonaiagents.config.feature_configs import ToolConfig
from praisonaiagents.tools import tool

# @tool auto-registers into the process-global registry at import time.
@tool
def get_weather(city: str) -> str:
    """Return the current weather for the given city."""
    return f"Sunny in {city}"

# Opt in — this agent can now discover @tool-decorated callables
# even though it did not list them in tools=[...]
plugin_host = Agent(
    name="PluginHost",
    instructions="Use any registered tool the user asks for.",
    tool_config=ToolConfig(allow_global_tools=True),
)
plugin_host.start("What's the weather in Paris?")

Best Practices

Set a timeout for external tool calls

Any tool that calls an external API or runs a subprocess should have a timeout. Without one, a hung tool call blocks your agent indefinitely. Start with 30–60 seconds and adjust based on your tool’s expected latency.

Enable parallel for independent tools

Use execution=ExecutionConfig(parallel_tool_calls=True) when your agent commonly calls multiple tools at once and those tools don’t depend on each other’s outputs. This can cut wall-clock time significantly. ExecutionConfig.parallel_tool_calls is the single source of truth; ToolConfig(parallel=True) is a deprecated alias for it.

Enable artifacts for large data tools

If your tools return large datasets (SQL queries, file reads, API responses), set enable_artifacts=True. This prevents large outputs from filling the LLM context window, which wastes tokens and can cause errors.

Keep redact_secrets=True

Leave redact_secrets=True (the default) to prevent API keys, passwords, and tokens from being stored in artifact files or shown in tool outputs.

Keep allow_global_tools=False unless you are a plugin host

Any module in the process that imports an @tool-decorated function auto-registers it globally. With allow_global_tools=True, every such tool becomes callable by this agent whether you passed it or not — including unsafe ones from unrelated modules. Only opt in when your agent’s whole point is dynamic dispatch over the registry.

Artifact Storage

How artifacts are stored and retrieved

Async Tool Safety

Safe concurrent tool execution

Toolsets

Group and manage tools as sets

Tool Retry Policy

Configure retry behavior for failing tools

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

How It Works

Configuration Options

ToolConfig SDK Reference

Common Patterns

Pattern 1 — Timeout for slow external APIs

Best Practices

Artifact Storage

Async Tool Safety

Toolsets

Tool Retry Policy

​Quick Start

​How It Works

​Configuration Options

ToolConfig SDK Reference

​Common Patterns

​Pattern 1 — Timeout for slow external APIs

​Best Practices

​Related

Artifact Storage

Async Tool Safety

Toolsets

Tool Retry Policy

Quick Start

How It Works

Configuration Options

Common Patterns

Pattern 1 — Timeout for slow external APIs

Best Practices

Related