Build a daily briefing agent with Vercel AI SDK and Scalekit Agent Auth

Connect a TypeScript or Python agent via Vercel AI SDK and Scalekit Agent Auth to Google Calendar and Gmail using two integration patterns.

A daily briefing agent needs two things: today’s calendar events and the latest unread emails. Both live behind OAuth-protected APIs, and each requires its own token, its own authorization flow, and its own refresh logic. Before you write any scheduling logic, you’re already maintaining two parallel token lifecycles.

Scalekit eliminates that overhead. It stores one OAuth session per connector per user, handles token refresh automatically, and gives you a single API surface regardless of which provider you’re talking to. This recipe shows how to use it with Google Calendar and Gmail — and demonstrates two patterns for consuming those credentials in your agent.

What this recipe covers:

OAuth token pattern — Scalekit provides a valid token; your agent calls the Google Calendar REST API directly. Use this when you need full control over the request.
Built-in action pattern — Your agent calls execute_tool("gmail_fetch_mails"); Scalekit executes the Gmail API call and returns structured data. Use this when you want speed and don’t need to customize the request.

The complete source used here is available in the vercel-ai-agent-toolkit repository, with a TypeScript implementation using the Vercel AI SDK and a Python implementation using the Anthropic SDK directly.

1. Set up connections in Scalekit

In the Scalekit Dashboard, create two connections under Agent Auth → Connections:

googlecalendar — Google Calendar OAuth connection
gmail — Gmail OAuth connection

The connection names are identifiers your code references directly. They must match exactly.

1
cd typescript
2
pnpm install

The typescript/package.json includes:

1
{
2
  "dependencies": {
3
    "ai": "^4.3.15",
4
    "@ai-sdk/anthropic": "^1.2.12",
5
    "@scalekit-sdk/node": "2.2.0-beta.1",
6
    "zod": "^3.0.0",
7
    "dotenv": "^16.0.0"
8
  }
9
}

1
cd python
2
uv venv .venv
3
uv pip install -r requirements.txt

The python/requirements.txt includes:

1
scalekit-sdk-python
2
anthropic
3
requests
4
python-dotenv

3. Configure credentials

Copy the example env file and fill in your credentials:

1
cp typescript/.env.example typescript/.env   # TypeScript
2
cp typescript/.env.example python/.env       # Python (same variables)

1
SCALEKIT_ENV_URL=https://your-env.scalekit.dev
2
SCALEKIT_CLIENT_ID=skc_...
3
SCALEKIT_CLIENT_SECRET=your-secret
4

5
ANTHROPIC_API_KEY=sk-ant-...

Get your Scalekit credentials at app.scalekit.com → Settings → API Credentials.

4. Initialize the Scalekit client

TypeScript
Python

1
import { ScalekitClient } from '@scalekit-sdk/node';
2
import { ConnectorStatus } from '@scalekit-sdk/node/lib/pkg/grpc/scalekit/v1/connected_accounts/connected_accounts_pb.js';
3
import 'dotenv/config';
4

5
// Never hard-code credentials — they would be exposed in source control.
6
// Pull them from environment variables at runtime.
7
const scalekit = new ScalekitClient(
8
  process.env.SCALEKIT_ENV_URL!,
9
  process.env.SCALEKIT_CLIENT_ID!,
10
  process.env.SCALEKIT_CLIENT_SECRET!,
11
);
12

13
const USER_ID = 'user_123'; // Replace with the real user ID from your session

ConnectorStatus is imported from the SDK’s generated protobuf file. Compare connectedAccount.status against ConnectorStatus.ACTIVE rather than the string 'ACTIVE' — TypeScript’s type system enforces this.

1
import os
2
import json
3
import requests
4
from datetime import datetime, timezone
5
from dotenv import load_dotenv
6
import anthropic
7
import scalekit.client
8

9
load_dotenv()
10

11
# Never hard-code credentials — they would be exposed in source control.
12
# Pull them from environment variables at runtime.
13
scalekit_client = scalekit.client.ScalekitClient(
14
    client_id=os.environ["SCALEKIT_CLIENT_ID"],
15
    client_secret=os.environ["SCALEKIT_CLIENT_SECRET"],
16
    env_url=os.environ["SCALEKIT_ENV_URL"],
17
)
18
actions = scalekit_client.actions
19

20
USER_ID = "user_123"  # Replace with the real user ID from your session

scalekit_client.actions is the entry point for all connected-account operations: creating accounts, generating auth links, fetching tokens, and executing built-in tools.

5. Ensure each connector is authorized

Before calling any API, check whether the user has an active connected account. If not, print an authorization link and wait for them to complete the browser OAuth flow.

TypeScript
Python

