Skip to main content

Integration Configs

Integration configs in Erdo define how to connect to external APIs, databases, and services. They provide structured configuration for authentication, UI schemas, resource discovery, and data access patterns that agents can use in their workflows.

What are Integration Configs?

Integration configs are Python configurations that define:
  • Authentication methods (OAuth2, API keys, database connections)
  • UI configuration for user-friendly credential collection
  • Resource discovery to find available data sources
  • Code generation templates for data access
  • Credential schemas for validation

Creating Integration Configs

Define integration configs using the Erdo SDK by creating a Python file with an integration_configs list:
# my_integrations.py
from erdo.integrations import IntegrationConfig
from erdo import (
    IntegrationType,
    AuthType,
    IntegrationStatus,
    UIConfig,
    IconConfig,
    CodegenDetails,
    CredentialField,
)

# PostgreSQL Database Integration
postgresql_config = IntegrationConfig(
    name="PostgreSQL",
    key="postgresql",
    type=IntegrationType.DATABASE,
    auth_types=[AuthType.DATABASE],
    status=IntegrationStatus.ACTIVE,
    description="PostgreSQL database for comprehensive data analysis and querying",
    provider_name="PostgreSQL",
    documentation_url="https://www.postgresql.org/docs/",

    # Credential schema - defines what credentials are needed
    credential_schema={
        "host": CredentialField(
            type="string",
            description="Database host",
            required=True,
            source="integration_credentials"
        ),
        "port": CredentialField(
            type="string",
            description="Database port",
            required=True,
            source="integration_credentials"
        ),
        "database": CredentialField(
            type="string",
            description="Database name",
            required=True,
            source="integration_credentials"
        ),
        "username": CredentialField(
            type="string",
            description="Database username",
            required=True,
            source="integration_credentials"
        ),
        "password": CredentialField(
            type="string",
            description="Database password",
            required=True,
            source="integration_credentials"
        ),
    },

    # UI configuration for the Erdo interface
    ui_config=UIConfig(
        brand_logo_icon=IconConfig(set="tabler", name="database"),
        brand_color="#336791",
        button_style="blue"
    ),

    # Code generation template for agents
    codegen_details=CodegenDetails(
        code='''import psycopg2
import pandas as pd

# Connect to PostgreSQL
conn = psycopg2.connect(
    host=SECRETS["postgresql"]["host"],
    port=SECRETS["postgresql"]["port"],
    database=SECRETS["postgresql"]["database"],
    user=SECRETS["postgresql"]["username"],
    password=SECRETS["postgresql"]["password"]
)

# Example: Query data
df = pd.read_sql("SELECT * FROM your_table LIMIT 10", conn)
print(df)

conn.close()''',
        imports=["psycopg2", "pandas"],
        hint="Use psycopg2 to connect to PostgreSQL and pandas for data analysis. Connection details are configured automatically."
    )
)

# Google Sheets OAuth2 Integration
google_sheets_config = IntegrationConfig(
    name="Google Sheets",
    key="google_sheets",
    type=IntegrationType.API,
    auth_types=[AuthType.OAUTH2],
    status=IntegrationStatus.ACTIVE,
    description="Connect to Google Sheets for data analysis and reporting.",
    provider_name="Google",
    documentation_url="https://developers.google.com/sheets/api/guides/concepts",

    # OAuth2 configuration
    auth_url="https://accounts.google.com/o/oauth2/v2/auth",
    token_url="https://oauth2.googleapis.com/token",
    available_scopes=[
        "https://www.googleapis.com/auth/drive.file",
        "https://www.googleapis.com/auth/userinfo.email",
        "https://www.googleapis.com/auth/spreadsheets.readonly"
    ],
    scope_separator=" ",

    # Credential schema
    credential_schema={
        "access_token": CredentialField(
            type="string",
            description="OAuth access token",
            required=True,
            source="integration_credentials"
        ),
        "refresh_token": CredentialField(
            type="string",
            description="OAuth refresh token",
            required=False,
            source="integration_credentials"
        ),
        "spreadsheet_id": CredentialField(
            type="string",
            description="Google Sheets spreadsheet ID",
            required=True,
            source="dataset_parameters"
        ),
    },

    # UI configuration
    ui_config=UIConfig(
        brand_logo_icon=IconConfig(set="custom", name="google-sheets"),
        brand_color="#0F9D58",
        button_style="white"
    ),

    # Code generation
    codegen_details=CodegenDetails(
        code='''from googleapiclient.discovery import build
from google.oauth2.credentials import Credentials

def get_sheets_client(secret):
    credentials = Credentials(token=secret['access_token'])
    return build('sheets', 'v4', credentials=credentials)

# Example usage:
client = get_sheets_client(SECRETS["google_sheets"])
spreadsheet_id = PARAMETERS['google_sheets']['spreadsheet_id']
result = client.spreadsheets().values().get(
    spreadsheetId=spreadsheet_id,
    range='Sheet1!A1:Z1000'
).execute()
values = result.get('values', [])''',
        imports=[
            "from googleapiclient.discovery import build",
            "from google.oauth2.credentials import Credentials"
        ]
    )
)

