feat: crewai deploy validate + defer native LLM client construction

[greysonlalonde]

Summary

Two related changes that together prevent the most common category of deploy-time failures:

• fix (851df79) — all native LLM providers now build their SDK clients lazily. Instantiating LLM(model="openai/gpt-4o-mini") at module scope (e.g. as a class default on a @crew method) previously crashed during crew-metadata extraction with ImportError: Error importing native provider: 1 validation error... whenever the API key wasn't in os.environ at the moment of import. _init_clients now wraps eager construction in try/except ValueError and _get_sync_client / _get_async_client helpers build on first use, re-raising the descriptive X_API_KEY is required error only at real call time.
• feat (9f61deb) — new crewai deploy validate command that runs 9 local checks against the project before it contacts the deploy API. crewai deploy create and crewai deploy push run the same checks automatically and abort on errors; --skip-validate opts out.

Checks

1. pyproject.toml with [project].name
2. lockfile (uv.lock / poetry.lock) present and not stale
3. src/<package>/ resolves (catches empty package names and .egg-info misdetection)
4. crew.py, config/agents.yaml, config/tasks.yaml for standard crews
5. main.py for flows
6. hatchling wheel target resolves
7. crew/flow module imports cleanly in a uv run subprocess with structured classification of failures (missing provider extras, missing API keys at import, stale crewai pins, pydantic errors)
8. env vars referenced in source vs .env (warning only)
9. crewai lockfile pin vs a known-bad cutoff (warning only)

Each finding has a stable code + structured title/detail/hint, so tests pin behavior 1:1 against the failure patterns this work was driven from.

Test plan

• 358/358 provider + deploy tests pass (pytest tests/llms/{openai,anthropic,azure,google,bedrock} tests/cli/deploy)
• Verified LLM(model="openai/gpt-4o-mini") succeeds with no API key set (previously raised ImportError: Error importing native provider: 1 validation error)
• Same for Anthropic, Gemini, Azure
• 33 new tests in tests/cli/deploy/test_validate.py cover each check 1:1
• crewai deploy validate smoke-tested against a broken project (missing pyproject.toml) — reports missing_pyproject and exits non-zero
• ruff check clean, ruff format clean on touched files

---

Note

Medium Risk
Adds a new validation gate that can block deployments and refactors native LLM providers to defer SDK client creation; both affect critical deploy/runtime paths and could surface new edge cases around credential discovery and client lifecycle.

Overview
Adds pre-deploy project validation via new crewai deploy validate, and runs the same checks automatically before crewai deploy create/push (with --skip-validate to bypass), aborting before contacting the platform when blocking issues are found.

Introduces a new DeployValidator that checks common deployment failure modes (project metadata/layout, lockfiles, hatchling wheel targeting, importability via uv run, env var usage, and stale crewai pins) and prints structured error/warning reports with stable codes.

Refactors native LLM providers (OpenAI, Anthropic, Azure, Gemini, Bedrock) to lazily build sync/async SDK clients using _get_sync_client()/_get_async_client(), so missing credentials don’t crash module import; tests are updated/added to cover lazy credential resolution and no-op cleanup behavior.

^{Reviewed by Cursor Bugbot for commit 4c3ff7d. Bugbot is set up for automated code reviews on this repo. Configure here.}

[iris-clawd]

Excellent PR — two complementary changes that address the most common deploy failure category.

Lazy client construction (all 5 native providers):

• Pattern is consistent: _init_clients wraps eager construction in try/except ValueError, _build_sync_client/_build_async_client factored out, _get_sync_client/_get_async_client build on first use
• All call sites updated from self._client → self._get_sync_client() etc.
• Azure tests updated to assert new lazy-error contract (construction succeeds, _get_sync_client() raises)
• This unblocks the key pattern: LLM(model="openai/gpt-4o-mini") as a class field default at import time

Deploy validator (842-line validate.py + 400-line test suite):

• 9 checks covering the failure patterns from production: pyproject, lockfile, package dir, crew/flow entrypoints, hatchling config, module imports, env vars, version pins
• Import check via uv run subprocess with JSON payload — smart approach to test in the real dependency environment
• _classify_import_error handles all the observed patterns: missing extras, missing API keys, no @crewbase, no Flow subclass, stale pins, pydantic errors
• Error/warning severity distinction is correct: missing structure = error, missing env vars = warning (platform sets them server-side)
• --skip-validate escape hatch on create/push
• Tests are thorough — 33 tests covering each code 1:1, including regression cases from production failures

Minor notes (non-blocking):

• The Bedrock lazy path catches Exception rather than ValueError (matches its broader auth failure modes — fine)
• aclose() in Azure calls _get_async_client() which could trigger lazy construction just to close — unlikely in practice but worth noting

LGTM 🚀 💬 223

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 4c3ff7d. Configure here.}

[cursor]

Regex never matches real provider error messages

Medium Severity

The missing_provider_extra regex expects backtick-delimited install commands (`([^`]+)`), but the actual ImportError messages raised by all provider modules (anthropic, azure, bedrock, gemini) use plain quotes without backticks — e.g., '...to install: uv add "crewai[anthropic]"'. This means the regex will never match real errors. The test only passes because it artificially injects backticks into the error message. In production, these errors fall through to the less-specific llm_provider_init_failed classification, losing the targeted missing_provider_extra code and the extracted install command hint.

Additional Locations (1)

• lib/crewai/tests/cli/deploy/test_validate.py#L288-L295

 

^{Reviewed by Cursor Bugbot for commit 4c3ff7d. Configure here.}