OpenAI Agents SDK

Build an OpenAI Agents SDK agent that reads Gmail as the user with AgentKit: turn Scalekit tools into function tools, or connect a Virtual MCP server.

Build an agent with the OpenAI Agents SDK that reads a user’s Gmail inbox. Each Scalekit tool becomes an Agents SDK function tool that runs the call through Scalekit as the user, and the SDK’s runner handles the tool-calling loop.

Calling the Chat Completions or Responses API directly instead? See OpenAI.

Before you start

Create a Gmail connection in AgentKit > Connections. The samples use the connection name gmail, so change it if yours differs. See Set up a connection.
Have the .env file from the Quickstart, and add your OpenAI API key as OPENAI_API_KEY to it.
The samples load .env with load_dotenv() from python-dotenv in Python, and import 'dotenv/config' in Node.js.

pip install scalekit-sdk-python python-dotenv openai-agents

npm install @scalekit-sdk/node dotenv @openai/agents

For Node.js, save the code in a .mts file, such as agent.mts, and run it with npx tsx agent.mts. The .mts extension makes the file an ES module, so it can use top-level await.

Initialize

Python
Node.js

import os
from dotenv import load_dotenv
from scalekit import ScalekitClient

load_dotenv()

scalekit_client = ScalekitClient(
    client_id=os.getenv("SCALEKIT_CLIENT_ID"),
    client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
    env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
)
actions = scalekit_client.actions

import 'dotenv/config';
import { ScalekitClient } from '@scalekit-sdk/node';

const scalekit = new ScalekitClient(
  process.env.SCALEKIT_ENVIRONMENT_URL!,
  process.env.SCALEKIT_CLIENT_ID!,
  process.env.SCALEKIT_CLIENT_SECRET!,
);

Later blocks reuse this setup.

Connect the user to Gmail

Python
Node.js

1
# Connect the user's Gmail account, and wait until it's ACTIVE before calling tools
2
connection_name = "gmail"
3
identifier = "user_123"  # your app's unique user ID
4

5
response = actions.get_or_create_connected_account(
6
    connection_name=connection_name, identifier=identifier
7
)
8
if response.connected_account.status != "ACTIVE":
9
    link = actions.get_authorization_link(
10
        connection_name=connection_name, identifier=identifier
11
    )
12
    print("Authorize Gmail:", link.link)
13
    input("Press Enter after authorizing...")
14
    # Fetch the account again to pick up the new status
15
    response = actions.get_or_create_connected_account(
16
        connection_name=connection_name, identifier=identifier
17
    )
18

19
if response.connected_account.status != "ACTIVE":
20
    raise RuntimeError(
21
        f"Gmail is {response.connected_account.status}, not ACTIVE. Authorize it and run again."
22
    )

1
import { createInterface } from 'node:readline/promises';
2
import { ConnectorStatus } from '@scalekit-sdk/node';
3

4
// Connect the user's Gmail account, and wait until it's ACTIVE before calling tools
5
const connectionName = 'gmail';
6
const identifier = 'user_123'; // your app's unique user ID
7

8
let { connectedAccount } = await scalekit.actions.getOrCreateConnectedAccount({
9
  connectionName,
10
  identifier,
11
});
12
if (connectedAccount?.status !== ConnectorStatus.ACTIVE) {
13
  const { link } = await scalekit.actions.getAuthorizationLink({ connectionName, identifier });
14
  console.log('Authorize Gmail:', link);
15
  const rl = createInterface({ input: process.stdin, output: process.stdout });
16
  await rl.question('Press Enter after authorizing...');
17
  rl.close();
18
  // Fetch the account again to pick up the new status
19
  ({ connectedAccount } = await scalekit.actions.getOrCreateConnectedAccount({
20
    connectionName,
21
    identifier,
22
  }));
23
}
24

25
if (connectedAccount?.status !== ConnectorStatus.ACTIVE) {
26
  throw new Error(`Gmail is not ACTIVE (status ${connectedAccount?.status}). Authorize it and run again.`);
27
}

See Authorize a user for production auth handling.

Run the agent

Fetch the tools scoped to this user and turn each one into a function tool. The tool’s JSON Schema is passed through as is, with strict mode off. When the model calls a tool, the function runs it with execute_tool (executeTool in Node.js) for this user and returns the app’s response. Use built-in tools explains the scoped tool list, paging past 100 tools, and how to read data when the app returns an error.

Python
Node.js

1
import asyncio
2
import json
3

4
from agents import Agent, FunctionTool, Runner
5
from google.protobuf.json_format import MessageToDict
6

7
scoped_response, _ = actions.tools.list_scoped_tools(
8
    identifier=identifier,
9
    filter={"connection_names": [connection_name]},
10
    page_size=100,  # up to 100 tools per page; page with next_page_token for more
11
)
12
definitions = [MessageToDict(t.tool).get("definition", {}) for t in scoped_response.tools]
13

14

15
def scalekit_tool(definition):
16
    async def run_tool(ctx, args_json: str) -> str:
17
        # execute_tool is a blocking call, so run it off the event loop
18
        result = await asyncio.to_thread(
19
            actions.execute_tool,
20
            tool_name=definition["name"],
21
            identifier=identifier,
22
            connection_name=connection_name,
23
            tool_input=json.loads(args_json or "{}"),
24
        )
25
        return json.dumps(result.data)
26

