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:
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 anOtpRequest:
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 offersfill_secret_at with totp and injects the code without putting it in the agent’s context.