Custom Tools

Create server‑side API actions using a Postman‑style live editor—no SDK code required. Configure endpoints, headers/auth, and bodies with variables; test instantly in the UI, then call the action from chat with optional confirmation.

Where to find it

1. Open Dashboard → Settings (gear icon in chat).
2. Go to the Custom Tools tab.
3. Click Add New Tool or edit an existing one.

Custom Tools Configuration

Use this section to configure how your custom tool behaves. The editor mirrors a modern API client with live request preview, variable helpers, and a built‑in test panel. Each area below shows the editor first, followed by guidance, best practices, and an example you can replicate quickly.

Details

• Name: must be letters/numbers/underscores (e.g., send_email).

• Description: what the action does and what the output means.

• Confirmation:

  • Need confirmation: ask before executing this tool in chat.
  • Always call: call this tool on every AI response (each turn). Use with caution; may increase cost and side effects.

• Best practices

  • Use a short, action‑oriented name (e.g., create_invoice, get_weather).
  • Describe both intent and output (what is returned and how it’s used in chat).
  • Set Need confirmation for any side‑effecting or billable action.
  • Recommended use cases for Always call: logging, telemetry, guardrails, post‑processing.

• Example

  • Name: send_email
  • Description: “Send an email via external API and return the message ID.”
  • Confirmation: Need confirmation

Endpoint

• Method and URL. Typing a ?key=value query auto‑parses into the Params table; editing the table updates the URL.

• Method colors help readability (GET, POST, etc.).

• Tips

  • Keep base paths stable; prefer query params over path sprawl for optional filters.
  • Use dry_run when the API supports it to safely validate payloads.
  • Prefer idempotent methods (GET/PUT) where possible; use POST for create-only operations and include a client idempotency key if supported.

• Example

  • GET example: GET https://api.example.com/weather?city={{city}}
  • POST example: POST https://api.example.com/send?dry_run={{dry_run}}

Headers

• Add key/value pairs. Values can include variables like {{api_token}}.

• Common: Authorization, Content-Type, custom vendor headers.

• Best practices

  • Set Content-Type to match Body mode (application/json, multipart/form-data, etc.).
  • Avoid putting secrets directly in headers; use variables that resolve server‑side.
  • The editor auto-aligns Content-Type with Body mode, but you can override it if your provider requires a non‑standard value.

• Example

  • Content-Type: application/json
  • Authorization: Bearer {{api_token}}

Authorization

• Types: Bearer, Basic, API Key, or custom header.

• Value and header key (when applicable) are stored in the tool (server‑side usage, no client leak).

• Tips

  • Prefer Bearer/API Key when available; use Basic only if required.
  • For Custom, specify headerKey (e.g., X-API-KEY) to match provider expectations.

• Examples

  • Bearer: Authorization: Bearer {{api_token}}
  • Basic: base64 of username:password (store securely)
  • API Key: X-API-KEY: {{api_key}}

Body

• Content types:

  • application/x-www-form-urlencoded, multipart/form-data: edited as key/value; sent as form-encoded or multipart payloads (not JSON).
  • application/json, text/plain: edited as raw text.

• Best practices

  • For complex payloads, prefer raw JSON and document field semantics.
  • Keep form‑data for file uploads or mixed field/file payloads.

• Common pitfalls

  • Mismatched Content-Type: ensure it matches the editor mode; the Headers tab shows the effective value.
  • JSON formatting: ensure valid JSON (double quotes, no trailing commas). Use a formatter if needed.

• Example (JSON)

  json

  { "to": "{{recipient}}", "subject": "{{subject}}", "text": "{{message}}" }

Variables

• Variables are system/env-like key–values available to the AI and tools at runtime.

• Use them to pass context (e.g., current user, workspace, org) without asking the user every time.

• Examples: korin_user_email (readonly), workspace_id (readonly), default_timezone.

• Readonly variables are injected by the system and excluded from testing inputs.

• Tips

  • Keep secrets and sensitive context in variables marked readonly.
  • Prefer descriptive names; document purpose in the description field.
  • Precedence: when placeholders overlap, Parameters resolve first, then Variables (see Parameters → Using Parameters in headers/body).

• Data types

  • string: free-form text, IDs, emails, ISO timestamps.
  • number: integers or floats (e.g., prices, quantities). Avoid thousand separators.
  • boolean: true / false (lowercase).
  • enum: restricted set of allowed strings (e.g., status in [pending, paid, failed]).
  • object (by convention): complex context objects you reference via dot paths (see Nested object placeholders below). Objects are not entered directly in URL params; they are typically used in JSON body templates.

• Example (variables used in a JSON body)

{
  "user": {
    "email": "{{korin_user_email}}",
    "timezone": "{{default_timezone}}"
  },
  "metadata": {
    "workspace": "{{workspace_id}}"
  }
}

• Nested object placeholders (dot paths)
  • You can reference nested data using dot notation: {{profile.address.city}}.
  • During execution, the system resolves the path against the variables map; unresolved paths are surfaced in test errors.
  • Use dot paths primarily in JSON bodies or header values; avoid in URL when values may require encoding.
  • Example:

