Tools

Tools give agents the ability to act -- search the web, browse pages, query APIs, and connect to external services. Tools are managed separately from agents and attached by their integer IDs.

How Tools Work

The tool workflow has four steps:

Browse Catalog  →  Add Tool  →  Configure  →  Attach to Agent

1. Browse the catalog to see what tools are available
2. Add a tool from the catalog to your account
3. Configure it with any required credentials or settings
4. Attach it to one or more agents by passing its integer ID

Tool Catalog

The catalog lists all tools available on the platform. Each entry has a name, type, title, description, and categories.

Python

from flymyai import AgentClient

client = AgentClient(api_key="fly-***")

catalog = client.tools.available()

for tool in catalog:
    print(f"{tool.name} ({tool.type})")
    print(f"  {tool.title}: {tool.description}")
    print(f"  Categories: {tool.categories}")

JavaScript

import { AgentClient } from "flymyai-js-client";

const client = new AgentClient({ apiKey: "fly-***" });

const catalog = await client.tools.available();

catalog.forEach(tool => {
    console.log(`${tool.name} (${tool.type})`);
    console.log(`  ${tool.title}: ${tool.description}`);
    console.log(`  Categories: ${tool.categories}`);
});

AvailableTool Fields

Field	Type	Description
name	string	Identifier used when creating the tool (e.g. "tavily")
type	string	Tool type
title	string	Human-readable display name
description	string	What the tool does
categories	list	Groupings for browsing (e.g. search, browser, data)

Adding a Tool

Create a tool instance from the catalog using its name (passed as mcp_tool). This returns a Tool object with an integer .id.

Python

tool = client.tools.create(mcp_tool="tavily")

print(f"Tool ID: {tool.id}")            # integer ID
print(f"MCP Tool: {tool.mcp_tool}")     # "tavily"
print(f"Configured: {tool.is_configured}")

JavaScript

const tool = await client.tools.create({ mcpTool: "tavily" });

console.log(`Tool ID: ${tool.id}`);
console.log(`MCP Tool: ${tool.mcp_tool}`);
console.log(`Configured: ${tool.isConfigured}`);

Tool Fields

Field	Type	Description
id	int	Unique identifier used when attaching to agents
mcp_tool	string	The catalog tool name
is_configured	bool	Whether all required configuration has been provided
next_configuration_step	dict or None	Describes the next required configuration input, if any

Configuring a Tool

Some tools require configuration (API keys, credentials, or other settings). When is_configured is false, inspect next_configuration_step and provide the required values.

Python

tool = client.tools.create(mcp_tool="tavily")

# Check what configuration is needed
if not tool.is_configured:
    print(f"Next step: {tool.next_configuration_step}")

    # Provide the required configuration
    tool = client.tools.provide_config(
        tool.id,
        user_response={"TAVILY_API_KEY": "tvly-***"}
    )

    print(f"Now configured: {tool.is_configured}")

JavaScript

let tool = await client.tools.create({ mcpTool: "tavily" });

if (!tool.isConfigured) {
    console.log("Next step:", tool.nextConfigurationStep);

    tool = await client.tools.provideConfig(tool.id, {
        userResponse: { TAVILY_API_KEY: "tvly-***" }
    });

    console.log(`Now configured: ${tool.isConfigured}`);
}

Multi-step configuration

Some tools may require multiple configuration steps. After each call to provide_config, check is_configured and next_configuration_step again. Repeat until is_configured is true.

Attaching Tools to Agents

Pass tool IDs as a list of integers when creating or updating an agent:

Python

# Create tools
tavily = client.tools.create(mcp_tool="tavily")
tavily = client.tools.provide_config(tavily.id, user_response={"TAVILY_API_KEY": "tvly-***"})

browser = client.tools.create(mcp_tool="browser")

# Create agent with tools attached
agent = client.agents.create(
    name="Research Assistant",
    goal="Research the given topic and produce a detailed summary with sources.",
    tools=[tavily.id, browser.id]
)

# Or update an existing agent's tools
client.agents.update(
    agent_id=agent.id,
    tools=[tavily.id, browser.id]
)

JavaScript

// Create tools
let tavily = await client.tools.create({ mcpTool: "tavily" });
tavily = await client.tools.provideConfig(tavily.id, {
    userResponse: { TAVILY_API_KEY: "tvly-***" }
});

const browser = await client.tools.create({ mcpTool: "browser" });

// Create agent with tools attached
const agent = await client.agents.create({
    name: "Research Assistant",
    goal: "Research the given topic and produce a detailed summary with sources.",
    tools: [tavily.id, browser.id]
});

Calling Tools Directly

You can invoke a tool directly without an agent, which is useful for testing or one-off operations:

Python

result = client.tools.call(
    tool.id,
    action="search",
    arguments={"query": "latest AI research papers"}
)

print(result)

JavaScript

const result = await client.tools.call(tool.id, {
    action: "search",
    arguments: { query: "latest AI research papers" }
});

console.log(result);

Complete Example

End-to-end flow: browse catalog, add tools, configure, create agent, run it.

from flymyai import AgentClient

client = AgentClient(api_key="fly-***")

# 1. Browse the catalog
catalog = client.tools.available()
for t in catalog:
    print(f"  {t.name}: {t.description}")

# 2. Add tools
tavily = client.tools.create(mcp_tool="tavily")
browser = client.tools.create(mcp_tool="browser")

# 3. Configure tools that need it
tavily = client.tools.provide_config(
    tavily.id,
    user_response={"TAVILY_API_KEY": "tvly-***"}
)

# 4. Create an agent with tools attached
agent = client.agents.create(
    name="Market Researcher",
    goal="Research current market trends and produce a structured analysis.",
    tools=[tavily.id, browser.id],
    status="active"
)

# 5. Run the agent
run = client.runs.create(agent_id=agent.id)
result = client.runs.wait(run.id, timeout=300)

print(f"Status: {result.status}")
print(f"Output: {result.output}")

Next Steps

• Agents -- create agents and attach tools
• Runs -- execute agents and monitor progress