Skip to main content

Tools

Tools are what an agent can call to act: search the web, run code, query a database or post to Slack.

Tools come from three sources: the Marketplace, with 1,000+ models, tools and integrations callable with one API key; integrations you connect with your own account; and custom tools you write in Python.

Which tool do I need​

NeedTool page
Answer from live web resultsWeb search
Run your own Python functionPython sandbox
Post in Slack, send Gmail, update Salesforce or HubSpotIntegrations
Call the actions of an MCP serverRemote MCP
Remember facts across sessionsSessions and memory
Save outputs as downloadable filesFile manager
Find models, tools and integrationsMarketplace search
Answer from your documentsKnowledge base
Give an agent files to readFiles
Query a SQLite or PostgreSQL databaseDatabases
Use a Marketplace model as a toolModels

Marketplace tools​

Marketplace tools are hosted and ready to run: you get them by path, with no connect step.

Find a tool​

Search the Marketplace by keyword, then get the tool by its asset path. Each result carries its path.

from aixplain import Aixplain

aix = Aixplain(api_key="YOUR_API_KEY")

page = aix.Tool.search(query="web", page_size=5)
print([tool.name for tool in page.results])

web_search = aix.Tool.get("tavily/tavily-web-search/tavily")
print(web_search.name, web_search.list_actions())
Show output

Attach a tool to an agent​

Pass tools in tools. The agent decides when to call each one, and result.data.steps shows which ones ran.

agent = aix.Agent(
    name="Research agent",
    description="Researches topics on the web.",
    instructions="Use web search for anything time-sensitive. Cite your sources.",
    tools=[web_search],
).save()

result = agent.run("What is the latest stable Python release? One sentence.")
print([step["unit"]["name"] for step in result.data.steps])
print(result.data.output)
Show output

An agent sees each tool's name, description and input descriptions. Clear names and descriptions help it pick the right tool.

Scope a tool​

Set allowed_actions before you create the agent, so the agent sees only the actions it needs. Fewer actions mean fewer parameters in its context and no calls to actions you have not reviewed.

web_search.allowed_actions = ["search"]
web_search.actions["search"].inputs.num_results = 3
print(web_search.actions["search"].inputs.keys())
Show output

Setting an input under .actions[...].inputs fixes its value for every call. allowed_actions also applies when you run the tool directly.

Integrations​

An integration is an app you connect, through OAuth or with a token or API key, to create a tool. The tool then acts in that app with your account.

slack = aix.Tool(
    name="Slack",
    description="Posts messages to Slack channels.",
    integration="composio/slack/composio",
).save()
print("Open this link to connect Slack:", slack.redirect_url)
Show output

Open the link and approve, and the tool is ready for any agent. Some integrations need no sign-in, such as Shared memory. For tokens, API keys and the most used apps, see Integrations.

Custom tools​

A custom tool runs your own Python function in the Python sandbox. Write the function so an agent can call it correctly:

  • Put imports inside the function, so the function runs on its own.
  • Add type hints. They become the tool's input types.
  • Add a docstring that says what the function does and returns.
import inspect

def convert_currency(amount: float, rate: float):
    """Convert an amount with an exchange rate. Returns the converted amount rounded to cents."""
    from decimal import Decimal, ROUND_HALF_UP
    converted = Decimal(str(amount)) * Decimal(str(rate))
    return {"converted": float(converted.quantize(Decimal("0.01"), rounding=ROUND_HALF_UP))}

converter = aix.Tool(
    name="Currency converter",
    description="Converts an amount of money with a given exchange rate.",
    code=inspect.getsource(convert_currency),
).save()

agent.tools.append(converter)
agent.save()

result = agent.run("Use the currency converter: 250 USD to EUR at a rate of 0.9237.")
print([step["unit"]["name"] for step in result.data.steps])
print(result.data.output)
Show output

The SDK names the tool's action after the function. If the code defines more than one function, pass config={"code": ..., "function_name": "..."} instead of code=.

Update a custom tool​

Set the new code in config, with function_name, and save. The tool keeps its ID, so agents that use it pick up the change.

def convert_currency(amount: float, rate: float):
    """Convert an amount with an exchange rate. Returns the amount rounded to whole units."""
    return {"converted": round(amount * rate)}

converter.config = {"code": inspect.getsource(convert_currency), "function_name": "convert_currency"}
converter.save()

result = converter.run(data={"amount": 250, "rate": 0.9237})
print(result.data)
Show output

Every aix.Tool parameter and method is in the API reference: tool.

Clean up​

agent.delete()
slack.delete()
converter.delete()

Next steps​