{
  "ship_to": {
    "city": "{{customer.address.city}}",
    "country": "{{customer.address.country}}"
  }
}

Parameters

• Parameters are URL query parameters and declared inputs used to resolve {{placeholders}} in URL, headers, and body.

• Each parameter has name, type, description, and flags: nullable, optional enum.

• Parameters drive the Test panel (required ones must have test values).

  • When a required parameter is missing at test time, the editor highlights the field and explains what to fix.

• URL behavior

  • The Params table is the source of truth for URL query params. Editing Params updates the URL; typing ?key=value in URL auto-parses back into Params.
  • Values are URL-encoded automatically when the request is sent.
  • Empty or nullable params are omitted from the final URL.
  • Arrays: repeat the same key (e.g., tag=red&tag=blue) or use tag[]=red&tag[]=blue depending on your API’s convention.
  • Booleans are serialized as true / false strings.

• Array example

  • Params table: tag: red, tag: blue
  • Resolved URL (repeat key): ...&tag=red&tag=blue
  • Alternative (bracket style, if your API expects it): ...&tag[]=red&tag[]=blue

• Common pitfalls

  • Enum mismatch: provide one of the allowed values; define enum options to guide inputs.
  • Accidental empty params: mark as nullable or remove them; empty values are omitted.

• Examples

  • URL: https://api.example.com/search?query={{q}}&page={{page}}&tag={{tag}}
  • Params table:
    • q: "laptop"
    • page: 2
    • tag: "ultrabook"
  • Resolved URL at test-time:
    • https://api.example.com/search?query=laptop&page=2&tag=ultrabook

• Using Parameters in headers/body

  • Placeholders in headers/body (e.g., Authorization: Bearer {{api_token}}) resolve from Parameters first, then Variables.
  • Prefer Parameters for request-specific inputs; use Variables for ambient context and secrets.

• Tips

  • Capture enums for finite sets (status, type) to guide inputs and validation.
  • Keep required parameters minimal; prefer sensible defaults for optional ones.

Visibility & Access

• Public: accessible by anyone in Korin (all users).

• Private: add an allowlist of emails. When you switch to private, your email is auto‑added (you can manage the list).

• Best practices

  • Start Private and allowlist collaborators; switch to Public when stable.
  • Keep sensitive tools Private and review access regularly.
  • Before switching to Public, ensure logging/auditing is enabled and confirmation is set if the tool has side effects.

• Example

  • Private tool with allowlist: you@example.com, teammate@example.com

Custom Tool Example

Goals

• Demonstrate configuring a write-action (Send Email) with auth and variables.
• Show a live test, including request preview and response.

Preparation

• API endpoint and method (e.g., POST https://api.example.com/send).
• Authentication choice and credential (e.g., Bearer token).
• Required variables/parameters and their types (e.g., recipient, subject, message).
• Request body shape and content type.

Configuration

• Details: name, description, confirmation behavior.
• Endpoint: method + URL; add query params as needed.
• Headers/Auth: content type and auth header.
• Body: raw JSON or key/value pairs.
• Variables: declare inputs and mark nullable/readonly/enums.
• Test: provide test values and run.

Expectation

• Request preview shows the final method, URL (with params resolved), headers, and body using your test values.
• The test panel returns the HTTP status and response payload (JSON/text) for quick validation.
• Secrets handling and safety:
  • Headers, Authorization, and Body values that you configure are stored encrypted on the backend.
  • It is safe to place secrets (e.g., API tokens) in Authorization or header fields; they are never exposed to other users and are transmitted server‑to‑server when actions run.
  • In UI previews, sensitive values may be masked depending on the auth type; real values are only used during execution.
• Failure case preview: if required Parameters/Variables are missing or invalid, the Test panel highlights fields and surfaces clear error messages.

Troubleshooting

• 4xx/5xx responses: double‑check endpoint, auth, payload shape.
• Missing variables message: fill all required test values; mark optional ones as nullable.
• Body mismatch: ensure Content-Type matches the editor mode (KV vs raw).
• Access denied in chat: confirm visibility and allowlist for private tools.
• 401/403 Unauthorized/Forbidden: verify Authorization scheme (Bearer/Basic/API Key), header key for Custom, and valid credentials.
• 404 Not Found: confirm base URL, path segments, and whether the API expects a trailing slash.
• 415 Unsupported Media Type: the server rejects body type; set Content-Type to match raw JSON vs form modes.
• 429 Rate limited: back off and retry; consider adding a dry_run or test window outside peak load.
• 5xx Server errors: retry later; validate payload against provider docs and reduce body size/complexity.
• JSON errors: malformed JSON in Body; use the JSON body mode and format payload before testing.
• Multipart/form issues: ensure each field key matches provider spec; file uploads must use multipart/form-data.
• Enum validation: provide one of the allowed values; define enum options in Variables to guide inputs.
• Readonly parameters: system‑injected values (e.g., korin_user_email) don’t require test input and cannot be overridden.
• Timeouts: large payloads or slow endpoints may time out; reduce data or test with dry_run first.
• TLS/SSL: ensure https:// is used when the API requires TLS.

Related Topics

• Built-in Tools
• Feeding Knowledge
• Agent Orchestration
• Prompt Templates