Building Tool Connectors

A tool is a REST endpoint your application exposes that Kernel Service agents can call. Tools let agents interact with your system — reading data, creating records, sending messages.

Overview

1. Define what your tool does (input/output schema)
2. Build an HTTP endpoint in your app
3. Register it with Kernel Service
4. Agents can now use it

Tool Endpoint Contract

Kernel calls your endpoint with these headers:

Header	Description
X-Tenant-ID	Which tenant the request is for
X-Kernel-Request-ID	Unique request ID for tracing
X-Idempotency-Key	For safe retries
Authorization	Bearer {service_token}

Example: “Get Lead” Tool

Schema:

{
  "name": "myapp.leads.get",
  "description": "Fetch a lead's details",
  "input_schema": {
    "type": "object",
    "properties": {
      "lead_id": {"type": "string", "description": "Lead ID to fetch"}
    },
    "required": ["lead_id"]
  }
}

Laravel Implementation:

routes/api.php

Route::prefix('kernel/v1/tools')
    ->middleware(['kernel.auth'])
    ->group(function () {
        Route::get('leads/{lead_id}', GetLeadTool::class);
    });

// app/Actions/KernelTools/GetLeadTool.php
class GetLeadTool
{
    public function __invoke(Request $request, int $lead_id): JsonResponse
    {
        $lead = Lead::with(['contact', 'company'])->findOrFail($lead_id);

        return response()->json([
            'lead_id' => $lead->id,
            'title' => $lead->title,
            'status' => $lead->status,
            'contact' => [
                'name' => $lead->contact?->name,
                'email' => $lead->contact?->email,
            ],
            'company' => [
                'name' => $lead->company?->name,
            ],
        ]);
    }
}

Execution Modes

Each tool has an execution mode:

Mode	Behaviour
immediate	Kernel executes the tool and continues
draft_only	Tool creates a draft (e.g. email) for human review
requires_approval	Kernel pauses and creates an approval request

Viewing Available Tool Schemas

Use the tools API to see exactly what schemas your tools need:

curl https://beta.kernelservice.com/api/v1/tools \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "X-API-Key: $API_KEY"

This returns every registered tool with full input/output schemas — use it as your implementation spec.