Adding Custom Integrations

Datafuse makes Adding Custom Integrations incredibly easy and efficient. It allows developers to import any HTTP API, Swagger/OpenAPI specification, or custom API configuration and compile it instantly into a schema-safe, runtime-ready integration that AI models can execute.

The Custom Integrations Pipeline

When you paste an API definition or write a custom integration config, Datafuse runs it through a multi-stage validation and compiler pipeline to generate tools:

• Ingestion: Supports both raw YAML configurations and fully qualified OpenAPI v3 specifications.
• Normalization: Standardizes authentication schemes (Bearer, OAuth2, API Key) and HTTP parameters into flat query/body JSON schemas.
• Compilation: Creates functional tool definitions, ensuring is_mutating rules match (POST, PUT, DELETE are mutating, while GET is read-only).

Defining Custom Integrations in YAML

To convert any standard third-party REST API into agent tools, you define the integration mappings.

Here is an example definition for adding a custom integration for Ably Realtime (ably.yaml), representing the actions and schemas directly in Datafuse:

key: ably
title: Ably Realtime
description: Build real-time messaging, collaboration, and pub/sub solutions.
category: Communication
runtime_type: rest

auth_schemes:
  - key: api_key
    type: api_key
    placement:
      location: header
      name: Authorization
      prefix: "Basic "
    credential_fields:
      - name: api_key
        label: Ably API Key
        required: true
        is_secret: true

metadata:
  base_url_template: https://rest.ably.io/
  ping_endpoint: /time

actions:
  - slug: publish_message
    name: Publish Message
    description: Publish a real-time message to a specific pub/sub channel.
    endpoint: /channels/{channel_id}/messages
    method: POST
    is_mutating: true
    input_schema:
      type: object
      properties:
        path:
          type: object
          required:
            - channel_id
          properties:
            channel_id:
              type: string
              description: The Ably channel ID.
        body:
          type: object
          required:
            - name
            - data
          properties:
            name:
              type: string
              description: The event name.
            data:
              type: string
              description: The message payload.

Action Parsing Mechanics

During compilation, Datafuse processes custom integrations to guarantee safe agent runtime invocation:

Path Parameter Interpolation

If your endpoint template contains path variables (e.g. /channels/{channel_id}/messages), Datafuse parses the path argument key from the agent payload and dynamically rewrites the URL at runtime.

Mutation Isolation

AI models must know if an action causes side-effects. Datafuse sets the is_mutating flag true for any HTTP methods other than GET. This allows you to restrict writing actions behind human-in-the-loop approvals at the SDK level.

Using the Developer Console to Add Integrations

To register custom integrations manually:

1. Navigate to the Connectors section inside the Datafuse web console.
2. Select Add Custom Integration and choose between writing custom YAML configurations or pasting an OpenAPI JSON/YAML spec.
3. Click Compile & Register. The compiler will validate the schemas and publish the integration to your provider registry.
4. Select Discover Tools to verify all compiled actions are correctly mapped.

!NOTE Once compiled, the custom integrations immediately become available to your TypeScript or Python SDK loops, allowing your AI agent to call them with zero redeployment.