custom-agent-creator

Custom Agent Creation and Integration

Minimum Inputs

• Confirm Agent name (registry key used in configs/agent_registry.yaml and root config.yaml)
• Confirm Python module name (browseruse_bench/agents/.py)
• Confirm supported benchmarks (e.g., Online-Mind2Web / BrowseComp / LexBench-Browser)
• Collect external docs URL(s); read and extract usable SDK/API details
• Define config keys (model_id, api_key, base_url, timeout, SDK-specific options)
• Agent runtime config lives in root config.yaml under agents:<agent_name>; model/provider parameters are read from agent_config and injected into SDK constructors directly

Required References

• browseruse_bench/agents/init.py (check existing imports before adding)
• configs/agent_registry.yaml (check existing agent registrations)

Load when needed (do NOT read upfront)

• references/custom-agent-integration.md — SDK integration patterns
• browseruse_bench/agents/base.py — BaseAgent method signatures
• browseruse_bench/agents/registry.py — @register_agent internals
• browseruse_bench/runner/agent_runner.py — runner entrypoint conventions
• browseruse_bench/cli/run.py — extra dependency mapping
• browseruse_bench/utils/venv.py — install_agent_dependencies (supports requirements_file)
• browseruse_bench/agents/browser_use.py — simple agent reference example
• browseruse_bench/agents/agent_tars.py — subprocess-based agent example
• browseruse_bench/agents/skyvern.py — async/CDP agent example
• docs/en/agents/custom-agent.mdx — user-facing docs template
• docs/zh/agents/custom-agent.mdx — Chinese docs template

Standard Workflow

1. Create module:
   • browseruse_bench/agents/<agent_module>.py
2. Implement BaseAgent subclass:
   • Add from future import annotations
   • PEP8 import order: stdlib → third-party → local
   • Use typing annotations (Dict, Any, Path)
   • Do not use print(); use logger
   • Do not use sys.path.insert
   • Read all configurable values from agent_config (no hardcoding)
   • Pass model/provider parameters from agent_config directly into SDK constructors (avoid relying solely on environment variables)
   • If the upstream SDK has a hardcoded/whitelist model check, do not expose that limitation directly to browseruse-bench users when it can be avoided: use a provider-native bootstrap/default model only for SDK initialization, and after initialization replace the SDK's runtime inference client/engine with your own wrapper that honors the configured model_id, api_key, and base_url
   • Resolve paths with REPO_ROOT when touching files
3. Register module import:
   • Add from browseruse_bench.agents import <agent_module> # noqa: F401 to browseruse_bench/agents/init.py
4. Register agent in configs/agent_registry.yaml:
   • path: browseruse_bench/agents
   • entrypoint: browseruse_bench/runner/agent_runner.py
   • venv: .venv (or .venvs/ if it needs an isolated environment)
   • supported_benchmarks: [...]
5. Add runtime config to root config.yaml under agents:<agent_name>:
   • active_model: <default_model_key>
   • models: { <model_key>: { model_id, api_key, base_url, ... } }
   • browser: { browser_id, ... } (if the agent uses a browser)
   • defaults: { timeout, max_steps, ... }
6. Add dependencies — two paths depending on whether the agent's deps conflict with core: