Skip to main content
Email codes, SMS codes, and confirmation links are values the agent can’t invent. The SDKs ship a built-in custom tool for that moment: the agent calls request_otp, your process resolves the code or link, and the run continues with that single value. Pass otp_tool / otpTool in tools with the handler that matches where the code arrives:
Python ships the tool in the hai_agents_tools module of the hai-agents package. TypeScript exports it from hai-agents.

Read the code from email

The IMAP handler polls unread mail (newest first), extracts a code or confirmation link, marks that message read so a retry can’t reuse a stale code, and returns only that value. For Gmail or Google Workspace, use an app password. It runs in your process: IMAP credentials never leave your machine, and the agent never sees mailbox contents, subjects, or senders.

What the agent sends

The tool’s input schema is fixed. Your handler receives it as an OtpRequest: Return a non-empty string. An empty value fails 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 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.