Skip to main content
Managed tools let an agent call first-party integrations through Voice.ai-managed operations instead of custom webhook tools. Today, managed tools cover Google Calendar, Google Sheets, and Gmail.
Prerequisites: API key, an existing voice agent, and a Google Cloud OAuth app configured with the Voice.ai callback URL.

​
Overview

Managed tools are configured on the agent under config.managed_tools. Supported managed tool configs:
  • google_calendar
  • google_sheets
  • google_gmail
Supported operations:
  • Calendar: google_calendar_check_availability, google_calendar_list_upcoming_events, google_calendar_create_event, google_calendar_update_event, google_calendar_cancel_event
  • Sheets: google_sheets_append_row, google_sheets_list_sheets, google_sheets_read_rows
  • Gmail: google_gmail_search_messages, google_gmail_get_message, google_gmail_send_email
Use managed tools when you want Voice.ai to handle:
  • provider OAuth connection state
  • scope calculation and reconnect checks
  • generated callable tool definitions for the runtime
  • provider API execution on behalf of the connected user
Current managed-tools model:
  • Connection routes are provider-scoped and use /api/v1/{provider}/....
  • If you enable additional operations later, status can report reconnect_required until you reconnect and grant the additional access.
  • DELETE /api/v1/{provider}/{agent_id}/disconnect removes that provider’s managed-tools access for the agent.

​
Configure an Agent

Set config.managed_tools on the agent with the managed tool configs you want to enable. 
{
  "name": "Executive Assistant",
  "config": {
    "prompt": "You are a concise executive assistant.",
    "managed_tools": {
      "google_calendar": {
        "enabled": true,
        "default_calendar_id": "primary",
        "timezone": "America/Los_Angeles",
        "selected_operations": [
          "google_calendar_check_availability",
          "google_calendar_create_event",
          "google_calendar_update_event"
        ]
      },
      "google_sheets": {
        "enabled": true,
        "spreadsheet_id": "1abc123example",
        "sheet_name": "Leads",
        "selected_operations": [
          "google_sheets_append_row",
          "google_sheets_read_rows"
        ]
      },
      "google_gmail": {
        "enabled": true,
        "selected_operations": [
          "google_gmail_search_messages",
          "google_gmail_get_message"
        ]
      }
    }
  }
}
Managed tool config fields:
Managed tool configFieldTypeDescription
google_calendarenabledbooleanEnable Calendar managed tools for the agent
google_calendardefault_calendar_idstringOptional default calendar ID. Falls back to primary when omitted
google_calendartimezonestringOptional IANA timezone like America/Los_Angeles
google_calendarselected_operationsstring[]Optional subset of Calendar operations. Omit for all supported Calendar operations
google_sheetsenabledbooleanEnable Sheets managed tools for the agent
google_sheetsspreadsheet_idstringOptional default spreadsheet ID
google_sheetssheet_namestringOptional default worksheet tab name
google_sheetsselected_operationsstring[]Optional subset of Sheets operations. Omit for all supported Sheets operations
google_gmailenabledbooleanEnable Gmail managed tools for the agent
google_gmailselected_operationsstring[]Optional subset of Gmail operations. Omit for all supported Gmail operations
If selected_operations is omitted, Voice.ai treats that managed tool config as “all supported operations selected.” If selected_operations is an empty array, the config stays present but requests no provider-specific scopes.

​
Connect a Provider

Connection routes use the provider segment for the managed integration you are connecting, so the examples below use {provider} as a placeholder. The OAuth flow is:
  1. Call POST /api/v1/{provider}/{agent_id}/oauth/start
  2. Open the returned auth_url in a popup or browser
  3. The OAuth provider redirects back to the Voice.ai callback URL
  4. Voice.ai stores the connection and returns a popup completion page
  5. Poll GET /api/v1/{provider}/{agent_id}/status
Notes:
  • return_path is the app URL Voice.ai sends the user back to after the backend callback completes.
  • The OAuth provider still redirects to the Voice.ai backend callback URL configured in your OAuth app. return_path only controls the final app destination after that callback finishes.
  • The Google connection is shared across Calendar, Sheets, and Gmail for the agent.
  • Pass the currently enabled Google managed tool config in managed_tools so OAuth requests access for the Google tools that are enabled on the agent.
  • If you enable more Google capabilities later, start OAuth again with the updated Google managed tool config for the agent.
  • Disconnect remains provider-wide. Disconnecting Google removes Calendar, Sheets, and Gmail access for that agent.
Example: 
curl -X POST "https://dev.voice.ai/api/v1/{provider}/agent_123/oauth/start" \
  -H "Authorization: Bearer vk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "return_path": "https://app.example.com/settings/agent-google",
    "managed_tools": {
      "google_calendar": {
        "enabled": true,
        "timezone": "America/Los_Angeles",
        "selected_operations": [
          "google_calendar_check_availability",
          "google_calendar_create_event"
        ]
      }
    }
  }'
Successful response: 
{
  "auth_url": "https://accounts.google.com/o/oauth2/v2/auth?...",
  "requested_scopes": [
    "openid",
    "https://www.googleapis.com/auth/userinfo.email",
    "https://www.googleapis.com/auth/calendar"
  ]
}

​
Check Connection Status

Use provider status to confirm the account is connected and whether a reconnect is required. 
curl "https://dev.voice.ai/api/v1/{provider}/agent_123/status" \
  -H "Authorization: Bearer vk_your_api_key"
Example response: 
{
  "connected": true,
  "agent_id": "agent_123",
  "granted_scopes": [
    "openid",
    "https://www.googleapis.com/auth/userinfo.email",
    "https://www.googleapis.com/auth/calendar"
  ],
  "scopes": [
    "openid",
    "https://www.googleapis.com/auth/userinfo.email",
    "https://www.googleapis.com/auth/calendar"
  ],
  "required_scopes": [
    "openid",
    "https://www.googleapis.com/auth/userinfo.email",
    "https://www.googleapis.com/auth/calendar"
  ],
  "missing_scopes": [],
  "reconnect_required": false
}

​
Disconnect a Provider

Remove the linked provider account from the agent: 
curl -X DELETE "https://dev.voice.ai/api/v1/{provider}/agent_123/disconnect" \
  -H "Authorization: Bearer vk_your_api_key"

​
Tool Behavior

Managed tools are exposed to the runtime as generated callable tools. The exact tool set depends on:
  • which providers are enabled
  • which operations are selected
  • which scopes are currently granted
Mutating operations such as creating calendar events, appending rows, and sending email are designed to require clear user confirmation before the agent should act.

​
Timezones and Defaults

  • Calendar timezone must be an IANA timezone like America/Los_Angeles
  • Calendar operations can fall back to the configured default_calendar_id and timezone
  • Sheets operations can fall back to the configured spreadsheet_id and sheet_name

​
API Reference

The full request and response schemas are available in the API reference under Managed Tools.