EXPLAINER

Connecting AI Agents to External Applications

An agent reaches Gmail, calendars or CRMs only through tools you define and run. The model requests a tool call; your server performs the API or MCP action with proper credentials and permissions.

Short answer: Agents do not magically have an inbox: you supply a tool, the model may call it, and your code talks to the external app.

What is it?

Language models cannot open Gmail or Salesforce by themselves. Integration means you expose a narrow capability as an agent tool (via Function Calling (Tool Calling) Explained or What is MCP (Model Context Protocol)?), obtain credentials (OAuth or API keys), execute the call on a server, and return a summarised result to the model.

Why it matters

This is how agents become useful — and how they become dangerous. Every external action needs authentication, authorisation, logging and often human approval (Permissions and Security for AI Integrations).

How to do it

  1. Decide the user-visible jobs ("list unread", "draft reply") — not raw "call any Google API".
  2. Implement those jobs as server functions with explicit inputs.
  3. Obtain tokens via OAuth with least-privilege scopes, storing refresh tokens server-side.
  4. Register tools with clear descriptions; validate arguments.
  5. Prefer read-only tools first; gate send/delete on confirmation.
  6. Treat returned content (email bodies, tickets) as untrusted (What is Prompt Injection?).
  7. Choose direct API wrapping vs an MCP server based on reuse needs.

Example

User: "What are my three latest unread emails?"

  1. Model calls list_unread(max=3).
  2. Your server uses the user's Google refresh token, calls Gmail API, returns subjects + ids only.
  3. Model summarises for the user.
  4. If the user says "archive the first", you require confirmation before archive(id).

When to use it

Integrate when the product promise requires live systems of record. Skip when a static RAG corpus answers the need.

Practical notes

Operational checklist: document every tool's side effects, owner, and data classes (public, internal, confidential). Add integration tests that run against sandboxes, not production mailboxes. When a provider API changes, your tool adapter should be the only file that breaks. Prefer returning concise summaries to the model and keep raw payloads in your logs for audit. If you offer MCP and direct tools, ensure both paths enforce the same authorisation middleware. Product copy should tell users which third parties they connect and how to revoke access. This page pairs with Gmail and Google Integration for AI Agents for a concrete mail design and Permissions and Security for AI Integrations for the security bar. Work through one real request end to end, write down the failure modes you observed, and add a regression test so the next change does not silently drop validation, auth, or logging. Prefer boring, reviewable code over a clever abstraction until the second or third product needs the same pattern. Work through one real request end to end, write down the failure modes you observed, and add a regression test so the next change does not silently drop validation, auth, or logging. Prefer boring, reviewable code over a clever abstraction until the second or third product needs the same pattern.

Common mistakes

  • Giving the model a generic "run HTTP" tool.
  • Shipping client secrets to the browser.
  • Trusting email text as instructions.
  • Believing GoVibeTool or the base model includes a Gmail connector — you must build or host one (Gmail and Google Integration for AI Agents).