# Export the integration configs for Erdo to discover
integration_configs = [
    postgresql_config,
    google_sheets_config,
]

Integration Config Components

Authentication Types

Database Authentication:
auth_types=[AuthType.DATABASE]
credential_schema={
    "host": CredentialField(type="string", required=True, source="integration_credentials"),
    "username": CredentialField(type="string", required=True, source="integration_credentials"),
    "password": CredentialField(type="string", required=True, source="integration_credentials"),
}
OAuth2 Authentication:
auth_types=[AuthType.OAUTH2]
auth_url="https://accounts.google.com/o/oauth2/v2/auth"
token_url="https://oauth2.googleapis.com/token"
available_scopes=["https://www.googleapis.com/auth/userinfo.email"]
API Key Authentication:
auth_types=[AuthType.API_KEY]
credential_schema={
    "api_key": CredentialField(type="string", required=True, source="integration_credentials")
}

UI Configuration

Customize how the integration appears in the Erdo interface:
ui_config=UIConfig(
    brand_logo_icon=IconConfig(set="tabler", name="database"),
    brand_color="#336791",
    button_style="blue"  # "blue", "brand", "white"
)

Code Generation

Provide templates that agents can use to connect to your integration:
codegen_details=CodegenDetails(
    code="import requests\nresponse = requests.get(url, headers={'Authorization': f'Bearer {token}'})",
    imports=["requests"],
    hint="Use the requests library to make API calls with authentication"
)

Managing Integration Configs

Sync Integration Configs

Upload your integration configs to Erdo:
# Sync single integration config file
erdo sync-integration-config my_integrations.py

# Sync all integration configs in directory
erdo sync-integration-config ./integrations/

# Dry run to see what would be synced
erdo sync-integration-config --dry-run ./integrations/

List Integration Configs

View available integration configs on the server:
# List all integration configs
erdo list-integration-configs

# Plain output (names only)
erdo list-integration-configs --plain

Export Integration Configs

Download integration config definitions:
erdo export-integration stripe

Using Integration Configs in Agents

Once synced, integration configs can be used in agent workflows:
from erdo import Agent
from erdo.actions import integration, llm

agent = Agent(name="data_analyzer")

# Fetch data from PostgreSQL integration
fetch_data = agent.step(
    integration.query(
        integration_key="postgresql",
        query="SELECT * FROM sales WHERE date >= '2024-01-01'"
    ),
    key="fetch_data"
)

# Analyze the fetched data
analyze = agent.step(
    llm.message(
        prompt="Analyze this sales data: {{steps.fetch_data.result}}"
    ),
    key="analyze",
    depends_on=["fetch_data"]
)

agents = [agent]

File Structure

Organize your integration configs in a clear directory structure:
my-integrations/
├── database_integrations.py      # Database configs (PostgreSQL, MySQL, etc.)
├── api_integrations.py          # API configs (Stripe, Salesforce, etc.)
├── google_integrations.py       # Google services (Sheets, Analytics, etc.)
└── __init__.py                   # Optional: import all configs
Each file should follow the pattern:
# File: database_integrations.py
from erdo.integrations import IntegrationConfig
from erdo import IntegrationType, AuthType, IntegrationStatus

# Define your configs
postgresql_config = IntegrationConfig(...)
mysql_config = IntegrationConfig(...)

# Export for discovery
integration_configs = [
    postgresql_config,
    mysql_config,
]

Best Practices

  1. Clear Naming: Use descriptive names and keys for your integration configs
  2. Comprehensive Schemas: Define all required and optional credential fields
  3. Helpful Documentation: Provide clear descriptions and documentation URLs
  4. Code Templates: Include practical code examples in codegen_details
  5. Error Handling: Consider edge cases in your credential schemas
  6. Security: Never include actual credentials in your config definitions

Example Integration Configs

The Erdo repository includes example integration configs:
  • Database integrations: PostgreSQL, MySQL
  • Google services: Sheets, Analytics, Ads
  • Payment platforms: Stripe
  • CRM systems: HubSpot
  • Marketing platforms: Meta Ads

Next Steps