# Using Personal Connectors

div
strong
🔨 In Development
 — This section is still being developed and may change.


Learn how to integrate personal connectors into your AI assistants and leverage external services in your workflows.

## Overview

Personal connectors become available as functions that your assistants can call during conversations. This enables seamless integration with external services without complex API management.

## Basic Usage

### 1. Enable Connectors in Assistants

When creating or updating an assistant, reference your configured connectors:


```python
# Create assistant with connector access
assistant = freddy.assistants.create(
    name="Connected Assistant",
    instructions="""You have access to my personal connectors. Use them to:

    - Search my Notion workspace for relevant information
    - Send emails through Gmail when requested
    - Access my Google Calendar for scheduling
    - Query my personal database for data

    Always ask for clarification if a request is ambiguous.""",
    model="gpt-4",
    tools=[
        # Connector functions are automatically available
        # based on your configurations
    ]
)
```

### 2. Function Calling

Your assistant will automatically discover and use available connector functions:


```python
# Example conversation
message = freddy.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="Can you check my Notion workspace for project ideas?"
)

# The assistant will automatically:
# 1. Recognize this requires the Notion connector
# 2. Call the appropriate connector function
# 3. Format and return the results
```

## Advanced Integration Patterns

### Multi-Connector Workflows

Create assistants that use multiple connectors in sequence:


```python
instructions = """
You can access multiple services:

1. Use Notion to research and gather information
2. Use Gmail to send follow-up emails
3. Use Google Calendar to schedule meetings
4. Use Slack to share updates with the team

When a user requests a complex task, break it down into steps using these tools.
"""
```

### Error Handling and Fallbacks

Design robust workflows with proper error handling:


```python
# In your assistant's error handling strategy
"""
If a connector fails:
1. Inform the user about the issue
2. Suggest alternatives if available
3. Offer to retry or use a different approach
4. Escalate to human support if needed

Always be transparent about what went wrong and what you're doing to fix it.
"""
```

## Real-World Examples

### Research Assistant


```python
# Research assistant that uses multiple connectors
research_assistant = freddy.assistants.create(
    name="Research Assistant",
    instructions="""You are a research assistant with access to:

    - Notion workspace for note-taking and research storage
    - Web search for current information
    - Gmail for communicating findings
    - Google Drive for document storage

    Research Process:
    1. Search for information using available tools
    2. Organize findings in Notion
    3. Summarize key insights
    4. Share results via email or document""",
    model="gpt-4"
)
```

### Project Manager


```python
# Project management assistant
project_assistant = freddy.assistants.create(
    name="Project Manager",
    instructions="""You help manage projects using:

    - Notion for task and project tracking
    - Google Calendar for scheduling
    - Slack for team communication
    - Linear for issue tracking

    Always keep project information synchronized across all platforms.""",
    model="gpt-4"
)
```

## Best Practices

### 🔄 **Workflow Design**

- Design clear workflows that leverage multiple connectors
- Implement proper error handling and fallback strategies
- Test connector integrations thoroughly
- Monitor connector performance and reliability


### 📊 **Data Management**

- Be mindful of data privacy and security
- Implement proper data validation and sanitization
- Handle rate limits and API quotas gracefully
- Cache data when appropriate to reduce API calls


### 🔧 **Maintenance**

- Regularly review and update connector configurations
- Monitor connector health and performance
- Keep credentials and tokens up to date
- Update assistant instructions as connectors evolve


## Monitoring and Debugging

### Logging Connector Activity

Monitor connector usage through Freddy's logging system:


```python
# Access connector logs
logs = freddy.personal_connectors.get_logs(
    configuration_id="config_123",
    start_date="2024-01-01",
    end_date="2024-01-31"
)

for log in logs:
    print(f"Function: {log.function_name}")
    print(f"Status: {log.status}")
    print(f"Duration: {log.duration_ms}ms")
```

### Troubleshooting Common Issues

**Connector Not Available**

- Verify the connector configuration is active
- Check that the assistant has access to the connector
- Ensure credentials are valid and not expired


**Function Call Failures**

- Check API rate limits and quotas
- Verify network connectivity
- Review error messages for specific issues
- Test connector functions independently


**Performance Issues**

- Monitor response times for slow connectors
- Implement caching for frequently accessed data
- Consider data pagination for large datasets
- Optimize function call patterns


## Cost Management

### Understanding Costs

- Each connector may have associated costs
- Monitor usage through [Freddy Hub](https://freddy-hub.aitronos.com)
- Set up usage alerts and budgets
- Optimize workflows to minimize costs


### Cost Optimization Strategies

- Cache frequently accessed data
- Batch multiple operations when possible
- Use webhooks instead of polling where available
- Implement smart retry logic to avoid unnecessary calls


## Security Considerations

### Data Protection

- Connectors handle sensitive data - ensure proper encryption
- Implement access controls and permissions
- Regular security audits of connector configurations
- Monitor for unusual access patterns


### Compliance

- Ensure connector usage complies with service terms
- Maintain audit trails for regulatory compliance
- Implement data retention policies
- Regular security assessments


## Advanced Features

### Custom Function Development

Create custom functions that leverage multiple connectors:


```python
def comprehensive_research(query: str) -> Dict:
    """Perform comprehensive research using multiple connectors."""

    results = {
        "web_search": web_search_connector.search(query),
        "notion_search": notion_connector.search(query),
        "document_search": drive_connector.search(query)
    }

    # Combine and rank results
    combined_results = combine_search_results(results)

    return {
        "query": query,
        "results": combined_results,
        "sources_used": list(results.keys())
    }
```

### Event-Driven Workflows

Set up connectors to trigger workflows based on external events:


```python
# Example: Email-triggered workflow
"""
When a new email arrives in Gmail:
1. Analyze the email content
2. Search for related information in Notion
3. Create a task in your project management tool
4. Send a notification via Slack
"""
```

## Next Steps

- [Set up Authentication](/docs/documentation/personal-connectors/authentication) - Configure your connectors
- [Billing Guide](/docs/documentation/personal-connectors/billing) - Understand costs and limits
- [Connectors Overview](/docs/documentation/personal-connectors/overview) - Learn about available connectors
- [API Reference](/docs/api-reference/personal-connectors/list) - Technical documentation


For technical support, contact [support@aitronos.com](mailto:support@aitronos.com).