Agent and Tool Decorator

Use Agent with the tool() decorator when you want llm-async to handle the tool-call loop for you. The agent sends your tools to the provider, executes requested tool calls, appends tool results to the conversation, and keeps calling the model until it returns a final response or reaches max_iter.

import asyncio
import os

from llm_async import Agent, OpenAIProvider, tool


@tool
def calculator(operation: str, a: float, b: float) -> float:
    """Perform basic arithmetic operations."""
    if operation == "add":
        return a + b
    if operation == "subtract":
        return a - b
    if operation == "multiply":
        return a * b
    if operation == "divide":
        return a / b
    raise ValueError(f"Unsupported operation: {operation}")


async def main() -> None:
    agent = Agent(
        provider=OpenAIProvider(api_key=os.getenv("OPENAI_API_KEY")),
        model="gpt-4o-mini",
        tools=[calculator],
    )

    response = await agent.acomplete(
        messages=[
            {
                "role": "user",
                "content": "What is 15 + 27? Use the calculator.",
            }
        ]
    )
    print(response.main_response.content)


asyncio.run(main())

Decorated Tools

The tool() decorator wraps a regular Python function and attaches a generated Tool definition to function.tool.

The generated schema uses the function name as the tool name, the function docstring as the tool description, and supported type annotations for parameters:

from llm_async import tool


@tool
def word_count(text: str) -> int:
    """Count the number of words in a text string."""
    return len(text.split())


assert word_count.tool.name == "word_count"
assert word_count.tool.parameters["properties"]["text"] == {"type": "string"}

Supported parameter annotations include str, int, float, bool, list, list[T], dict, and optional unions such as str | None. Parameters without supported annotations are omitted from the generated schema. Parameters with defaults, and optional parameters, are not marked as required.

Agent Options

Agent accepts these options:

Option	Description
provider	Provider instance used for acomplete and tool execution.
model	Model name passed to the provider on every completion request.
tools	List of functions decorated with tool().
parallel_tools	Execute multiple tool calls concurrently when True. Defaults to True.
max_iter	Maximum model/tool-call iterations before returning the last response. Defaults to 10.

Additional keyword arguments passed to acomplete() are forwarded to the provider, so provider-specific options such as temperature or tool_choice can still be used.

See examples/agent_tool_decorator.py for a multi-provider example.