Skip to main content
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. Without a handler it prompts on stdin; with a handler you can read an inbox over IMAP or fetch the value from anywhere else your code can reach.

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.

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.
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 — never mailbox contents, subjects, or senders. Useful IMAP options:

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.

What the agent sends

The tool’s input schema is fixed. The agent fills: 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. Reach for otp_tool when the code arrives out of band (email, SMS, magic link); reach for a vault when the TOTP secret is already in your secrets provider.