DOCSEARCHbyAlgolia
Submit Docs

superglue AI Agent Platform

repository·main·Indexed 24 days ago

https://github.com/superglue-ai/superglue

An AI agent platform designed to automate the connection, migration, and implementation of enterprise systems including ERPs, CRMs, and databases. It supports a wide range of connection types (REST, GraphQL, SOAP, file-based, and database) and provides TypeScript and Python SDKs for API interaction. The platform includes a Superglue Agent Plugin for integration building workflows such as API/schema discovery, connector mapping review, and auth boundary checks.

Tokens
47.8K
Snippets
70
Records
265
Agent score
84%

What's inside superglue

  1. Overview of superglue capabilities

    main

    superglue uses AI agents to connect, migrate, and implement enterprise systems. It is designed to automate tasks that typically require human engineering and coordination, such as:

    • System Implementation: Mapping and migrating legacy data, configuring systems (e.g., NetSuite, SAP), and maintaining data sync post-go-live.
    • AI Platform Integration: Connecting ERP, CRM, and databases to AI platforms like Claude with governed data access.
    • End-to-end Integrations: Managing the entire implementation process, including importing historical data and connecting customer systems.

  2. Use the Superglue Agent Plugin in an Agent Harness

    main

    The Superglue Agent Plugin is designed for SKILL.md-compatible harnesses like Codex, Claude Code, Claude Cowork, and Copilot-style coworkers.

    It provides agents with a precise operating procedure, expected outputs, and plugin evaluations. It does not add a runtime dependency to Superglue itself, making it a lightweight addition for agentic workflows focused on integration building.

  3. Accessing step results in dataSelectors and outputTransforms

    main

    Every step result is wrapped in an envelope. You must account for this when accessing data. Accessing sourceData.stepId.results will fail because it hits the envelope rather than the API response.

    • Object selector (or none): Access via sourceData.stepId.data
    • Array selector: Access via sourceData.stepId.map(i => i.data)
    • Paginated step: Access via sourceData.stepId.data (pages are merged server-side into a single envelope; do not use .map() on it).

  5. How call_system resolves placeholders

    main

    The call_system function uses the systemId parameter to perform automatic resolution of placeholders in the tool's configuration:

    1. Credentials: Resolves <<systemId_credKey>> placeholders in URLs, headers, and bodies. These must exactly match the keys stored in system.credentials.
    2. URLs: Resolves <<systemId_url>> placeholders using the system's url field.
    3. OAuth: Automatically refreshes OAuth tokens before the request is made.
    4. Routing: Routes the request to the correct protocol strategy (e.g., HTTP, Postgres, MSSQL, Redis, FTP/SFTP, SMB).

    Important: Nothing is injected automatically. Placeholders must be explicitly placed in the step config.

  6. Configure execution mode using dataSelectors

    main

    A dataSelector is a JS function that determines if a step runs in Single Execution mode or Loop Execution mode.

    Single Execution (Returns an OBJECT)

    The step runs once. The returned object becomes currentItem.

    (sourceData) => ({ userId: sourceData.userId })

    Loop Execution (Returns an ARRAY)

    The step runs once for every element in the array. Each element becomes currentItem.

    (sourceData) => sourceData.getContacts.data.filter(c => c.active)

    Accessing currentItem in Step Config

    Once a selector is defined, access the item in your config using:

    • <<currentItem>>: The whole value.
    • <<(sourceData) => sourceData.currentItem.id>>: A specific property.
    • <<(sourceData) => sourceData.currentItem.name.toUpperCase()>>: A transformed property.
    (sourceData) => ({ userId: sourceData.userId })
