> ## Documentation Index > Fetch the complete documentation index at: https://docs.bindai.dev/llms.txt > Use this file to discover all available pages before exploring further. # Connections > Connect BindAI applications to external services and systems. # 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: ```text theme={null} 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: ```python theme={null} from bindai_connections import Connection ``` A connection provides: * `name` * `connect()` * `disconnect()` * `is_connected()` * `send(payload)` Conceptually: ```python theme={null} 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: ```text theme={null} 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. ```python theme={null} 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: ```python theme={null} 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: ```python theme={null} 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: ```python theme={null} 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: ```python theme={null} 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. ```python theme={null} from bindai_connections import ConnectionManager manager = ConnectionManager() ``` A connection can be added to the manager: ```python theme={null} manager.add(connection) ``` The connection is stored using its `name` property. Connections can then be accessed by name: ```python theme={null} 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: ```python theme={null} 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: ```python theme={null} manager = ConnectionManager() manager.add(connection) manager.connect(connection.name) # Use the connection... manager.disconnect(connection.name) ``` A managed connection can be removed: ```python theme={null} manager.remove(connection.name) ``` If the connection is active, `remove()` disconnects it before removing it from the manager. All active connections can be disconnected: ```python theme={null} manager.disconnect_all() ``` The manager can also be cleared completely: ```python theme={null} manager.clear() ``` `clear()` disconnects active connections and then removes all managed instances. *** # Connection Lookup The manager provides direct lookup for managed instances: ```python theme={null} connection = manager.get("slack") ``` If the requested connection is not managed, `get()` raises `KeyError`. Applications can check before lookup: ```python theme={null} if manager.contains("slack"): connection = manager.get("slack") ``` Managed connections can also be inspected: ```python theme={null} 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: ```python theme={null} 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: ```text theme={null} 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: ```text theme={null} 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: ```text theme={null} Workflow | +---- Agent | +---- Tool | v Connection | v External Service ``` A workflow might: 1. Execute an agent. 2. Process the result. 3. Send the result through a connection. 4. 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. ```python theme={null} 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: ```python theme={null} 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: ```text theme={null} 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: ```python theme={null} 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: ```text theme={null} 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: ```text theme={null} 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: ```python theme={null} 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`: ```python theme={null} 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: ```python theme={null} 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: ```python theme={null} from bindai_connections import ( Connection, ConnectionManager, ConnectionRegistry, WebhookConnection, GitHubConnection, SlackConnection, NotionConnection, JiraConnection, DiscordConnection, ResendConnection, VercelConnection, NetlifyConnection, ) ``` The registry and manager serve different purposes: ```text theme={null} ConnectionRegistry | v Connection Types | v ConnectionManager | v Connection Instances ``` This documentation intentionally avoids assuming higher-level APIs such as: ```python theme={null} 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: ```text theme={null} 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.