Tool Config

Configure tool execution timeouts, retries, parallel execution, and artifact storage

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

python

from praisonaiagents import Agent, ExecutionConfig, 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)

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

Diagram

Quick Start

Simple Usage

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

python

from praisonaiagents import Agent, 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:

python

from praisonaiagents import Agent, ExecutionConfig, 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

python

from praisonaiagents import Agent, 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

Diagram

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:

python

# 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`. The flag currently takes effect on the async (`achat()` / `astart()`) tool loop only; the sync (`chat()` / `start()`) loop still runs batched calls sequentially (#6202).
`output_limit`	`int`	`16000`	Max bytes before spilling to artifact store
`output_max_lines`	`int \	None`	`None`	Max lines kept from a tool’s output. `None` disables the line cap.
`output_direction`	`str`	`"both"`	`head` keeps the first lines/chars, `tail` keeps the last, `both` keeps both ends with a `...[N lines total, showing M]...` marker between them. Steers both the line cap and the `output_limit` char cap.
`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.

Common Patterns

Pattern 1 — Timeout for slow external APIs

python

from praisonaiagents import Agent, 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:

python

from praisonaiagents import Agent, ExecutionConfig, 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")

Warning

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

python

# 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:

Since PraisonAI PR #6060, output_max_lines and output_direction are applied — earlier releases accepted them but ignored them. The line cap runs first, then the output_limit char cap; both keep the end(s) chosen by output_direction.

Diagram

python

from praisonaiagents import Agent
from praisonaiagents.config 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.")

Show only the head of a verbose tool:

python

from praisonaiagents import Agent
from praisonaiagents.config import ToolConfig

agent = Agent(
    name="Lister",
    instructions="Summarise the directory listing.",
    tools=[list_files],
    tool_config=ToolConfig(
        output_direction="head",  # Keep the first lines
        output_max_lines=50,
    )
)

With output_direction="both" (the default), output_max_lines=4 on a 200-line output keeps line 0, line 1, a ...[200 lines total, showing 4]... marker, then line 198, line 199. Leaving output_max_lines=None keeps output unchanged.

Plugin-host: allow global @tool discovery:

python

from praisonaiagents import Agent, 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. Tools writing to the same file fall back to sequential — see the write-conflict guard.

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

Tool Config

Quick Start

How It Works

Configuration Options

Common Patterns

Pattern 1 — Timeout for slow external APIs

Best Practices

Related