​
What are Agent Tools?

Tools in xpander.ai are operations provided by interfaces (LinkedIn, Reddit, Weather, etc.) that allow agents to interact with external systems and data sources. Tools enable your agent to interact with the real world - accessing databases, calling APIs, controlling external services, and even delegating to other agents.

​
Basic Tool Usage

function-call.py
# Get LLM response
response = self.model.chat.completions.create(
                model="gpt-4.1",
                messages=self.agent_backend.messages,
                temperature=0.0,
                tools=self.agent_backend.get_tools(),
                tool_choice=self.agent_backend.tool_choice
            )
self.agent_backend.add_messages(response.model_dump())

tool_calls = XpanderClient.extract_tool_calls(llm_response=response.model_dump())
tool_results = self.agent_backend.run_tools(tool_calls=tool_calls)

for tool in tool_results:
    print(f"Tool: {tool.function_name} - Status: {tool.result}")
)

If you want to control how your agent uses these tools in a hierarchical structure, check out the Agent Graph System guide.

​
Visual Tool Management

The Agent Builder provides a visual interface for managing tools:

  1. Create an agent in the Builder at https://app.xpander.ai
  2. Use the canvas to add tools visually
  3. Configure tools with a user-friendly interface
  4. Test tools directly in the platform

Message Management

Replace your conversation memory with xpander’s system:

  • Thread-based chats
  • Cross-session memory
  • Structured storage

Tool Execution

Replace your tool system with xpander’s:

  • LLM provider conversion
  • Built-in tools
  • Consistent patterns

Event Handling

Replace your event handling with xpander’s:

  • Multi-channel support
  • Structured events
  • Agent communication

​
Exploring Available Interfaces

xpander.ai provides a rich library of pre-built interfaces that your agents can leverage without any development work. These interfaces span across various domains and services to help your agents accomplish a wide range of tasks.

​
Adding Tools to Your Agent

You can add tools to your agents using the visual UI, the CLI, or programmatically with the SDK.

xpander.ai’s visual interface makes adding tools intuitive without writing code:

1

Access the Interfaces Panel

Navigate to your agent and click the “Interfaces” button in the top-right corner

2

Browse Available Tools

Explore interfaces like LinkedIn, Reddit, and more

3

Select Operations

Choose the specific operations you want to add to your agent

4

Configure Settings

Adjust any operation-specific settings if needed

5

Add to Agent

Click “Add” to attach the operations to your agent

​
Defining and Using Local Tools

Local tools require manual implementation by defining both their schema and function:

local_tools.py
def read_file(file_path: str) -> Dict[str, Any]:
    # Your implementation here
    return {"success": True, "content": "File content here"}

# Then define the tool declarations (schema for the LLM)
local_tools = [
    {
        "declaration": {
            "type": "function",
            "function": {
                "name": "read_file",
                "description": "Read a file from the sandbox",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "file_path": {
                            "type": "string",
                            "description": "Path to the file to read"
                        }
                    },
                    "required": ["file_path"]
                }
            }
        },
        "fn": read_file
    }
]

# Create convenient lookup structures
local_tools_list = [tool['declaration'] for tool in local_tools]
local_tools_by_name = {tool['declaration']['function']['name']: tool['fn'] for tool in local_tools}

# Register local tools with your agent
client = XpanderClient(api_key=os.getenv("XPANDER_API_KEY"))
agent = client.agents.get(agent_id=os.getenv("XPANDER_AGENT_ID"))

agent.add_local_tools(local_tools_list)

​
Using Local Tools in Your Agent

When using local tools, you need to execute them manually when the LLM calls them:

my-agent.py
response = openai_client.chat.completions.create(
    model="gpt-4o",
    messages=agent.messages,
    tools=agent.get_tools(),
    temperature=0
)

# Extract all tool calls
all_calls = XpanderClient.extract_tool_calls(
    response.model_dump()
)
    
# Process local tools manually
local_tool_calls = XpanderClient.retrieve_pending_local_tool_calls(all_calls)
    
## execute local tool calls
## Manually call the functions 
##

## add local tool call results to agent memory
self.agent.memory.add_tool_call_results(
    tool_call_results=local_tool_call_results,
)

​
Best Practices

​
Troubleshooting Tool Access

When working with tools, you might encounter various issues that prevent your agent from accessing or properly using them. Here are common problems and their solutions: