Connections

BindAI Connections provide a consistent interface for communicating with external services and systems. A connection represents an external destination that BindAI can connect to and send data through. Connections are useful for integrating AI applications and workflows with services such as GitHub, Slack, Notion, Jira, Discord, email providers, deployment platforms, and generic webhooks.

Connection Architecture

The Connections package provides three core concepts:

Connection — the base interface for an external connection.
ConnectionRegistry — a registry of connection types available for dynamic lookup.
ConnectionManager — manages active connection instances.

The architecture can be represented as:

Application / Workflow
        |
        v
ConnectionManager
        |
        v
Connection
        |
        v
External Service

The registry provides connection types, while the manager stores concrete connection instances. This keeps external-service communication separate from agent and workflow logic.

Connection Interface

The base Connection abstraction defines a small common interface:

from bindai_connections import Connection

A connection provides:

name
connect()
disconnect()
is_connected()
send(payload)

Conceptually:

connection.connect()

if connection.is_connected():
    result = connection.send(payload)

connection.disconnect()

The exact behavior and payload format of send() depend on the specific connection implementation. Connections may raise exceptions when an operation cannot be performed.

Connection Lifecycle

A typical connection lifecycle is:

Create
  |
  v
Connect
  |
  v
Send
  |
  v
Disconnect

Connections do not necessarily maintain a long-lived network session. For some integrations, connect() may prepare or validate the connection while send() performs the actual external request. For other integrations, connect() may simply establish an internal active state. The concrete behavior depends on the integration. Applications should therefore treat connect() and disconnect() as lifecycle operations defined by each connection implementation rather than assuming a particular network behavior.

Connection Registry

ConnectionRegistry stores named connection types.

from bindai_connections import ConnectionRegistry

ConnectionRegistry.names()

The registry can be used to inspect connection types registered by the Connections package. A connection type can be retrieved by name:

connection_type = ConnectionRegistry.provider("slack")

The registry returns the connection class, not an active connection instance. The registry is useful when applications need to work with connections dynamically. For example:

connection_type = ConnectionRegistry.provider("slack")
connection = connection_type(...)

The exact constructor arguments depend on the selected connection implementation.

Registered Connections

The current package initialization registers these connection types:

webhook
slack
notion
jira
discord
resend
vercel
netlify

For example:

from bindai_connections import ConnectionRegistry

ConnectionRegistry.names()

returns the currently registered connection names. GitHubConnection is also publicly exposed by the package, but it is not currently registered with ConnectionRegistry by the package initialization. It can still be imported directly:

from bindai_connections import GitHubConnection

This distinction is intentional in the documentation: a publicly available connection class does not necessarily mean that the class is registered for dynamic lookup. The available integrations can grow independently from the core connection abstraction.

Connection Manager

ConnectionManager manages active connection instances.

from bindai_connections import ConnectionManager

manager = ConnectionManager()

A connection can be added to the manager:

manager.add(connection)

The connection is stored using its name property. Connections can then be accessed by name:

connection = manager.get("slack")

The manager also provides operations for:

Checking whether a connection exists
Connecting a connection
Disconnecting a connection
Disconnecting all active connections
Removing a connection
Listing managed connections
Listing managed connection names
Clearing all connections
Checking the number of managed connections

For example:

manager.connect("slack")
manager.disconnect("slack")

The manager operates on concrete connection instances. It does not create connection types through the registry automatically.

Connection Manager Lifecycle

A typical manager lifecycle is:

manager = ConnectionManager()

manager.add(connection)

manager.connect(connection.name)

# Use the connection...

manager.disconnect(connection.name)

A managed connection can be removed:

manager.remove(connection.name)

If the connection is active, remove() disconnects it before removing it from the manager. All active connections can be disconnected:

manager.disconnect_all()

The manager can also be cleared completely:

manager.clear()

clear() disconnects active connections and then removes all managed instances.

Connection Lookup

The manager provides direct lookup for managed instances:

connection = manager.get("slack")

If the requested connection is not managed, get() raises KeyError. Applications can check before lookup:

if manager.contains("slack"):
    connection = manager.get("slack")

Managed connections can also be inspected:

manager.all()
manager.names()
manager.size()

all() returns the managed connection instances. names() returns the names of managed connections. size() returns the number of managed connections.

Webhook Connections

WebhookConnection provides a generic integration for sending payloads to webhook endpoints. This is useful for services that expose HTTP webhook interfaces. Typical use cases include:

Automation triggers
Notifications
Workflow events
External system callbacks
Custom integrations

Webhook connections provide a general-purpose integration point without requiring a dedicated provider-specific package.

GitHub

GitHubConnection provides an HTTP connection for the GitHub REST API. The connection accepts a GitHub token and supports configurable API base URLs and request timeouts. Conceptually:

from bindai_connections import GitHubConnection

connection = GitHubConnection("github-token")
connection.connect()

result = connection.send({
    "path": "/user",
    "method": "GET",
})

The GitHub connection supports request payload fields including:

path
method
body

For requests with a body, the body is encoded as JSON. The default GitHub API base URL is:

https://api.github.com

The connection also sends the GitHub API version header used by the current implementation. GitHubConnection is publicly exported but is not currently registered with ConnectionRegistry.

Slack

SlackConnection provides an integration with Slack. Typical use cases include:

Sending notifications
Posting workflow results
Sending agent-generated messages
Alerting teams about workflow events

A workflow can therefore use a Slack connection without embedding Slack-specific communication logic throughout the workflow itself.

Notion

NotionConnection provides an integration with Notion. Potential application uses include:

Writing generated content
Updating pages
Publishing workflow results
Connecting AI workflows with workspace information

Authentication and request behavior remain specific to the Notion integration.

Jira

JiraConnection provides an integration with Jira. Typical uses include:

Creating or updating issues
Connecting AI workflows to project-management processes
Automating issue-related operations
Sending workflow results to Jira

The connection abstraction keeps Jira-specific communication separate from general workflow logic.

Discord

DiscordConnection provides an integration with Discord. Typical uses include:

Sending notifications
Publishing workflow results
Alerting Discord channels
Connecting automated workflows with communities

Resend

ResendConnection provides an integration with Resend for email-related operations. Typical uses include:

Sending application notifications
Delivering workflow results
Sending generated messages
Integrating email delivery into automated workflows

Email credentials and sender configuration should be supplied through secure deployment configuration.

Vercel

VercelConnection provides an integration with Vercel. It can be used to connect BindAI automation with deployment-related operations supported by the connection implementation. This can be useful when AI workflows participate in application deployment or infrastructure automation.

Netlify

NetlifyConnection provides an integration with Netlify. It can connect BindAI automation with deployment-related operations supported by the integration. This makes it possible to incorporate deployment platforms into larger AI-driven workflows.

Connections and Agents

Connections can be used alongside agents when an agent needs to interact with an external system. A typical architecture is:

Agent
  |
  v
Tool
  |
  v
Connection
  |
  v
External Service

The tool can provide the agent with a controlled interface while the connection handles communication with the external service. This separation is useful because agents should not need to contain provider-specific networking logic.

Connections and Workflows

Connections can also be used by workflows. For example:

Workflow
   |
   +---- Agent
   |
   +---- Tool
   |
   v
Connection
   |
   v
External Service

A workflow might:

Execute an agent.
Process the result.
Send the result through a connection.
Continue or complete execution.

The exact workflow integration depends on how the connection is used by the application or tool.

Connections and Tools

A common pattern is to expose a connection through a tool.

def notify_team(message: str) -> str:
    connection.send({"message": message})
    return "Notification sent"

The tool becomes the controlled interface available to the agent, while the connection manages external communication. This separation provides several benefits:

Provider-specific logic remains isolated.
Agents receive simple tool interfaces.
External credentials remain outside prompts.
Connections can be reused.
Tools can validate inputs before performing external actions.

Configuration

Connection configuration should remain outside application logic whenever possible. Depending on the integration, configuration may include:

API keys
Access tokens
Webhook URLs
Account identifiers
Workspace identifiers
Project identifiers
Endpoint URLs
Sender information

Sensitive credentials should normally be supplied through environment variables or a dedicated secret-management system. Never commit credentials to source control.

Connection State

The base interface exposes:

connection.is_connected()

This allows applications to determine whether a connection considers itself active. Applications should not assume that an internally connected state guarantees that an external service is currently reachable. Network availability, credentials, service availability, and authorization can change independently. A connection may therefore report an active local state while a subsequent external request still fails.

Error Handling

External services can fail for many reasons. Examples include:

Authentication failures
Invalid requests
Network failures
Rate limits
Service outages
Invalid payloads
Permission errors

Applications should handle connection failures explicitly. For operations that have external side effects, retry behavior should be designed carefully. Blindly retrying a request can create duplicate operations when the first request actually succeeded but its response was lost. The Connections package does not provide a universal retry policy for all integrations. Retry behavior should therefore be implemented at the appropriate application or workflow layer.

Idempotency

Connections that perform state-changing operations should consider idempotency. For example:

Workflow
   |
   v
Send Request
   |
   +---- Success
   |
   +---- Unknown Outcome
             |
             v
          Retry?

Before retrying a failed external operation, determine whether repeating it is safe. Where supported, use idempotency keys or other mechanisms provided by the external service. Applications should avoid assuming that every failed request can safely be repeated.

Security

Connections often provide access to external systems and therefore require careful security controls. Recommended practices include:

Keep credentials outside source code.
Use the minimum required permissions.
Validate data before sending it externally.
Restrict write operations where possible.
Protect state-changing tools.
Avoid exposing secrets to agents.
Avoid placing credentials in prompts.
Audit important external operations.
Rotate credentials when appropriate.

Connections should be treated as privileged boundaries between BindAI and external systems. When a connection is exposed through an agent tool, the tool should provide an intentionally limited interface rather than unrestricted external access.

External Data

Connections may send or receive information from external services. Applications should consider:

Data sensitivity
User authorization
Access permissions
Data retention
Logging
Compliance requirements
Cross-system data flow

Only the data required for the operation should be transmitted. Applications should also avoid unnecessarily exposing external-service responses to agents or other components.

Reusing Connections

A connection instance can be managed and reused by an application. For example:

manager = ConnectionManager()

manager.add(connection)

manager.connect(connection.name)

# Use the connection...

manager.disconnect(connection.name)

Reusing connections can simplify resource management and avoid repeatedly constructing the same integration object. The appropriate lifecycle depends on the external service and the connection implementation.

Connection Isolation

Different external services should remain logically isolated. For example:

Application
   |
   +---- Slack Connection
   |
   +---- GitHub Connection
   |
   +---- Notion Connection
   |
   +---- Jira Connection

A failure in one integration should not unnecessarily compromise unrelated integrations. Applications should also avoid sharing credentials between unrelated services.

Connections in Multi-Agent Systems

Connections can support multi-agent architectures. For example:

Team
 |
 +---- Research Agent
 |
 +---- Development Agent
 |
 +---- Communication Agent
                 |
                 v
              Slack

Different agents can use different tools and connections according to their responsibilities. This helps maintain clear boundaries between agent roles and external permissions.

Testing Connections

Connections should be tested independently from the agents and workflows that use them. Useful tests include:

Construction
Configuration validation
Connection lifecycle
Connected-state behavior
Payload handling
Authentication failures
External-service failures
Invalid responses
Cleanup
Error handling

Registry behavior should also be tested where dynamic connection lookup is used. Useful registry tests include:

Registering a connection type
Looking up a registered type
Listing registered names
Rejecting an empty connection name
Handling unknown connection names

Manager behavior should also be tested independently. Useful manager tests include:

Adding connections
Looking up managed connections
Checking membership
Connecting and disconnecting
Removing connections
Disconnecting all connections
Clearing the manager
Listing managed names
Reporting manager size

External API calls should generally be mocked in unit tests. Integration tests can be used separately when real external services are required.

Local Development

During development, connections should preferably use:

Test accounts
Mock services
Development workspaces
Non-production credentials
Safe test data

Avoid pointing development automation at production systems unless there is a deliberate reason to do so.

Production Usage

Production connections require additional operational considerations. These can include:

Credential management
Rate limits
Service availability
Network configuration
Monitoring
Failure handling
Retry behavior
Audit logging
Access control

Production infrastructure should be configured independently from local development environments.

Adding a New Connection

A new integration should implement the Connection abstraction. Conceptually:

from typing import Any
from bindai_connections import Connection

class ExampleConnection(Connection):

    @property
    def name(self) -> str:
        return "example"

    def connect(self) -> None:
        ...

    def disconnect(self) -> None:
        ...

    def is_connected(self) -> bool:
        ...

    def send(self, payload: Any) -> Any:
        ...

The implementation can then be registered with ConnectionRegistry:

ConnectionRegistry.register("example", ExampleConnection)

The exact registration and integration details should follow the current package implementation. If registration is performed during package initialization, applications can then retrieve the connection type dynamically:

connection_type = ConnectionRegistry.provider("example")

Connection Design Principles

Good connections should:

Have a clear responsibility.
Hide provider-specific communication details.
Avoid exposing credentials.
Validate external input.
Handle failures explicitly.
Keep side effects predictable.
Support testing.
Avoid unnecessary global state.
Provide clear error information.
Follow the common connection interface.

Current Scope

The current Connections package provides:

Core

Connection
ConnectionRegistry
ConnectionManager

Public Connection Classes

WebhookConnection
GitHubConnection
SlackConnection
NotionConnection
JiraConnection
DiscordConnection
ResendConnection
VercelConnection
NetlifyConnection

Currently Registered Connection Types

Webhooks
Slack
Notion
Jira
Discord
Resend
Vercel
Netlify

GitHubConnection is publicly available but is not currently registered with ConnectionRegistry. These integrations provide a foundation for connecting BindAI applications and workflows to external systems. Additional integrations can be added without changing the core connection abstraction.

Future Integrations

Potential future integrations include services such as:

Google Workspace
Stripe
Additional communication platforms
Additional project-management systems
Additional deployment platforms
Additional SaaS APIs

Future integrations should follow the same common connection architecture where appropriate.

API Accuracy

The Connections package currently provides the abstractions and APIs described in this document. The public package exposes:

from bindai_connections import (
    Connection,
    ConnectionManager,
    ConnectionRegistry,
    WebhookConnection,
    GitHubConnection,
    SlackConnection,
    NotionConnection,
    JiraConnection,
    DiscordConnection,
    ResendConnection,
    VercelConnection,
    NetlifyConnection,
)

The registry and manager serve different purposes:

ConnectionRegistry
        |
        v
Connection Types
        |
        v
ConnectionManager
        |
        v
Connection Instances

This documentation intentionally avoids assuming higher-level APIs such as:

project.add_connection(...)
application.connection(...)
workflow.connection(...)
connection.authenticate(...)
connection.receive(...)

unless those APIs are explicitly implemented. Applications should use the public interfaces provided by the installed BindAI version.

Summary

BindAI Connections provide a small abstraction for communicating with external services. The core architecture is:

Application
    |
    v
ConnectionManager
    |
    v
Connection
    |
    v
External Service

ConnectionRegistry provides named connection types for dynamic lookup, while ConnectionManager manages active connection instances. Connections can be combined with tools, agents, and workflows to build AI applications that interact with external systems. The current package publicly exposes integrations for:

Webhooks
GitHub
Slack
Notion
Jira
Discord
Resend
Vercel
Netlify

The package currently registers all of these except GitHubConnection, which remains publicly importable but is not registered for dynamic registry lookup. By keeping external-service communication behind a common interface, BindAI can add integrations incrementally while keeping application and workflow logic independent from individual service implementations.

​Connections

​Connection Architecture

​Connection Interface

​Connection Lifecycle

​Connection Registry

​Registered Connections

​Connection Manager

​Connection Manager Lifecycle

​Connection Lookup

​Webhook Connections

​GitHub

​Slack

​Notion

​Jira

​Discord

​Resend

​Vercel

​Netlify

​Connections and Agents

​Connections and Workflows

​Connections and Tools

​Configuration

​Connection State

​Error Handling

​Idempotency

​Security

​External Data

​Reusing Connections

​Connection Isolation

​Connections in Multi-Agent Systems

​Testing Connections

​Local Development

​Production Usage

​Adding a New Connection

​Connection Design Principles

​Current Scope

​Core

​Public Connection Classes

​Currently Registered Connection Types

​Future Integrations

​API Accuracy

​Summary