Custom Tools Integration

Define custom OpenAPI JSON schemas so Verabase AI agents can query internal APIs or trigger transaction actions mid-chat.

What it does

Custom Tools expose internal or third-party API capabilities directly to your AI agents. Using standard OpenAPI JSON schema definitions, you define tools (e.g., "Check Order Status", "Reset Password") that the agent can choose to execute during its reasoning loop to fetch real-time database details or commit database actions.

Data Flow & Callback Trigger

Tool execution flows dynamically during user conversation cycles:

Data Read: User inputs are parsed. If a tool call is decided, Verabase sends an HTTP POST request containing JSON arguments to your configured endpoint.
Data Written: Returns JSON-formatted data from your server back to the agent reasoning cycle to generate responses.
Sync Frequency: Real-time. API execution callbacks fire synchronously during conversation loops.

Scope & Limits

Authentication: Supports Bearer tokens, Basic Auth credentials, and custom header definitions.
Call Limits: External server response times must stay under 10 seconds. Request payloads are strictly verified against your JSON schema models. Refer to the OpenAI Function Calling Guide for details on schema formatting.

Setup guide

Estimated setup time: ~8 minutes. Authentication type: Bearer Token, API Key, or Basic Auth. Target API endpoint must be publicly accessible via HTTPS.

Navigate to Agent settings

Go to AI Agents → Select Agent → Tools inside your dashboard. Click Add Custom Tool.

Define Tool properties

Input a detailed tool name and describe its functionality clearly (the LLM uses this description to decide when to call the tool). Enter the target parameter properties in the JSON Schema editor window.

Configure Endpoint & Authentication

Enter the HTTPS target callback URL. Input the authentication headers (e.g. Authorization: Bearer YOUR_TOKEN) to secure target endpoints.

Test and save

Click Test Tool. Input mock parameters to verify request success. If validation checks pass, click Save Tool to deploy it live.

Where it shows up

Agent Workspace: Available tools list inside the Agent settings dashboard.
Inbox Execution: Displays active execution badges inside the Live Inbox thread when an agent triggers tool calls.

Troubleshooting & Common Issues

Timeout Error: If your server takes more than 10 seconds to respond, Verabase aborts the request. Optimize database calls on your server to keep latency under 1 second.
Validation Failures: Ensure your server returns JSON matching the parameter schema exactly. Mismatches will cause the agent to output fallback error responses.

Frequently asked questions

What language can custom tools be written in?

Custom tools are standard HTTP endpoints, so you can build them using any programming language (Python, Node.js, Go, etc.) that can receive JSON and return responses.

How does Verabase authenticate custom tool requests?

Verabase sends a signature header or secret token with every request, allowing your API server to verify that the call originated from Verabase.

What is the maximum timeout for custom tool execution?

To maintain responsive customer conversations, custom tool requests must return a response within 10 seconds.

Related integrations

Ready to deploy custom tools?

Join the waitlist for early access to the self-healing knowledge platform.

Get early access to Custom Tools