Skip to main content

​
Tools

Tools are callable functions that agents can invoke. Each tool belongs to an adapter and defines parameters using JSON Schema.

​
Tool Types

Bedrock supports two types of tools:
TypeDescriptionUse Case
InternalRuns in-process via a handler functionBuilt-in functionality, database operations
ExternalCalls an HTTP webhook URLCustom APIs, third-party integrations

​
How Tool Calls Work

When an agent decides to use a tool:
  1. LLM generates a tool call with arguments
  2. Bedrock validates arguments against the tool’s JSON Schema
  3. Tool executes:
    • Internal: Calls the handler function directly
    • External: POSTs to the webhook URL
  4. Result returns to the agent as text

​
Internal Tools

Internal tools run Python functions in the Bedrock backend. They’re used for built-in adapters like Contacts, SMS, Email, Projects, and others. Example internal tool definition: 
{
  "name": "create_contact",
  "description": "Create a new contact in your contact book",
  "handler": "defaults.contacts.handlers.create_contact",
  "parameters": {
    "type": "object",
    "properties": {
      "name": { "type": "string", "description": "Contact's full name" },
      "phone": { "type": "string", "description": "Phone in E.164 format" },
      "email": { "type": "string", "description": "Email address" }
    },
    "required": ["name"]
  }
}
The handler is a dotted path to a Python function: module.path.function_name

​
Handler Function Signature

Internal handlers receive: 
def create_contact(args: dict, agent: Agent, tool: Tool) -> str:
    """
    Args:
        args: The arguments from the LLM (validated against parameters schema)
        agent: The Agent instance calling the tool
        tool: The Tool instance being called

    Returns:
        String result shown to the agent
    """
    contact = Contact.objects.create(
        agent=agent,
        name=args["name"],
        phone=args.get("phone", ""),
    )
    return f"Created contact: {contact.name} (ID: {contact.id})"

​
External Tools (Webhooks)

External tools make HTTP POST requests to your API when called by an agent. This is how you integrate custom functionality. When an agent calls an external tool, Bedrock POSTs to your url with:
  • Headers: X-Agent-Secret (your product’s tool call secret) and X-Agent-Identity (agent UUID)
  • Body: The tool definition, agent/product context, and the LLM-generated arguments
Your endpoint returns JSON, which becomes the tool result the agent sees.

Custom Adapters Guide

For a full walkthrough of creating adapters, registering tools, handling webhook requests, verifying secrets, and best practices — see the Custom Adapters guide.

​
Tool Parameters (JSON Schema)

Tool parameters use JSON Schema. Common patterns:

​
Required String Parameter

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "The message to send"
    }
  },
  "required": ["message"]
}

​
Optional Parameters with Defaults

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "description": "Max results (default 50)",
      "default": 50
    }
  }
}

​
Enum Values

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": ["pending", "in_progress", "completed"],
      "description": "Task status"
    }
  }
}

​
Nested Objects

{
  "type": "object",
  "properties": {
    "address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" },
        "zip": { "type": "string" }
      },
      "required": ["street", "city"]
    }
  }
}

​
Automatic Reasoning

Bedrock automatically adds a reasoning parameter to all tools: 
{
  "reasoning": {
    "type": "string",
    "description": "The reasoning for the tool call."
  }
}
This helps with tracing and debugging - you can see why the agent decided to call each tool.

​
Detail URL (Dynamic Descriptions)

Tools can have a detail_url that’s fetched at runtime to augment the description with dynamic content: 
{
  "name": "check_schedule",
  "description": "Check availability on the calendar",
  "detail_url": "https://api.yourcompany.com/calendar/tool-detail",
  "url": "https://api.yourcompany.com/calendar/check"
}
The detail URL should return: 
{
  "detail": "Available slots this week: Monday 2pm, Wednesday 10am, Friday 3pm"
}
This detail is appended to the tool description, giving the agent real-time context.

​
Listing Tools

View all tools for an adapter: 
curl -X GET "https://api.bedrock.orinlabs.org/api/toolbox/tools/?adapter=ADAPTER_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Best Practices

Clear Descriptions

Write detailed descriptions - they’re included in the LLM prompt.

Verify Secrets

Always verify X-Agent-Secret in webhook handlers.

Return Useful Data

Return structured, actionable information the agent can use.

Handle Errors Gracefully

Return error messages the agent can understand and act on.