How to Build AI Agents With Gmail and Hubspot Authentication Using Arcade - Step by Step Guide

Arcade.dev transforms AI agents from conversational interfaces into production-ready automation tools that can securely take real-world actions through authenticated integrations. Unlike traditional AI agents that are limited to read-only operations, Arcade enables agents to manage emails, create HubSpot contacts, schedule meetings, and perform complex workflows with enterprise-grade OAuth 2.0 security. This comprehensive guide provides step-by-step instructions for implementing Gmail and HubSpot authentication using Arcade's official toolkits, complete with code examples, configuration details, and production deployment strategies.

The authentication challenge has kept 70% of AI agent projects from reaching production. Arcade solves this by providing managed OAuth flows, automatic token refresh, and secure credential handling that keeps sensitive data isolated from AI models. With 96+ pre-built integrations and support for major frameworks like LangChain, CrewAI, and OpenAI Agents, developers can build sophisticated multi-service workflows in minutes rather than weeks.

Understanding Arcade's Authentication-First Architecture

Arcade.dev operates as an AI tool-calling platform built specifically to bridge the gap between AI models and authenticated external services. The platform consists of four core components that work together to provide seamless integration capabilities.

The Arcade Engine serves as both your MCP (Model Context Protocol) server and primary tool provider, managing authentication flows, tool registration, and secure execution. This engine can run locally for development, in the cloud for managed hosting, or on-premises for enterprise deployments, requiring at least one Arcade worker to function properly.

Arcade Dashboard provides centralized management for tools, users, and deployments through an intuitive web interface. Available at https://api.arcade.dev/dashboard for cloud deployments, the dashboard scales automatically with organization size and provides real-time monitoring of agent activities.

The platform's modular library architecture includes specialized components:
• arcade-core for platform functionality
• arcade-tdk for the Tool Development Kit with @tool decorator
• arcade-serve for infrastructure
• arcade-evals for testing
• arcade-cli for command-line operations

This separation allows developers to install only required components and customize deployments based on specific needs.

Client libraries support multiple programming languages with ArcadePy for Python, ArcadeJs for TypeScript, and ArcadeGo for Go implementations. Each library provides identical functionality with language-specific optimizations and framework integrations.

Step 1. Gmail Integration Setup and Configuration

Gmail integration through Arcade eliminates the complexity typically associated with Google OAuth implementation while maintaining enterprise-grade security standards. The Gmail toolkit is fully available as an official Arcade toolkit, developed and maintained directly by the Arcade team with comprehensive support for email management operations.

1.1 Available Gmail Operations

The Arcade Gmail toolkit provides essential email management capabilities through well-defined API methods.

Email management operations include:
• Gmail.ListEmails for retrieving inbox contents
• Gmail.SendEmail for sending messages via Gmail API
• Gmail.SearchEmails for searching through emails and threads
• Gmail.GetMessage for retrieving specific messages
• Gmail.GetThread for accessing email conversations

Draft management capabilities encompass:
• Gmail.CreateDraft for composing new drafts
• Gmail.UpdateDraft for modifying existing drafts
• Gmail.DeleteDraft for removing draft emails

Advanced operations like Gmail.TrashEmail for moving emails to trash are available exclusively on self-hosted instances, providing additional functionality for organizations requiring complete email lifecycle management.

1.2 Three-Line Authorization Implementation

Arcade's Just-in-Time (JIT) authorization pattern provides the most streamlined OAuth implementation available for AI agents:

from arcade.client import Arcade

# Initialize client with API key
arcade_client = Arcade(api_key="your_arcade_api_key")

# Authorize Gmail access for specific user
result = arcade_client.tools.authorize(
    tool_name="Gmail.ListEmails",
    user_id="user@example.com"
)

# Handle authorization flow automatically
if result.status != "completed":
    print(f"Click this link to authorize: {result.url}")
    arcade_client.auth.wait_for_completion(result)

This implementation handles the complete OAuth flow:
• Initial request triggers authorization check
• Generates dynamic authorization link if needed
• Processes user consent through secure browser flow
• Manages token storage and refresh automatically
• Enables secure execution with user's actual credentials

