Tools

Tools

LightAgent tools are ordinary Python callables with a tool_info attribute. The framework converts that metadata into an OpenAI-compatible function schema and dispatches the callable when the model selects it.

Basic Tool

from LightAgent import LightAgent

def get_weather(city_name: str) -> str:
    return f"{city_name} is sunny."

get_weather.tool_info = {
    "tool_name": "get_weather",
    "tool_description": "Get current weather information for a city.",
    "tool_params": [
        {
            "name": "city_name",
            "description": "The city name to query",
            "type": "string",
            "required": True,
        }
    ],
}

agent = LightAgent(
    model="gpt-4.1",
    api_key="your_api_key",
    base_url="https://api.openai.com/v1",
    tools=[get_weather],
)

print(agent.run("What is the weather in Shanghai?"))

Constructor Tools

Pass stable tools when creating the agent:

agent = LightAgent(
    model="gpt-4.1",
    api_key="your_api_key",
    base_url="https://api.openai.com/v1",
    tools=[get_weather],
)

Runtime Tools

Pass tools only for a specific run:

result = agent.run(
    "Use the calculator for 42 * 19.",
    tools=[calculator],
)

Runtime tools are registered before the model request and can be called during that run.

Tool Metadata

tool_info should include:

• tool_name: stable Python identifier, for example get_weather.
• tool_description: short model-facing description.
• tool_params: list of parameter definitions.

Supported parameter metadata follows a JSON-schema-like shape:

{
    "name": "city_name",
    "description": "The city name to query",
    "type": "string",
    "required": True,
}

Common types: string, integer, number, boolean, array, and object.

Named Tool Loading

ToolLoader can load a string-named tool from a tools directory. The tool file and function name must match the tool name:

tools/get_weather.py

def get_weather(city_name: str) -> str:
    return f"{city_name} is sunny."

get_weather.tool_info = {...}

Then pass the name:

agent = LightAgent(
    model="gpt-4.1",
    api_key="your_api_key",
    base_url="https://api.openai.com/v1",
    tools=["get_weather"],
)

Tool names are validated as Python identifiers to avoid path traversal.

Built-in Tools

LightAgent registers several built-in tools:

• execute_python_code
• execute_python_file
• execute_python_code_stream
• upload_file_to_oss

These are powerful tools. In production, review whether they should be exposed to every agent, especially when user input can influence code, files, network calls, or uploads.

Dynamic Tool Generation

agent.create_tool(user_input, tools_directory="tools") can ask the model to generate a tool file. Treat generated tools as code review candidates:

• keep generated tools outside automatic production paths until reviewed
• reject unsafe file names
• inspect imports and side effects
• add tests before relying on generated tools

Troubleshooting

• If the model never calls a tool, make the tool_description more specific.
• If a required argument is missing, check the tool_params list.
• If you see [LA-TOOL], inspect the callable, parameter names, and exceptions raised inside the tool.
• If local string tools do not load, confirm the file path, function name, and tool_info match.