feat: support both `api_key` and `apiKey` for CUA agent API keys

T-
1y ago
+13-7

why

  • Python docs and examples use api_key (snake_case), e.g. at https://docs.stagehand.dev/v2/basics/agent:
    agent = stagehand.agent(
        model="claude-sonnet-4-20250514",
        instructions="You are a helpful assistant that can use a web browser.",
        options={"api_key": os.getenv("ANTHROPIC_API_KEY")},
    )
    await agent.execute("apply for a job at Browserbase")
    
  • At https://www.browserbase.com/blog/evaluating-browser-agents, the uvx create-browser-app --template gemini-cua template also uses api_key.
  • The CUA implementations were only reading apiKey from config.options, so running the generated Gemini example could error with:
    GEMINI_API_KEY environment variable not set and not provided in config.
    
    even when options={"api_key": ...} was provided.
  • This is unnecessarily confusing and inconsistent between docs, templates, and runtime.

what changed

  • Anthropic CUA

    • API key resolution order:
      1. config.options["api_key"]
      2. config.options["apiKey"]
      3. ANTHROPIC_API_KEY env var
    • Safely handle config / config.options being None.
  • OpenAI CUA

    • API key resolution order:
      1. config.options["api_key"]
      2. config.options["apiKey"]
      3. OPENAI_API_KEY env var
    • Safely handle config / config.options being None.
  • Google CUA (Gemini)

    • API key resolution order:
      1. config.options["api_key"]
      2. config.options["apiKey"]
      3. GEMINI_API_KEY env var
      4. Raise ValueError if still missing (same behavior as before).
    • Switched env var name and error messaging to GEMINI_API_KEY, matching the Gemini usage and the generated template.

test plan

  • Generate and run the Gemini example:

    • uvx create-browser-app --template gemini-cua
    • Ensure it passes options={"api_key": os.getenv("GEMINI_API_KEY")}.
    • Run python main.py and verify it no longer fails with a missing GEMINI_API_KEY error when api_key is set.
  • Smoke-test Anthropic and OpenAI CUA:

    • For each:
      • options={"api_key": ...}
      • options={"apiKey": ...}
      • Only the respective *_API_KEY env var set, with options omitted.
    • Confirm authentication works and no AttributeError is raised when config / options is absent.

Summary by cubic

Support both api_key and apiKey for CUA agent API keys and standardize Gemini to GEMINI_API_KEY. Fixes auth errors in the Gemini template and aligns behavior with docs and examples.

  • Bug Fixes

    • Anthropic, OpenAI, and Gemini now resolve API keys in this order: options["api_key"] → options["apiKey"] → env var; also handles missing config/options safely.
    • Gemini uses GEMINI_API_KEY for env lookup and updated the error message accordingly.
  • Migration

    • If you set a different env var for Gemini before, rename it to GEMINI_API_KEY or pass options={"api_key": "..."} (or {"apiKey": "..."}).