1
async function ensureConnected(connector: string) {
2
  const { connectedAccount } =
3
    await scalekit.connectedAccounts.getOrCreateConnectedAccount({
4
      connector,
5
      identifier: USER_ID,
6
    });
7

8
  if (connectedAccount?.status !== ConnectorStatus.ACTIVE) {
9
    const { link } =
10
      await scalekit.connectedAccounts.getMagicLinkForConnectedAccount({
11
        connector,
12
        identifier: USER_ID,
13
      });
14
    console.log(`\n[${connector}] Authorization required.`);
15
    console.log(`Open this link:\n\n  ${link}\n`);
16
    console.log('Press Enter once you have completed the OAuth flow...');
17
    await new Promise<void>(resolve => {
18
      process.stdin.resume();
19
      process.stdin.once('data', () => { process.stdin.pause(); resolve(); });
20
    });
21
  }
22

23
  return connectedAccount;
24
}

1
def ensure_connected(connector: str):
2
    response = actions.get_or_create_connected_account(
3
        connection_name=connector,
4
        identifier=USER_ID,
5
    )
6
    connected_account = response.connected_account
7

8
    if connected_account.status != "ACTIVE":
9
        link_response = actions.get_authorization_link(
10
            connection_name=connector,
11
            identifier=USER_ID,
12
        )
13
        print(f"\n[{connector}] Authorization required.")
14
        print(f"Open this link:\n\n  {link_response.link}\n")
15
        input("Press Enter once you have completed the OAuth flow...")
16

17
    return connected_account

After the first successful authorization, getOrCreateConnectedAccount / get_or_create_connected_account returns an active account on all subsequent calls. Scalekit refreshes expired tokens automatically — your code never calls a token-refresh endpoint.

6. Fetch calendar events using the OAuth token pattern

For Google Calendar, retrieve a valid access token from Scalekit and call the Google Calendar REST API directly. This pattern gives you full control over query parameters, pagination, and error handling.

TypeScript
Python

1
async function getAccessToken(connector: string): Promise<string> {
2
  const response =
3
    await scalekit.connectedAccounts.getConnectedAccountByIdentifier({
4
      connector,
5
      identifier: USER_ID,
6
    });
7
  const details = response?.connectedAccount?.authorizationDetails?.details;
8
  if (details?.case === 'oauthToken' && details.value?.accessToken) {
9
    return details.value.accessToken;
10
  }
11
  throw new Error(`No access token found for ${connector}`);
12
}

Use this token in a tool that the LLM can call:

1
import { tool } from 'ai';
2
import { z } from 'zod';
3

4
const today = new Date();
5
const timeMin = new Date(today.getFullYear(), today.getMonth(), today.getDate()).toISOString();
6
const timeMax = new Date(today.getFullYear(), today.getMonth(), today.getDate(), 23, 59, 59).toISOString();
7

8
const calendarToken = await getAccessToken('googlecalendar');
9

10
const getCalendarEvents = tool({
11
  description: "Fetch today's events from Google Calendar",
12
  parameters: z.object({
13
    maxResults: z.number().optional().default(5),
14
  }),
15
  execute: async ({ maxResults }) => {
16
    const url = new URL('https://www.googleapis.com/calendar/v3/calendars/primary/events');
17
    url.searchParams.set('timeMin', timeMin);
18
    url.searchParams.set('timeMax', timeMax);
19
    url.searchParams.set('maxResults', String(maxResults));
20
    url.searchParams.set('orderBy', 'startTime');
21
    url.searchParams.set('singleEvents', 'true');
22

23
    const res = await fetch(url.toString(), {
24
      headers: { Authorization: `Bearer ${calendarToken}` },
25
    });
26
    if (!res.ok) throw new Error(`Calendar API error: ${res.status}`);
27
    const data = await res.json() as { items?: unknown[] };
28
    return data.items ?? [];
29
  },
30
});

1
def get_access_token(connector: str) -> str:
2
    # get_connected_account always returns a fresh token —
3
    # Scalekit refreshes expired tokens before returning.
4
    response = actions.get_connected_account(
5
        connection_name=connector,
6
        identifier=USER_ID,
7
    )
8
    tokens = response.connected_account.authorization_details["oauth_token"]
9
    return tokens["access_token"]
10

11
def fetch_calendar_events(access_token: str, max_results: int = 5) -> list:
12
    today = datetime.now(timezone.utc).astimezone()
13
    time_min = today.replace(hour=0, minute=0, second=0, microsecond=0).isoformat()
14
    time_max = today.replace(hour=23, minute=59, second=59, microsecond=0).isoformat()
15

16
    resp = requests.get(
17
        "https://www.googleapis.com/calendar/v3/calendars/primary/events",
18
        headers={"Authorization": f"Bearer {access_token}"},
19
        params={
20
            "timeMin": time_min,
21
            "timeMax": time_max,
22
            "maxResults": max_results,
23
            "orderBy": "startTime",
24
            "singleEvents": "true",
25
        },
26
    )