27
    return FunctionTool(
28
        name=definition["name"],
29
        description=definition.get("description", ""),
30
        params_json_schema=definition.get("input_schema", {"type": "object", "properties": {}}),
31
        on_invoke_tool=run_tool,
32
        strict_json_schema=False,  # Scalekit schemas don't follow strict mode's rules
33
    )
34

35

36
agent = Agent(
37
    name="Gmail assistant",
38
    instructions="Answer questions about the user's Gmail inbox.",
39
    model="gpt-4o",
40
    tools=[scalekit_tool(definition) for definition in definitions],
41
)
42
result = Runner.run_sync(agent, "Fetch my last 5 unread emails and summarize them")
43
print(result.final_output)

1
import { Agent, run, tool } from '@openai/agents';
2

3
const { tools: scopedTools } = await scalekit.tools.listScopedTools(identifier, {
4
  filter: { connectionNames: [connectionName] },
5
  pageSize: 100, // up to 100 tools per page; page with nextPageToken for more
6
});
7
// Tool definitions are typed as generic JSON, so read each field explicitly
8
const definitions = scopedTools.flatMap((t) => (t.tool?.definition ? [t.tool.definition] : []));
9
const tools = definitions.map((definition) =>
10
  tool({
11
    name: String(definition.name),
12
    description: String(definition.description ?? ''),
13
    parameters: definition.input_schema as any,
14
    strict: false, // Scalekit schemas don't follow strict mode's rules
15
    execute: async (input) => {
16
      const result = await scalekit.actions.executeTool({
17
        toolName: String(definition.name),
18
        identifier,
19
        connector: connectionName,
20
        toolInput: input as Record<string, unknown>,
21
      });
22
      return JSON.stringify(result.data);
23
    },
24
  }),
25
);
26

27
const agent = new Agent({
28
  name: 'Gmail assistant',
29
  instructions: "Answer questions about the user's Gmail inbox.",
30
  model: 'gpt-4o',
31
  tools,
32
});
33
const result = await run(agent, 'Fetch my last 5 unread emails and summarize them');
34
console.log(result.finalOutput);

If a tool function raises an error, the Agents SDK tells the model the call failed, so the model can retry or explain the failure. When the app itself rejects a request, execute_tool doesn’t raise: the app’s error response comes back in data, and the model reads it like any other result.

Check it worked

The script prints a summary of the user’s unread emails. To see each tool call and the Gmail response it returned, read result.new_items (result.newItems in Node.js).

Use MCP instead

The Agents SDK connects to MCP servers natively. Point it at a Virtual MCP server with a session token for this user, and the agent discovers the server’s tools on its own. Add this below the code above. It reuses the setup and, in Node.js, the Agent and run imports.

Python
Node.js

1
import asyncio
2
import os
3
from datetime import timedelta
4

5
from agents import Agent, Runner
6
from agents.mcp import MCPServerStreamableHttp
7

8
# Returned by create_config when you created the Virtual MCP server
9
config_id = os.environ["SCALEKIT_MCP_CONFIG_ID"]
10
mcp_url = os.environ["SCALEKIT_MCP_SERVER_URL"]
11

12
# Mint a fresh session token for this user before each agent run
13
mcp_token = actions.mcp.create_session_token(
14
    mcp_config_id=config_id,
15
    identifier=identifier,
16
    expiry=timedelta(hours=1),
17
).token
18

19

20
async def run():
21
    async with MCPServerStreamableHttp(
22
        name="scalekit",
23
        params={"url": mcp_url, "headers": {"Authorization": f"Bearer {mcp_token}"}},
24
    ) as server:
25
        agent = Agent(
26
            name="Gmail assistant",
27
            instructions="Answer questions about the user's Gmail inbox.",
28
            model="gpt-4o",
29
            mcp_servers=[server],
30
        )
31
        result = await Runner.run(agent, "Fetch my last 5 unread emails and summarize them")
32
        print(result.final_output)
33

34

35
asyncio.run(run())

1
import { MCPServerStreamableHttp } from '@openai/agents';
2

3
// Returned by createConfig when you created the Virtual MCP server
4
const configId = process.env.SCALEKIT_MCP_CONFIG_ID!;
5
const mcpUrl = process.env.SCALEKIT_MCP_SERVER_URL!;
6

7
// Mint a fresh session token for this user before each agent run
8
const session = await scalekit.actions.mcp.createSessionToken({
9
  mcpConfigId: configId,
10
  identifier,
11
  expirySeconds: 60 * 60,
12
});
13

14
const mcpServer = new MCPServerStreamableHttp({
15
  name: 'scalekit',
16
  url: mcpUrl,
17
  requestInit: { headers: { Authorization: `Bearer ${session.token}` } },
18
});
19
await mcpServer.connect();
20
try {
21
  const mcpAgent = new Agent({
22
    name: 'Gmail assistant',
23
    instructions: "Answer questions about the user's Gmail inbox.",
24
    model: 'gpt-4o',
25
    mcpServers: [mcpServer],
26
  });
27
  const mcpResult = await run(mcpAgent, 'Fetch my last 5 unread emails and summarize them');
28
  console.log(mcpResult.finalOutput);
29
} finally {
30
  await mcpServer.close();
31
}

See Create a Virtual MCP server and Mint session tokens to create the server, check the user’s connections and mint a token.

Manage connected accountsCheck an account's status and ask users to reconnect.

AgentKit launch checklistEverything to finish before real users connect.

API reference

The endpoints this page's code calls, with every field and the SDK method for each: