Tool & API Integration Patterns

An agent without tools is just a chatbot. Tools are what make agents actually useful — they can search the web, read files, send messages, deploy code, and interact with any API. This chapter covers how to wire it all up.

The Tool Landscape

MCP (Model Context Protocol) — The Future of Tool Integration

MCP is an open standard (created by Anthropic) that lets any AI agent connect to any tool server through a universal protocol. Think of it as USB for AI tools — plug in any MCP server and your agent can use it immediately.

# Install an MCP server (e.g., filesystem access)
npx @anthropic/create-mcp-server filesystem

# Or use community MCP servers:
npx mcp-server-github    # GitHub operations
npx mcp-server-slack     # Slack integration  
npx mcp-server-postgres  # Database access
npx mcp-server-brave     # Web search

# Configure in your agent's config:
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@anthropic/mcp-server-filesystem", "/path/to/workspace"]
    },
    "github": {
      "command": "npx", 
      "args": ["mcp-server-github"],
      "env": { "GITHUB_TOKEN": "ghp_xxxx" }
    }
  }
}

🔌 Tool Integration by Platform

import anthropic

client = anthropic.Anthropic()

# Define tools the agent can use
tools = [
    {
        "name": "search_web",
        "description": "Search the web for current information",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "Search query"}
            },
            "required": ["query"]
        }
    },
    {
        "name": "send_email",
        "description": "Send an email",
        "input_schema": {
            "type": "object",
            "properties": {
                "to": {"type": "string"},
                "subject": {"type": "string"},
                "body": {"type": "string"}
            },
            "required": ["to", "subject", "body"]
        }
    }
]

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "Search for AI news today"}]
)

# Handle tool calls in the response
for block in response.content:
    if block.type == "tool_use":
        # Execute the tool and return results
        result = execute_tool(block.name, block.input)
        # Continue conversation with tool result...

import openai

tools = [{
    "type": "function",
    "function": {
        "name": "get_stock_price",
        "description": "Get current stock price",
        "parameters": {
            "type": "object",
            "properties": {
                "symbol": {"type": "string", "description": "Stock ticker"}
            },
            "required": ["symbol"]
        }
    }
}]

response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What's AAPL at?"}],
    tools=tools,
    tool_choice="auto"
)

# Check if model wants to call a function
if response.choices[0].message.tool_calls:
    for call in response.choices[0].message.tool_calls:
        result = execute_function(call.function.name, 
                                  call.function.arguments)
        # Return result to continue conversation

from crewai_tools import BaseTool

class PriceLookupTool(BaseTool):
    name: str = "Price Lookup"
    description: str = "Look up current price for a product or service"
    
    def _run(self, query: str) -> str:
        # Your implementation here
        result = search_prices(query)
        return f"Found: {result}"

# Assign tools to agents
agent = Agent(
    role="Research Analyst",
    tools=[PriceLookupTool(), SearchTool(), WebScrapeTool()],
    llm="claude-sonnet-4-20250514"
)

Webhook Patterns

Webhooks are the universal glue. Any platform can send/receive webhooks, making them the easiest way to connect different systems:

# Incoming webhook: External service → Your agent
# Example: Stripe payment → trigger agent action
POST https://your-openclaw.com/webhook/stripe
{
  "event": "payment.completed",
  "amount": 29.00,
  "customer": "john@example.com"
}
# Agent receives this as a system event and acts on it

# Outgoing webhook: Your agent → External service  
# Example: Agent publishes content → notify Slack
POST https://hooks.slack.com/services/YOUR/WEBHOOK/URL
{
  "text": "📝 New content published: [Title]",
  "channel": "#content-updates"
}

The Tool Integration Hierarchy

Move through this hierarchy in order. Each level builds on the previous one. Don't give your agent action tools until it's proven reliable with information and memory tools first.

API Integration Patterns

When connecting your agent to external APIs, use these patterns:

Error Handling for API Tools

APIs fail. A lot. Your agent needs to handle: rate limits (back off and retry), auth failures (alert you, don't retry with bad creds), timeouts (retry once, then move on), and unexpected responses (log them and use fallback behavior). The agents that survive are the ones that fail gracefully, not the ones that never fail.