27
    resp.raise_for_status()
28
    return resp.json().get("items", [])

7. Fetch emails using the built-in action pattern

For Gmail, call execute_tool with the built-in gmail_fetch_mails action. Scalekit executes the Gmail API call using the stored token and returns structured data. You don’t need to build the request, handle the token, or parse the response format.

TypeScript
Python

1
const getUnreadEmails = tool({
2
  description: 'Fetch top unread emails from Gmail via Scalekit actions',
3
  parameters: z.object({
4
    maxResults: z.number().optional().default(5),
5
  }),
6
  execute: async ({ maxResults }) => {
7
    const response = await scalekit.tools.executeTool({
8
      toolName: 'gmail_fetch_mails',
9
      connectedAccountId: gmailAccount?.id,
10
      params: {
11
        query: 'is:unread',
12
        max_results: maxResults,
13
      },
14
    });
15
    return response.data?.toJson() ?? {};
16
  },
17
});

1
def fetch_unread_emails(connected_account_id: str, max_results: int = 5) -> dict:
2
    response = actions.execute_tool(
3
        tool_name="gmail_fetch_mails",
4
        connected_account_id=connected_account_id,
5
        tool_input={
6
            "query": "is:unread",
7
            "max_results": max_results,
8
        },
9
    )
10
    return response.result

The built-in action pattern trades flexibility for brevity. You can’t customize headers or pagination, but you also don’t need to read Gmail API documentation — the tool parameters are consistent across all Scalekit connectors. See all supported agent connectors for the full list of built-in tools.

8. Wire the agent together

Pass both tools to the LLM and ask for a daily summary.

TypeScript
Python

The TypeScript version uses the Vercel AI SDK’s generateText with maxSteps to allow the LLM to call multiple tools in sequence before producing the final response.

1
import { generateText } from 'ai';
2
import { anthropic } from '@ai-sdk/anthropic';
3

4
const [calendarAccount, gmailAccount] = await Promise.all([
5
  ensureConnected('googlecalendar'),
6
  ensureConnected('gmail'),
7
]);
8

9
const calendarToken = await getAccessToken('googlecalendar');
10

11
const { text } = await generateText({
12
  model: anthropic('claude-sonnet-4-6'),
13
  prompt: `Give me a summary of my day for ${today.toDateString()}: list today's calendar events and my top 5 unread emails.`,
14
  tools: {
15
    getCalendarEvents,
16
    getUnreadEmails,
17
  },
18
  maxSteps: 5, // allow the LLM to call multiple tools before responding
19
});
20

21
console.log(text);

maxSteps controls how many tool-call rounds the LLM can make before it must return a final text response. Without it, generateText stops after the first tool call.

The Python version uses the Anthropic SDK directly with a manual agentic loop. The loop continues until the model returns stop_reason == "end_turn" with no pending tool calls.

1
def run_agent():
2
    gmail_account = ensure_connected("gmail")
3
    ensure_connected("googlecalendar")
4
    calendar_token = get_access_token("googlecalendar")
5

6
    client = anthropic.Anthropic()
7
    today = datetime.now().strftime("%A, %B %d, %Y")
8

9
    tools = [
10
        {
11
            "name": "get_calendar_events",
12
            "description": "Fetch today's events from Google Calendar",
13
            "input_schema": {
14
                "type": "object",
15
                "properties": {"max_results": {"type": "integer", "default": 5}},
16
            },
17
        },
18
        {
19
            "name": "get_unread_emails",
20
            "description": "Fetch top unread emails from Gmail via Scalekit actions",
21
            "input_schema": {
22
                "type": "object",
23
                "properties": {"max_results": {"type": "integer", "default": 5}},
24
            },
25
        },
26
    ]
27

28
    messages = [
29
        {
30
            "role": "user",
31
            "content": f"Give me a summary of my day for {today}: list today's calendar events and my top 5 unread emails.",
32
        }
33
    ]
34

35
    while True:
36
        response = client.messages.create(
37
            model="claude-sonnet-4-6",
38
            max_tokens=1024,
39
            tools=tools,
40
            messages=messages,
41
        )
42
        messages.append({"role": "assistant", "content": response.content})
43

44
        if response.stop_reason == "end_turn":
45
            for block in response.content:
46
                if hasattr(block, "text"):
47
                    print(block.text)
48
            break
49

50
        tool_results = []
51
        for block in response.content:
52
            if block.type == "tool_use":
53
                max_results = block.input.get("max_results", 5)
54
                if block.name == "get_calendar_events":
55
                    result = fetch_calendar_events(calendar_token, max_results)
56
                elif block.name == "get_unread_emails":
57
                    result = fetch_unread_emails(gmail_account.id, max_results)
58
                else:
59
                    result = {"error": f"Unknown tool: {block.name}"}
60
                tool_results.append({
61
                    "type": "tool_result",
62
                    "tool_use_id": block.id,
63
                    "content": json.dumps(result),
64
                })
65

66
        if tool_results:
67
            messages.append({"role": "user", "content": tool_results})
68
        else:
69
            break
70

71
if __name__ == "__main__":
72
    run_agent()

9. Testing

Run the agent:

TypeScript
Python

1
cd typescript && pnpm start

1
cd python && .venv/bin/python index.py

On first run, you see two authorization prompts in sequence:

1
[googlecalendar] Authorization required.
2
Open this link:
3

4
  https://auth.scalekit.dev/connect/...
5

6
Press Enter once you have completed the OAuth flow...
7

8
[gmail] Authorization required.
9
Open this link:
10

11
  https://auth.scalekit.dev/connect/...
12

13
Press Enter once you have completed the OAuth flow...

After both connectors are authorized, the agent fetches your data and returns a summary:

1
Here's your day for Friday, March 27, 2026:
2

3
📅 Calendar — 3 events today
4
• 9:00 AM  Team standup (30 min)
5
• 1:00 PM  Product review
6
• 4:00 PM  1:1 with manager
7

8
📧 Unread emails — top 5
9
• "Q1 roadmap feedback needed" — Sarah Chen, 1h ago
10
• "Deploy failed: production" — GitHub Actions, 2h ago
11
• "New PR review requested" — Lin Feng, 3h ago
12
...

On subsequent runs, both authorization prompts are skipped. Scalekit returns the active session directly.

Common mistakes

Connection name mismatch

Symptom: getOrCreateConnectedAccount returns an error for googlecalendar or gmail
Cause: The connection name in the Scalekit Dashboard does not match the literal string in your code
Fix: Make the dashboard connection name match your code exactly, for example googlecalendar instead of google-calendar

TypeScript status compared to a string

Symptom: TypeScript raises TS2367 for connectedAccount?.status !== 'ACTIVE'
Cause: The SDK returns a ConnectorStatus enum, not a string literal
Fix: Import ConnectorStatus from the SDK’s generated protobuf file and compare against ConnectorStatus.ACTIVE

Python naive datetimes in API calls

Symptom: Google Calendar returns a 400 error for your event query
Cause: A naive datetime produces an ISO string without timezone information
Fix: Use datetime.now(timezone.utc) and call .astimezone() so the generated timestamps are timezone-aware

maxSteps missing in the Vercel AI SDK

Symptom: generateText stops after the first tool call instead of returning a final summary
Cause: The model is not allowed to make enough tool-call rounds
Fix: Set maxSteps to at least 3, and increase it if your workflow needs more than one tool call plus a final response

toolInput used instead of params

Symptom: executeTool succeeds but the Gmail tool receives no parameters
Cause: @scalekit-sdk/node expects a params field, not toolInput
Fix: Pass tool arguments in params, for example { query: 'is:unread', max_results: 5 }

Production notes

User ID from session — Both implementations hardcode USER_ID = "user_123". In production, replace this with the real user identifier from your application’s session. A mismatch means Scalekit looks up the wrong user’s tokens.

Token freshness — getConnectedAccountByIdentifier (TypeScript) and get_connected_account (Python) always return a fresh token — Scalekit refreshes it before returning if it has expired. You do not need to track expiry or call a refresh endpoint.

First-run blocking — The authorization prompt blocks the process until the user completes OAuth in the browser. In a web application, redirect the user to link instead of printing it, and handle the callback before proceeding.

execute_tool response shape — In Python, response.result is a dictionary whose structure depends on the tool. In TypeScript, response.data?.toJson() converts the protobuf response to a plain object. Log the raw response on first use to understand the shape before passing it to the LLM.

Rate limits — The Google Calendar API and Gmail API both have per-user daily quotas. If your agent runs frequently, add exponential backoff around the API calls and cache calendar events across requests where freshness allows.

Next steps

Add more connectors — The same ensureConnected pattern works for any Scalekit-supported connector. Swap the connector name and replace the Google API calls with the target service’s API. See all supported connectors.
Use the built-in Calendar action — Scalekit also provides a googlecalendar_list_events built-in action. If you don’t need custom query parameters, switch the Calendar tool to execute_tool and remove the getAccessToken call entirely.
Stream the response — Replace generateText with streamText in the Vercel AI SDK to stream the LLM’s summary token-by-token instead of waiting for the full response.
Handle re-authorization — If a user revokes access, getOrCreateConnectedAccount returns an inactive account. Add a re-authorization path to recover gracefully instead of crashing.
Review the agent auth quickstart — For a broader overview of the connected-accounts model and supported providers, see the agent auth quickstart.