(sourceData) => sourceData.getContacts.data.filter(c => c.active)

  7. Ensure Demo Data Quality and Plausibility

    main

    A demo is only considered successful if the delivered payload contains meaningful, non-empty domain data.

    Requirements:

    • Avoid Echoes: Never treat a bare httpbin /anything/... echo response as valid demo data.
    • Domain Specificity: Ensure the payload contains concrete records relevant to the chosen theme (e.g., contacts for CRM, tickets for support, orders for ERP).
    • Transformation: If the initial retrieval from the simulated upstream system returns empty or placeholder content, apply a deterministic transform or request shaping step to ensure the final payload is meaningful.
    • Validation: Validate output quality before the final user response. If the payload is empty or implausible, rebuild/fix and run the tool again.

  8. Understand the tool editing confirmation flow

    main

    The edit_tool process involves a multi-step confirmation flow to prevent accidental changes:

    1. Generation: You call edit_tool with a patches array, a toolId (or draftId in the playground), and a payload.
    2. Validation: edit_tool validates and applies the patches, returning diffs and confirmation defaults.
    3. User Review: The user sees a diff UI displaying all proposed changes.
    4. Decision: The user can confirm all, partially approve (accepting some and rejecting others), or decline all.
    5. Application: If partially approved, only the approved diffs are applied to the original configuration.
    6. Result: You receive the final confirmation result.

    Save Behavior

    • Main Agent: Edits usually auto-save. Always use the returned persistence, toolId, draftId, and saveError fields to track success rather than assuming the save worked.
    • Tool Playground Agent:
      • The default confirm action is save.
      • The alternate Accept action keeps changes draft-only.
      • Use draftId: "playground-draft" for follow-up edits or runs in the playground.

  9. How to use Systems and credentials in tool configurations

    main

    Systems are reusable building blocks for superglue tools that store configuration and credentials.

    Credential Namespacing

    Credentials are not injected automatically. They must be explicitly referenced in the tool's step configuration using the format <<systemId_credentialKey>>.

    Example: If a system has id="stripe" and a stored credential api_key, it is available as <<stripe_api_key>>.

    • For HTTP tools: Place the placeholder in the headers.
    • For databases/Redis/file servers: Place the placeholder in the connection URL.

    System URLs

    Instead of hardcoding base URLs, use the <<systemId_url>> placeholder. This allows tools to work across different environments (e.g., dev vs. prod) without modification.

    Example: System id="salesforce" with url="https://mycompany.salesforce.com" is available as <<salesforce_url>>. Step config: { "url": "<<salesforce_url>>/services/data/v58.0/sobjects/Account" }

    OAuth Tokens

    OAuth tokens (access_token, refresh_token) are automatically refreshed before each step execution. However, access_token must still be explicitly referenced in step headers to authenticate requests.

  10. Manage Base Roles (admin, member, enduser)

    main

    Every user has exactly one base role. These roles define the starting permissions for an organization.

    RoleDescriptionPermissions
    adminImmutable. Bypasses all RBAC checks.Full access to everything.
    memberDefault for team members. Cannot be deleted or renamed.Starts with tools: "ALL" and systems: "ALL". Can be narrowed.
    enduserDefault for portal consumers. Cannot be deleted or renamed.Starts with tools: [] and systems: {} (no access). Must be explicitly granted access.

    Auto-append behavior: When a user creates a new tool or system, it is automatically added to the creator's base role if that role is in SPECIFIC mode (not "ALL"):

    • New tool $\rightarrow$ appended to tools list.
    • New system $\rightarrow$ appended to systems map with read-write access.

  11. Understand Superglue Access Rules (RBAC)

    main

    Superglue uses Role-Based Access Control (RBAC) to define tool-level and system-level allowlists.

    Important Constraints:

    • RBAC is only available on enterprise organizations.
    • In non-enterprise (personal) organizations, RBAC is not used; all users have admin access.
    • Users can have one base role and multiple custom roles.
    • Permission resolution follows union semantics (the most permissive role wins).

  12. Understand HTTP request behavior and error detection

    main

    Request Behavior

    • Body Handling: GET, HEAD, DELETE, and OPTIONS methods always have their bodies stripped. POST, PUT, and PATCH parse bodies starting with { as JSON.
    • Defaults: Includes Accept: */* and a Chrome-like User-Agent. HTTPS accepts self-signed certs (rejectUnauthorized: false).
    • Parsing: Responses are read as arraybuffer and auto-parsed (JSON, CSV, XML, etc.).

    Error Detection

    • HTTP Status Errors: Non-2xx responses throw an error containing the method, URL, a 1000-char response body preview, masked config, and retry count.
    • Smart Error Detection: Even with 2xx status codes, the system scans for error indicators like response.code or response.status being in the 400-599 range, or keys like error, errors, error_message, failure_reason, failure, or failed (up to depth 2) having non-empty values.
    • Bypassing: Set failureBehavior: "continue" in Advanced Settings to skip error checking.