runpod 2.2.0__tar.gz → 2.2.1__tar.gz

{runpod-2.2.0 → runpod-2.2.1}/CHANGELOG.md

@@ -22,6 +22,22 @@
 * Deployment artifacts apply project ignore rules and mandatory secret-file exclusions while preserving vendored dependency assets.
 * Synchronous calls wait across polling timeouts on Python 3.10 and propagate operation timeouts.
 
+## [2.2.1](https://github.com/runpod/runpod-python/compare/v2.2.0...v2.2.1) (2026-11-10)
+
+
+### Bug Fixes
+
+* **apps:** a `runpod` pin in `dependencies=[...]` silently produces a mixed install on workers ([#700](https://github.com/runpod/runpod-python/issues/700)) ([16a0280](https://github.com/runpod/runpod-python/commit/16a0280085f7d3fee2f75ba1aa946a50d34ac854))
+* **apps:** give new deployed endpoints unique template names ([#696](https://github.com/runpod/runpod-python/issues/696)) ([c930098](https://github.com/runpod/runpod-python/commit/c930098a02540e327a695a855b49026c73508c14))
+* **cli:** make agent login a two-step flow ([#711](https://github.com/runpod/runpod-python/issues/711)) ([cbf681b](https://github.com/runpod/runpod-python/commit/cbf681b3c5cd4b3a42964472fe19aa1c5f100221))
+* **endpoint:** Endpoint.run_sync drops the error of a FAILED job ([#699](https://github.com/runpod/runpod-python/issues/699)) ([05a77b3](https://github.com/runpod/runpod-python/commit/05a77b3370fec18f6ba2f6201dbd8b585ee22260))
+* **version:** report the imported tree's version ([#708](https://github.com/runpod/runpod-python/issues/708)) ([13dfbe5](https://github.com/runpod/runpod-python/commit/13dfbe57ad36fbe8cb53a2d788cab88951f437e9))
+
+
+### Documentation
+
+* **examples:** fix broken and stale examples under examples/ ([#694](https://github.com/runpod/runpod-python/issues/694)) ([18d5fee](https://github.com/runpod/runpod-python/commit/18d5fee7a0612f800decb00d57d05fe439ca2f2c))
+
 ## [2.2.0](https://github.com/runpod/runpod-python/compare/v2.1.0...v2.2.0) (2026-11-09)
 
 

{runpod-2.2.0/runpod.egg-info → runpod-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runpod
-Version: 2.2.0
+Version: 2.2.1
 Summary: 🐍 | Python library for Runpod API and serverless worker SDK.
 Home-page: https://runpod.io
 Author: Runpod
@@ -67,7 +67,7 @@ Dynamic: requires-python
 [![CI | Unit Tests](https://github.com/runpod/runpod-python/actions/workflows/CI-pytests.yml/badge.svg)](https://github.com/runpod/runpod-python/actions/workflows/CI-pytests.yml)
 [![License](https://img.shields.io/badge/License-MIT-blue)](LICENSE)
 
-[Documentation](https://docs.runpod.io) • [Examples](examples/apps) • [Discord](https://discord.gg/pJ3P2DbUUq)
+[Documentation](https://docs.runpod.io) • [Examples](examples) • [Discord](https://discord.gg/pJ3P2DbUUq)
 
 </div>
 

{runpod-2.2.0 → runpod-2.2.1}/README.md

@@ -9,7 +9,7 @@
 [![CI | Unit Tests](https://github.com/runpod/runpod-python/actions/workflows/CI-pytests.yml/badge.svg)](https://github.com/runpod/runpod-python/actions/workflows/CI-pytests.yml)
 [![License](https://img.shields.io/badge/License-MIT-blue)](LICENSE)
 
-[Documentation](https://docs.runpod.io) • [Examples](examples/apps) • [Discord](https://discord.gg/pJ3P2DbUUq)
+[Documentation](https://docs.runpod.io) • [Examples](examples) • [Discord](https://discord.gg/pJ3P2DbUUq)
 
 </div>
 

runpod-2.2.1/examples/README.md

@@ -0,0 +1,63 @@
+# Examples
+
+## Before you start
+
+```bash
+pip install runpod
+rp login
+```
+
+`rp login` stores your API key, and every example picks it up from there. If
+`RUNPOD_API_KEY` is set in your environment, the examples use that key
+instead.
+
+## Which folder to start with
+
+| Folder | What it shows | Needs |
+|---|---|---|
+| [`apps/`](apps) | Python functions that run on cloud GPUs and CPUs, started with `rp flash dev` | An account. Start here if you are new. |
+| [`serverless/`](serverless) | Handlers for your own serverless worker image | Nothing. They run locally. |
+| [`endpoints/`](endpoints) | Sending jobs to an existing serverless endpoint | An endpoint id |
+| [`api/`](api) | Creating templates, endpoints, and registry credentials | An account |
+| [`rest_wrapper.py`](rest_wrapper.py) | Pod lifecycle: create, stop, resume, terminate | An account. Creates a billable GPU pod. |
+
+## Running the serverless handlers locally
+
+```bash
+cd examples/serverless
+python simple_handler.py --test_input '{"input": {"name": "world"}}'
+```
+
+Or start a local API server and call it:
+
+```bash
+python simple_handler.py --rp_serve_api
+curl -X POST http://localhost:8000/runsync \
+  -H "Content-Type: application/json" \
+  -d '{"input": {"name": "world"}}'
+```
+
+Run with no arguments, a handler looks for a `test_input.json` file in the
+current directory.
+
+## Getting an endpoint id for `endpoints/`
+
+Each `endpoints/` example has a `YOUR_ENDPOINT_ID` placeholder. To use an
+endpoint you already have, list them with `rp endpoint list`. To create one
+for trying the examples, run [`api/create_endpoint.py`](api/create_endpoint.py),
+which deploys `runpod/mock-worker` and prints the new id.
+
+`endpoints/streaming.py` needs a worker that streams: a generator handler, or
+`runpod/mock-worker` started with `--generator`.
+
+## Cost and cleanup
+
+- Endpoints with `workers_min=0` cost nothing while idle. Delete them with
+  `rp endpoint delete ENDPOINT_ID`.
+- Templates stay on your account. Delete them from the Templates page in the
+  console.
+- `rest_wrapper.py` terminates its pod at the end, including when a step
+  fails.
+- `rp flash dev` deletes the endpoints it created when the session ends.
+  Network volumes created by `apps/` examples are not deleted; list them with
+  `rp volume list` and remove them with `rp volume delete`.

runpod-2.2.1/examples/api/create_container_registry_auth.py

@@ -0,0 +1,24 @@
+"""Example of creating a container registry auth with the Runpod API.
+
+Registry credentials let templates pull images from a private registry. The
+credential stays on your account after the script exits; delete it with
+`rp registry delete NAME`.
+"""
+
+import runpod
+
+# Run `rp login` once to store your API key, or uncomment the line below:
+# runpod.api_key = "YOUR_RUNPOD_API_KEY"
+
+try:
+    new_container_registry_auth = runpod.create_container_registry_auth(
+        name="example-registry-auth",
+        username="YOUR_REGISTRY_USERNAME",
+        password="YOUR_REGISTRY_PASSWORD",
+    )
+
+    print(new_container_registry_auth)
+
+except runpod.error.QueryError as err:
+    print(err)
+    print(err.query)

runpod-2.2.1/examples/api/create_endpoint.py

@@ -0,0 +1,44 @@
+"""Example of creating an endpoint with the Runpod API.
+
+The endpoint scales to zero workers when idle, so it costs nothing until it
+receives requests. It stays on your account after the script exits; delete it
+with `rp endpoint delete ENDPOINT_ID`, then delete its template from the
+Templates page in the console.
+"""
+
+import uuid
+
+import runpod
+
+# Run `rp login` once to store your API key, or uncomment the line below:
+# runpod.api_key = "YOUR_RUNPOD_API_KEY"
+
+# Template and endpoint names must be unique on your account.
+NAME = f"example-endpoint-{uuid.uuid4().hex[:8]}"
+
+try:
+
+    # runpod/mock-worker echoes its input back, which is enough to try the
+    # examples in examples/endpoints/.
+    new_template = runpod.create_template(
+        name=NAME, image_name="runpod/mock-worker:latest", is_serverless=True
+    )
+
+    print(new_template)
+
+    new_endpoint = runpod.create_endpoint(
+        name=NAME,
+        template_id=new_template["id"],
+        gpu_ids="AMPERE_16",
+        workers_min=0,
+        workers_max=1,
+        flashboot=True,
+    )
+
+    print(new_endpoint)
+    print(f"Endpoint id: {new_endpoint['id']}")
+    print(f"Delete it with: rp endpoint delete {new_endpoint['id']}")
+
+except runpod.error.QueryError as err:
+    print(err)
+    print(err.query)

runpod-2.2.1/examples/api/create_template.py

@@ -0,0 +1,27 @@
+"""Example of creating a template with the Runpod API.
+
+The template stays on your account after the script exits. Delete it from
+the Templates page in the console when you no longer need it.
+"""
+
+import uuid
+
+import runpod
+
+# Run `rp login` once to store your API key, or uncomment the line below:
+# runpod.api_key = "YOUR_RUNPOD_API_KEY"
+
+# Template names must be unique on your account.
+TEMPLATE_NAME = f"example-template-{uuid.uuid4().hex[:8]}"
+
+try:
+
+    new_template = runpod.create_template(
+        name=TEMPLATE_NAME, image_name="runpod/base:2.0.0-ubuntu2404"
+    )
+
+    print(new_template)
+
+except runpod.error.QueryError as err:
+    print(err)
+    print(err.query)

runpod-2.2.1/examples/api/get_endpoints.py

@@ -0,0 +1,13 @@
+"""Example of listing your serverless endpoints with the Runpod API."""
+
+import runpod
+
+# Run `rp login` once to store your API key, or uncomment the line below:
+# runpod.api_key = "YOUR_RUNPOD_API_KEY"
+
+endpoints = runpod.get_endpoints()
+
+# Each entry is the endpoint's full configuration, including its environment
+# variables, so print only the id and name here.
+for endpoint in endpoints:
+    print(endpoint["id"], endpoint.get("name"))

{runpod-2.2.0 → runpod-2.2.1}/examples/endpoints/asyncio_job_request.py

@@ -7,11 +7,10 @@ import asyncio
 import runpod
 from runpod import AsyncioEndpoint, AsyncioJob, http_client
 
-asyncio.set_event_loop_policy(
-    asyncio.WindowsSelectorEventLoopPolicy()
-)  # For Windows Users
+# Run `rp login` once to store your API key, or uncomment the line below:
+# runpod.api_key = "YOUR_RUNPOD_API_KEY"
 
-runpod.api_key = "YOUR_API_KEY"
+JOB_TIMEOUT = 120  # seconds
 
 
 async def main():
@@ -21,7 +20,7 @@ async def main():
     async with http_client.AsyncClientSession() as session:
         # Invoke API
         payload = {}
-        endpoint = AsyncioEndpoint("ENDPOINT_ID", session)
+        endpoint = AsyncioEndpoint("YOUR_ENDPOINT_ID", session)
         job: AsyncioJob = await endpoint.run(payload)
 
         # Get current job status
@@ -30,8 +29,9 @@ async def main():
         # Print status
         print(status)
 
-        # Wait until job is completed or failed
-        output = await job.output()
+        # Wait until the job completes or fails, up to JOB_TIMEOUT seconds.
+        # Raises TimeoutError if the job is still running after that.
+        output = await job.output(timeout=JOB_TIMEOUT)
 
         # Print output
         print(output)

{runpod-2.2.0 → runpod-2.2.1}/examples/endpoints/health.py

@@ -2,10 +2,10 @@
 
 import runpod
 
-# Set your global API key with `runpod config` or uncomment the line below:
+# Run `rp login` once to store your API key, or uncomment the line below:
 # runpod.api_key = "YOUR_RUNPOD_API_KEY"
 
-endpoint = runpod.Endpoint("gwp4kx5yd3nur1")
+endpoint = runpod.Endpoint("YOUR_ENDPOINT_ID")
 
 endpoint_health = endpoint.health()
 

runpod-2.2.1/examples/endpoints/run.py

@@ -0,0 +1,23 @@
+"""
+Example of calling an endpoint using the Runpod Python Language Library.
+"""
+
+import runpod
+
+# Run `rp login` once to store your API key, or uncomment the line below:
+# runpod.api_key = "YOUR_RUNPOD_API_KEY"
+
+endpoint = runpod.Endpoint("YOUR_ENDPOINT_ID")
+
+run_request = endpoint.run(
+    {"input": {"prompt": "a photo of a horse the size of a Boeing 787"}}
+)
+
+# Check the status of the run request, for example IN_QUEUE or IN_PROGRESS.
+print(run_request.status())
+
+# Wait up to 60 seconds for the job to finish, then print its output.
+# Raises TimeoutError if the job is still running after that.
+# Without a timeout, output() returns immediately, and returns None if the
+# job has not finished yet.
+print(run_request.output(timeout=60))

{runpod-2.2.0 → runpod-2.2.1}/examples/endpoints/run_sync.py

@@ -2,12 +2,14 @@
 Example of calling an endpoint using the Runpod Python Language Library.
 """
 
+import requests
+
 import runpod
 
-# Set your global API key with `runpod config` or uncomment the line below:
+# Run `rp login` once to store your API key, or uncomment the line below:
 # runpod.api_key = "YOUR_RUNPOD_API_KEY"
 
-endpoint = runpod.Endpoint("sdxl")  # Where "sdxl" is the endpoint ID
+endpoint = runpod.Endpoint("YOUR_ENDPOINT_ID")
 
 try:
     # Run the endpoint synchronously, blocking until the endpoint run is complete.
@@ -17,5 +19,7 @@ try:
     )
 
     print(run_request)
-except TimeoutError:
+except (TimeoutError, requests.exceptions.Timeout):
+    # TimeoutError: the job was still running when the timeout expired.
+    # requests.exceptions.Timeout: the HTTP request itself timed out.
     print("Job timed out.")

runpod-2.2.1/examples/endpoints/streaming.py

@@ -0,0 +1,24 @@
+""" Example of streaming data from an endpoint. """
+
+import runpod
+
+# Run `rp login` once to store your API key, or uncomment the line below:
+# runpod.api_key = "YOUR_RUNPOD_API_KEY"
+
+# This input targets an endpoint running the runpod/mock-worker image started
+# with --generator, which yields each item of mock_return with mock_delay
+# seconds between them. Replace it with the input your own streaming
+# handler expects.
+endpoint = runpod.Endpoint("YOUR_ENDPOINT_ID")
+
+run_request = endpoint.run(
+    {
+        "input": {
+            "mock_return": ["a", "b", "c", "d", "e", "f", "g"],
+            "mock_delay": 1,
+        }
+    }
+)
+
+for output in run_request.stream():
+    print(output)

runpod-2.2.1/examples/rest_wrapper.py

@@ -0,0 +1,47 @@
+"""Create, stop, resume, and terminate a pod with the Runpod API.
+
+This creates a billable GPU pod. The pod is terminated at the end, including
+when a step fails.
+"""
+
+import time
+
+import runpod
+
+# Run `rp login` once to store your API key, or uncomment the line below:
+# runpod.api_key = "YOUR_RUNPOD_API_KEY"
+
+GPU_TYPE = "NVIDIA GeForce RTX 4090"  # see `rp catalog` for other GPU types
+WAIT_SECONDS = 10
+
+gpus = runpod.get_gpus()
+print(gpus)
+
+gpu = runpod.get_gpu(GPU_TYPE)
+print(gpu)
+
+pod = runpod.create_pod(
+    "example-pod",
+    "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404",
+    GPU_TYPE,
+)
+print(pod)
+pod_id = pod["id"]
+
+try:
+    print("Waiting for pod to be created...")
+    time.sleep(WAIT_SECONDS)
+
+    print(runpod.stop_pod(pod_id))
+
+    print("Waiting for pod to be stopped...")
+    time.sleep(WAIT_SECONDS)
+
+    # Resuming can fail if no GPU of this type is free on the pod's machine.
+    print(runpod.resume_pod(pod_id))
+
+    print("Waiting for pod to be resumed...")
+    time.sleep(WAIT_SECONDS)
+finally:
+    runpod.terminate_pod(pod_id)
+    print(f"Terminated pod {pod_id}")

runpod-2.2.1/examples/serverless/concurrent_handler.py

@@ -0,0 +1,41 @@
+"""Concurrency Modifier Example
+
+An async handler lets one worker run several jobs at once. The worker calls
+the concurrency modifier with its current concurrency and resizes to the value
+it returns, waiting until no jobs are in flight before resizing.
+
+To test locally, run:
+python concurrent_handler.py --test_input '{"input": {"seconds": 1}}'
+"""
+
+import asyncio
+
+import runpod
+
+MAX_CONCURRENCY = 4
+
+
+# ---------------------------------- Handler --------------------------------- #
+async def async_handler(job):
+    """
+    Async handler. While it awaits, the worker can start other jobs.
+    """
+    seconds = job["input"].get("seconds", 1)
+    await asyncio.sleep(seconds)
+    return {"slept": seconds}
+
+
+# --------------------------- Concurrency Modifier --------------------------- #
+def concurrency_modifier(current_concurrency: int) -> int:
+    """
+    Return the number of jobs this worker should run at once.
+
+    Replace the fixed value with your own logic, for example based on free
+    GPU memory or queue depth.
+    """
+    return MAX_CONCURRENCY
+
+
+runpod.serverless.start(
+    {"handler": async_handler, "concurrency_modifier": concurrency_modifier}
+)

{runpod-2.2.0 → runpod-2.2.1}/examples/serverless/logger.py

@@ -1,4 +1,8 @@
-""" Example of using the RunPodLogger class. """ ""
+"""Example of using the RunPodLogger class.
+
+Running locally, the logger prints plain text. On a deployed worker, where
+RUNPOD_ENDPOINT_ID is set, it prints one JSON object per line instead.
+"""
 
 import runpod
 
@@ -11,11 +15,11 @@ log.info("An info message")
 log.warn("A warning message")
 log.error("An error message")
 
-# Output:
-# DEBUG   | A debug message
-# INFO    | An info message
-# WARN    | A warning message
-# ERROR   | An error message
+# Local output:
+# DEBUG  | A debug message
+# INFO   | An info message
+# WARN   | A warning message
+# ERROR  | An error message
 
 
 log.debug("A debug message", request_id=JOB_ID)
@@ -23,7 +27,13 @@ log.info("An info message", request_id=JOB_ID)
 log.warn("A warning message", request_id=JOB_ID)
 log.error("An error message", request_id=JOB_ID)
 
-# Output:
+# Local output:
+# DEBUG  | 1234567890 | A debug message
+# INFO   | 1234567890 | An info message
+# WARN   | 1234567890 | A warning message
+# ERROR  | 1234567890 | An error message
+
+# Output on a deployed worker:
 # {"requestId": "1234567890", "message": "A debug message", "level": "DEBUG"}
 # {"requestId": "1234567890", "message": "An info message", "level": "INFO"}
 # {"requestId": "1234567890", "message": "A warning message", "level": "WARN"}

{runpod-2.2.0 → runpod-2.2.1}/runpod/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.2.0'
-__version_tuple__ = version_tuple = (2, 2, 0)
+__version__ = version = '2.2.1'
+__version_tuple__ = version_tuple = (2, 2, 1)
 
-__commit_id__ = commit_id = 'g89d72b8c4'
+__commit_id__ = commit_id = 'gba5e6ad82'

{runpod-2.2.0 → runpod-2.2.1}/runpod/api/queries/apps.py

@@ -19,7 +19,7 @@ query getFlashAppByName($flashAppName: String!) {
             name
             state
             activeBuildId
-            endpoints { id name }
+            endpoints { id name template { name } }
         }
     }
 }
@@ -60,7 +60,7 @@ query getFlashEnvironmentByName($input: FlashEnvironmentByNameInput!) {
         state
         activeBuildId
         createdAt
-        endpoints { id name }
+        endpoints { id name template { name } }
         networkVolumes { id name }
     }
 }

{runpod-2.2.0 → runpod-2.2.1}/runpod/apps/auth.py

@@ -4,7 +4,11 @@ import asyncio
 import base64
 import datetime as dt
 import hashlib
+import json
+import os
 import secrets
+import tempfile
+from pathlib import Path
 from typing import Any, Callable, Dict, Optional
 from urllib.parse import quote
 from uuid import uuid4
@@ -89,8 +93,59 @@ async def _post_authentication_attempt(
     return payload
 
 
-async def agent_login(email: str, *, read_code: Callable[[], str]) -> str:
-    """exchange an emailed code for an api key bound to this login's verifier."""
+def pending_agent_login_path(profile: str) -> Path:
+    from runpod.cli.groups.config.functions import CREDENTIAL_FILE
+
+    profile_id = hashlib.sha256(profile.encode("utf-8")).hexdigest()
+    return Path(CREDENTIAL_FILE).parent / f"login-{profile_id}.json"
+
+
+def save_agent_login(attempt: dict, profile: str) -> None:
+    path = pending_agent_login_path(profile)
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    fd, temporary = tempfile.mkstemp(dir=path.parent, suffix=".json")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as pending:
+            json.dump(attempt, pending)
+        os.replace(temporary, path)
+    except BaseException:
+        os.unlink(temporary)
+        raise
+
+
+def load_agent_login(profile: str) -> dict:
+    try:
+        attempt = json.loads(
+            pending_agent_login_path(profile).read_text(encoding="utf-8")
+        )
+    except FileNotFoundError:
+        raise LoginError(
+            "no pending login for this profile. Run runpod login --agent --email ADDRESS"
+        ) from None
+    except ValueError:
+        raise LoginError(
+            "invalid pending login. Run runpod login --agent --email ADDRESS to request a new code"
+        ) from None
+    if not isinstance(attempt, dict) or any(
+        not isinstance(attempt.get(field), str) or not attempt[field]
+        for field in ("attempt_id", "verifier", "api_url")
+    ):
+        raise LoginError(
+            "invalid pending login. Run runpod login --agent --email ADDRESS to request a new code"
+        )
+    return attempt
+
+
+def _agent_session() -> aiohttp.ClientSession:
+    return aiohttp.ClientSession(
+        timeout=aiohttp.ClientTimeout(total=30),
+        headers={"Accept": "application/json", "User-Agent": USER_AGENT},
+        cookie_jar=aiohttp.DummyCookieJar(),
+    )
+
+
+async def start_agent_login(email: str) -> dict:
+    """request an emailed code and return its proof-of-possession state."""
     verifier = secrets.token_urlsafe(32)
     challenge = (
         base64.urlsafe_b64encode(hashlib.sha256(verifier.encode("ascii")).digest())
@@ -99,11 +154,7 @@ async def agent_login(email: str, *, read_code: Callable[[], str]) -> str:
     )
     path = "/v2/signup/authentication-attempts"
 
-    async with aiohttp.ClientSession(
-        timeout=aiohttp.ClientTimeout(total=30),
-        headers={"Accept": "application/json", "User-Agent": USER_AGENT},
-        cookie_jar=aiohttp.DummyCookieJar(),
-    ) as session:
+    async with _agent_session() as session:
         attempt = await _post_authentication_attempt(
             session,
             path,
@@ -114,17 +165,20 @@ async def agent_login(email: str, *, read_code: Callable[[], str]) -> str:
         if not isinstance(attempt_id, str) or not attempt_id:
             raise LoginError("auth attempt failed to initialize")
 
-        while True:
-            code = read_code()
-            try:
-                result = await _post_authentication_attempt(
-                    session,
-                    f"{path}/{quote(attempt_id, safe='')}/verify",
-                    {"code": code, "codeVerifier": verifier},
-                )
-            except _VerificationCodeRejected:
-                continue
-            break
+    return {"attempt_id": attempt_id, "verifier": verifier, "api_url": _build_url(path)}
+
+
+async def verify_agent_login(attempt: dict, code: str) -> str:
+    """exchange a code and its saved verifier for an api key."""
+    path = "/v2/signup/authentication-attempts"
+    if attempt["api_url"] != _build_url(path):
+        raise LoginError("pending login belongs to a different API. Request a new code")
+    async with _agent_session() as session:
+        result = await _post_authentication_attempt(
+            session,
+            f"{path}/{quote(attempt['attempt_id'], safe='')}/verify",
+            {"code": code, "codeVerifier": attempt["verifier"]},
+        )
         credential = result.get("credential")
         api_key = credential.get("apiKey") if isinstance(credential, dict) else None
         if not isinstance(api_key, str) or not api_key.strip():
@@ -132,6 +186,17 @@ async def agent_login(email: str, *, read_code: Callable[[], str]) -> str:
         return api_key
 
 
+async def agent_login(email: str, *, read_code: Callable[[], str]) -> str:
+    """exchange an emailed code for an api key bound to this login's verifier."""
+    attempt = await start_agent_login(email)
+    while True:
+        code = read_code()
+        try:
+            return await verify_agent_login(attempt, code)
+        except _VerificationCodeRejected:
+            continue
+
+
 def _parse_expires_at(value: Optional[str]) -> Optional[dt.datetime]:
     if not value:
         return None