Handle two-factor authentication

Sites that protect a login with email codes, SMS codes, or confirmation links send a value the agent cannot invent. The SDKs ship a prebuilt custom tool for that moment: the agent calls request_otp, your process resolves the code or link, and the run continues with the single value. Pass otp_tool / otpTool in tools the same way you would any other custom tool. Pick the handler that matches where the code arrives:

Where the code arrives	Use	Best for
Anywhere, you are at the keyboard	Interactive prompt	Local runs and debugging
An inbox you control	IMAP handler	Unattended runs
Slack, SMS provider, any other source	Custom handler	Anything your code can reach
An authenticator app with the secret in 1Password	Vault	TOTP without exposing the secret

Prompt interactively

The default handler is enough for local runs: when the agent hits a 2FA step, your terminal asks for the code or link.

from hai_agents import Client
from hai_agents_tools import otp_tool

client = Client()
result = client.run_session(
    agent="h/web-surfer-flash",
    messages="Log in to example.com and summarize the inbox.",
    tools=[otp_tool()],
)
print(result.answer)

import { HaiAgentsClient, otpTool } from "hai-agents";

const client = new HaiAgentsClient();
const result = await client.runSession({
  agent: "h/web-surfer-flash",
  messages: "Log in to example.com and summarize the inbox.",
  tools: [otpTool()],
});
console.log(result.answer);

Read the code from email

For unattended runs, hand the tool an IMAP handler. It polls unread mail (newest first), extracts a code or confirmation link, marks that message read so a retry cannot reuse a stale code, and returns only that value to the agent. For Gmail or Google Workspace, use an app password.

import os

from hai_agents import Client
from hai_agents_tools import imap_otp_handler, otp_tool

handler = imap_otp_handler(
    host="imap.gmail.com",
    username="agent-inbox@gmail.com",
    password=os.environ["GMAIL_APP_PASSWORD"],
    sender="no-reply@example.com",  # optional: only mail from this address
)

client = Client()
result = client.run_session(
    agent="h/web-surfer-flash",
    messages="Log in to example.com and check for new notifications.",
    tools=[otp_tool(handler)],
)
print(result.answer)

import { HaiAgentsClient, imapOtpHandler, otpTool } from "hai-agents";

// Optional deps for the IMAP handler: npm install imapflow mailparser
const handler = imapOtpHandler({
  host: "imap.gmail.com",
  username: "agent-inbox@gmail.com",
  password: process.env.GMAIL_APP_PASSWORD!,
  sender: "no-reply@example.com", // optional: only mail from this address
});

const client = new HaiAgentsClient();
const result = await client.runSession({
  agent: "h/web-surfer-flash",
  messages: "Log in to example.com and check for new notifications.",
  tools: [otpTool({ handler })],
});
console.log(result.answer);

Like every custom tool, the handler runs in your process: IMAP credentials never leave your machine, and the agent only receives the extracted code or link. It never sees mailbox contents, subjects, or senders. Useful IMAP options:

Option	Default	Role
`sender`	unset	Only consider messages from this address
`timeout_s` / `timeoutMs`	2 minutes	Give up (tool error to the agent) after this long
`max_age_s` / `maxAgeMs`	15 minutes	Ignore unread mail older than this
`code_pattern` / `codePattern`	built-in heuristics	Override extraction. First capture group (or the whole match) is the code

Supply a custom handler

Any function that takes the agent’s request and returns a string works: prompt in Slack, call an inbox API, read SMS from a provider, and so on. Handlers may be sync or async.

from hai_agents_tools import OtpRequest, otp_tool

def from_slack(request: OtpRequest) -> str:
    # request.prompt, request.kind ("code" | "link"), request.source
    return slack.ask_user(request.prompt)

tools = [otp_tool(from_slack)]

import { otpTool, type OtpRequest } from "hai-agents";

async function fromSlack(request: OtpRequest): Promise<string> {
  // request.prompt, request.kind ("code" | "link"), request.source
  return slack.askUser(request.prompt);
}

const tools = [otpTool({ handler: fromSlack })];

What the agent sends

The tool’s input schema is fixed. The agent fills:

Field	Required	Meaning
`prompt`	yes	Human-readable ask, e.g. “Enter the 6-digit code sent to j***@example.com”
`kind`	no	`"code"` (default) or `"link"` for a full confirmation URL
`source`	no	Where it was sent, e.g. `"email"`, `"sms"`, `"authenticator app"`

Your handler should return a non-empty string. Empty values fail as a tool error so the agent can retry or stop cleanly.

Authenticator apps via a vault

If the site uses a TOTP authenticator and the secret already lives in 1Password, bind a vault to the browser instead. When the page matches a stored item, the session offers fill_secret_at with totp and injects the code without putting it in the agent’s context.

	`otp_tool`	Vault
Code arrives	Out of band: email, SMS, magic link	Generated from a TOTP secret
Who resolves it	Your handler, in your process	The session, from 1Password
Agent sees	The single code or link	Nothing

Get started

Concepts

Browser

Desktop

Integrations

Guides

Operate

Handle two-factor authentication

Prompt interactively

Read the code from email

Supply a custom handler

What the agent sends

Authenticator apps via a vault

Next steps

Vaults

Custom tools

​Prompt interactively

​Read the code from email

​Supply a custom handler

​What the agent sends

​Authenticator apps via a vault

​Next steps

Vaults

Custom tools

Prompt interactively

Read the code from email

Supply a custom handler

What the agent sends

Authenticator apps via a vault

Next steps