1.3 Environment Configuration Requirements

Hosted solution setup requires minimal configuration - only an Arcade API key from the dashboard and unique user identifiers for each application user. Google Cloud Console configuration, OAuth flow management, and token handling are managed automatically by Arcade's infrastructure.

Self-hosted deployments require additional setup including:
• Google Cloud Console configuration with custom OAuth 2.0 credentials
• Custom auth provider configuration
• Infrastructure deployment of Arcade Engine on your systems

Essential environment variables include:

# Required API Keys
ARCADE_API_KEY=your_arcade_api_key
OPENAI_API_KEY=your_openai_api_key  # For LLM framework integration

# User Configuration
USER_ID=unique_user_identifier

# Database for persistent memory (optional)
DATABASE_URL=postgresql://user:password@host:port/database

1.4 Comprehensive Gmail Integration Example

import asyncio
from arcadepy import AsyncArcade

async def main():
    # Initialize Arcade client
    client = AsyncArcade(api_key="your_arcade_api_key")
    user_id = "user@example.com"

    # Authorize Gmail access
    result = await client.tools.authorize(
        tool_name="Gmail.ListEmails",
        user_id=user_id
    )

    if result.status != "completed":
        print(f"Authorize Gmail: {result.url}")
        await client.auth.wait_for_completion(result)

    # Retrieve recent emails
    emails = await client.tools.call(
        tool_name="Gmail.ListEmails",
        user_id=user_id,
        arguments={"max_results": 10}
    )

    # Search for specific emails
    search_results = await client.tools.call(
        tool_name="Gmail.SearchEmails",
        user_id=user_id,
        arguments={"query": "from:support@company.com"}
    )

    # Send automated response
    send_result = await client.tools.call(
        tool_name="Gmail.SendEmail",
        user_id=user_id,
        arguments={
            "to": "recipient@example.com",
            "subject": "Automated Response from AI Agent",
            "body": "This email was processed and responded to automatically."
        }
    )

    print(f"Retrieved {len(emails.result)} emails")
    print(f"Found {len(search_results.result)} matching emails")
    print(f"Email sent successfully: {send_result.success}")

asyncio.run(main())

Step 2. HubSpot CRM Integration and Authentication

HubSpot integration through Arcade provides comprehensive CRM capabilities with official Arcade toolkit designation, ensuring full support and maintenance by the Arcade development team. The integration supports both hosted cloud and self-hosted deployments with flexible authentication configurations.

2.1 HubSpot Toolkit Operations

The HubSpot toolkit provides three core operations designed for comprehensive CRM management:

HubSpot.GetCompanyDataByKeywords retrieves company information with associated objects including:
• Deals, calls, emails, meetings, notes, and tasks
• Search against company name, phone, and website
• Pagination through next_page_token parameters

HubSpot.GetContactDataByKeywords enables full-text contact search with:
• Associated objects including calls, emails, meetings, notes, tasks, companies, and deals
• Keyword-based searching with configurable limits up to 10 results per request
• Pagination support for larger datasets

HubSpot.CreateContact facilitates new contact creation with:
• Company association requiring company_id and first_name as mandatory parameters
• Optional fields for last_name, email, phone, mobile_phone, and job_title
• Comprehensive contact profile creation

2.2 HubSpot Authentication Configuration

OAuth 2.0 implementation follows:
• Authorization code grant flow with redirect URL https://cloud.arcade.dev/api/v1/oauth/callback
• Automatic token management including access and refresh token handling
• User consent workflows with appropriate scope configuration

Three configuration approaches provide flexibility for different deployment scenarios:

1. Arcade Cloud Default Provider offers zero-configuration setup where users see "Arcade" as the requesting application, ideal for quick prototyping and development with no additional setup requirements.

2. Custom HubSpot Auth Provider through Arcade Cloud enables branded user experience where users see your application name. Configuration involves:
• Navigate to OAuth section → Providers in the Arcade Dashboard
• Click "Add OAuth Provider"
• Select "HubSpot" from provider dropdown
• Enter unique provider ID
• Input Client ID and Secret from your HubSpot app
• Save the configuration

2.3 HubSpot App Creation Requirements

Developer account setup begins with:
• Log into HubSpot App Developer account
• Navigate to Apps → Create App
• Configure App Info including name, description, logo, and support contact information
• Access the Auth tab to obtain Client ID and Client Secret credentials

OAuth configuration requires:
• Set redirect URL to https://cloud.arcade.dev/api/v1/oauth/callback
• Configure appropriate scopes based on toolkit requirements
• Select minimum required scopes for Arcade toolkit functionality
• Consider additional scopes for extended operations based on specific use case requirements

2.4 HubSpot Integration Code Examples

from arcadepy import Arcade

# Initialize Arcade client
client = Arcade(api_key="your_arcade_api_key")
user_id = "user_email@domain.com"

# Search for companies with technology focus
company_response = client.tools.call(
    tool_name="Hubspot.GetCompanyDataByKeywords",
    parameters={
        "keywords": "technology startup",
        "limit": 5
    },
    user_id=user_id
)

# Search for contacts in sales roles
contact_response = client.tools.call(
    tool_name="Hubspot.GetContactDataByKeywords",
    parameters={
        "keywords": "sales manager",
        "limit": 10
    },
    user_id=user_id
)

# Create new contact associated with company
new_contact = client.tools.call(
    tool_name="Hubspot.CreateContact",
    parameters={
        "company_id": "123456789",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com",
        "job_title": "Software Engineer"
    },
    user_id=user_id
)

print(f"Found {len(company_response.result)} companies")
print(f"Found {len(contact_response.result)} contacts")
print(f"Created contact: {new_contact.success}")

Step 3. Advanced Configuration and Toolkit Management

Arcade's comprehensive authentication system supports 96+ integrations across communication, productivity, business, search, entertainment, development, and analytics categories. The platform organizes integrations into four designation types:

• Arcade Toolkit for official integrations developed by Arcade
• Verified Toolkit for community-created integrations tested by Arcade
• Community Toolkit for community-maintained integrations
• Auth Integration for custom API connections

Step 4. Framework Integration and Agent Development

Arcade provides native support for major AI agent frameworks including:

• LangChain/LangGraph with full toolkit integration and user authorization
• CrewAI with custom auth flows and tool management
• OpenAI Agents with direct tool calling
• Vercel AI with tool integration patterns
• Mastra with Zod schema integration

4.1 LangGraph Integration Example

from arcade_tdk import ToolManager
from langgraph.prebuilt import create_react_agent

# Initialize tool manager with Arcade credentials
tool_manager = ToolManager(arcade_api_key="your_key")

# Get Gmail and HubSpot tools for agent
agent_tools = tool_manager.get_tools(
    toolkits=["gmail", "hubspot"],
    user_id="user@example.com"
)

# Create agent with email and CRM capabilities
agent = create_react_agent(llm, agent_tools)

# Execute agent workflow
response = agent.invoke({
    "messages": ["Check my emails and update HubSpot with any new leads"]
})

4.2 Custom Tool Development Pattern

from typing import Annotated
from arcade_tdk import ToolContext, tool
from arcade_tdk.auth import OAuth2

@tool(
    requires_auth=OAuth2(
        provider_id="custom-provider",
        scopes=["read", "write"]
    )
)
async def custom_integration_tool(
    context: ToolContext,
    parameter: Annotated[str, "Parameter description"]
) -> Annotated[dict, "Return type description"]:
    """Custom tool description for LLM understanding."""

    # Access user's authenticated token
    token = context.authorization.token

    # Access user information if configured
    user_info = context.authorization.user_info

    # Tool implementation with authenticated API calls
    return {"result": "success", "data": processed_data}

Step 5. Production Deployment and Best Practices

Deployment flexibility supports multiple scenarios from individual developers to enterprise teams:

• Arcade Cloud - Managed service with dashboard configuration, automatic scaling, built-in monitoring, and OAuth management
• Self-hosted deployment - Full control with custom configuration, on-premises security, and infrastructure management
• Hybrid approaches - Combine cloud and on-premises components for balanced control and convenience

5.1 Production Infrastructure Configuration

Engine configuration for production deployments requires comprehensive setup through engine.yaml:

# API Configuration
api:
  development: false
  http:
    host: 0.0.0.0
    read_timeout: 30s
    write_timeout: 1m
    idle_timeout: 30s

# Storage Backend (PostgreSQL for production)
storage:
  postgres:
    connection_string: 'postgresql://user:password@host:port/database'

# Cache Configuration (Redis for multi-node)
cache:
  redis:
    url: 'redis://redis-host:6379'
  api_key_ttl: 10s

# LLM Models
llm:
  models:
    - id: primary
      openai:
        api_key: ${env:OPENAI_API_KEY}
    - id: secondary
      anthropic:
        api_key: ${env:ANTHROPIC_API_KEY}

5.2 Testing and Evaluation Framework

Built-in evaluation capabilities provide comprehensive testing through multiple approaches:

• Unit tests verify individual tool functionality
• Integration tests validate tool-to-tool interactions
• Performance tests monitor speed and resource utilization
• Authorization tests ensure OAuth security
• End-to-end tests validate complete workflows

# Run comprehensive evaluations
arcade evals toolkits/gmail/evals --details --models gpt-4o
arcade evals toolkits/hubspot/evals --models gpt-4.1-mini

# Development testing commands
make test              # Run all tests
make check            # Linting and type checking
make build            # Build packages

Debugging capabilities include:
• Detailed request/response logging
• Dashboard monitoring with real-time execution tracking
• Comprehensive error handling
• Streaming debug capabilities for real-time response inspection

Step 6. Multi-Agent Architecture Patterns

Sophisticated agent architectures leverage Arcade's authentication capabilities for complex workflows. Specialized agent patterns include:

• Monitoring agents that scan calendars and documents for stress indicators
• Research agents that find and profile external resources
• Execution agents that handle scheduling and coordination tasks

# Multi-agent coordinator example
class EmailCRMAgent:
    def __init__(self, arcade_client, user_id):
        self.arcade = arcade_client
        self.user_id = user_id

    async def process_new_leads(self):
        # Gmail agent: scan for lead emails
        lead_emails = await self.arcade.tools.call(
            tool_name="Gmail.SearchEmails",
            arguments={"query": "lead OR inquiry OR interested"},
            user_id=self.user_id
        )

        # Processing agent: extract lead information
        for email in lead_emails.result:
            lead_data = await self.extract_lead_info(email)

            # HubSpot agent: create contact
            contact = await self.arcade.tools.call(
                tool_name="HubSpot.CreateContact",
                arguments={
                    "first_name": lead_data["first_name"],
                    "last_name": lead_data["last_name"],
                    "email": lead_data["email"],
                    "company_id": lead_data["company_id"]
                },
                user_id=self.user_id
            )

            # Follow-up agent: schedule next contact
            await self.schedule_follow_up(contact.result)

Conclusion

Arcade.dev represents a paradigm shift in AI agent development by solving the fundamental authentication challenge that has prevented most projects from reaching production. The platform's authentication-first architecture, comprehensive toolkit ecosystem, and production-ready infrastructure enable developers to build sophisticated agents that seamlessly integrate with Gmail, HubSpot, and dozens of other services.

Key advantages include:
• Three-line authentication setup that eliminates OAuth complexity
• Production-grade security with automatic token management
• Extensive framework support for existing development workflows
• Comprehensive documentation with practical examples
• Flexible deployment options from cloud to on-premises

The platform successfully bridges the gap between AI capabilities and real-world integrations, making authenticated agent development accessible while maintaining enterprise security and reliability standards.

With 96+ integrations, multi-framework support, and enterprise-grade security, Arcade enables developers to focus on agent logic rather than authentication infrastructure. Whether building simple email automation or complex multi-service workflows, Arcade provides the foundation for production-ready AI agents that can take real-world actions securely and reliably.

Additional Resources

• Arcade Documentation - Complete platform documentation
• Arcade Toolkits - Browse all available integrations
• API Reference - Detailed API documentation
• GitHub Repository - Source code and examples
• Getting Started Guide - Quick start tutorial
• SSO for AI Agents Guide - Authentication best practices
• Gmail Agent Tutorial - Detailed Gmail integration guide