docs: add Agent Capabilities overview page and improve Skills docs

- New 'Agent Capabilities' page explaining all 5 extension types (Tools, MCPs, Apps, Skills, Knowledge) with comparison table and decision guide
- Rewrite Skills page with practical examples showing Skills + Tools patterns, common FAQ, and Skills vs Knowledge comparison
- Add cross-reference callout on Tools page linking to the capabilities overview
- Add agent-capabilities to Core Concepts navigation (after agents)

.github/security.md

@@ -1,50 +1,12 @@
 ## CrewAI Security Policy
 
-We are committed to protecting the confidentiality, integrity, and availability of the CrewAI ecosystem. This policy explains how to report potential vulnerabilities and what you can expect from us when you do.
-
-### Scope
-
-We welcome reports for vulnerabilities that could impact:
-
-- CrewAI-maintained source code and repositories
-- CrewAI-operated infrastructure and services
-- Official CrewAI releases, packages, and distributions
-
-Issues affecting clearly unaffiliated third-party services or user-generated content are out of scope, unless you can demonstrate a direct impact on CrewAI systems or customers.
+We are committed to protecting the confidentiality, integrity, and availability of the
+CrewAI ecosystem.
 
 ### How to Report
 
-- **Please do not** disclose vulnerabilities via public GitHub issues, pull requests, or social media.
-- Email detailed reports to **security@crewai.com** with the subject line `Security Report`.
-- If you need to share large files or sensitive artifacts, mention it in your email and we will coordinate a secure transfer method.
+Please submit reports to **crewai-vdp-ess@submit.bugcrowd.com**
 
-### What to Include
-
-Providing comprehensive information enables us to validate the issue quickly:
-
-- **Vulnerability overview** — a concise description and classification (e.g., RCE, privilege escalation)
-- **Affected components** — repository, branch, tag, or deployed service along with relevant file paths or endpoints
-- **Reproduction steps** — detailed, step-by-step instructions; include logs, screenshots, or screen recordings when helpful
-- **Proof-of-concept** — exploit details or code that demonstrates the impact (if available)
-- **Impact analysis** — severity assessment, potential exploitation scenarios, and any prerequisites or special configurations
-
-### Our Commitment
-
-- **Acknowledgement:** We aim to acknowledge your report within two business days.
-- **Communication:** We will keep you informed about triage results, remediation progress, and planned release timelines.
-- **Resolution:** Confirmed vulnerabilities will be prioritized based on severity and fixed as quickly as possible.
-- **Recognition:** We currently do not run a bug bounty program; any rewards or recognition are issued at CrewAI's discretion.
-
-### Coordinated Disclosure
-
-We ask that you allow us a reasonable window to investigate and remediate confirmed issues before any public disclosure. We will coordinate publication timelines with you whenever possible.
-
-### Safe Harbor
-
-We will not pursue or support legal action against individuals who, in good faith:
-
-- Follow this policy and refrain from violating any applicable laws
-- Avoid privacy violations, data destruction, or service disruption
-- Limit testing to systems in scope and respect rate limits and terms of service
-
-If you are unsure whether your testing is covered, please contact us at **security@crewai.com** before proceeding.
+- **Please do not** disclose vulnerabilities via public GitHub issues, pull requests,
+  or social media
+- Reports submitted via channels other than this Bugcrowd submission email will not be reviewed and will be dismissed

.github/workflows/docs-broken-links.yml

@@ -23,7 +23,7 @@ jobs:
       - name: Set up Node
         uses: actions/setup-node@v4
         with:
-          node-version: "latest"
+          node-version: "22"
 
       - name: Install Mintlify CLI
         run: npm i -g mintlify

docs/ar/changelog.mdx

@@ -4,6 +4,171 @@ description: "تحديثات المنتج والتحسينات وإصلاحات
 icon: "clock"
 mode: "wide"
 ---
+<Update label="27 مارس 2026">
+  ## v1.13.0rc1
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0rc1)
+
+  ## ما الذي تغير
+
+  ### الوثائق
+  - تحديث سجل التغييرات والإصدار لـ v1.13.0a2
+
+  ## المساهمون
+
+  @greysonlalonde
+
+</Update>
+
+<Update label="27 مارس 2026">
+  ## v1.13.0a2
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a2)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - تحديث تلقائي لمستودع اختبار النشر أثناء الإصدار
+  - تحسين مرونة إصدار المؤسسات وتجربة المستخدم
+
+  ### الوثائق
+  - تحديث سجل التغييرات والإصدار للإصدار v1.13.0a1
+
+  ## المساهمون
+
+  @greysonlalonde
+
+</Update>
+
+<Update label="27 مارس 2026">
+  ## v1.13.0a1
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a1)
+
+  ## ما الذي تغير
+
+  ### إصلاحات الأخطاء
+  - إصلاح الروابط المعطلة في سير العمل الوثائقي عن طريق تثبيت Node على LTS 22
+  - مسح ذاكرة التخزين المؤقت لـ uv للحزم المنشورة حديثًا في الإصدار المؤسسي
+
+  ### الوثائق
+  - إضافة مصفوفة شاملة لأذونات RBAC ودليل النشر
+  - تحديث سجل التغييرات والإصدار للإصدار v1.12.2
+
+  ## المساهمون
+
+  @greysonlalonde, @iris-clawd, @joaomdmoura
+
+</Update>
+
+<Update label="25 مارس 2026">
+  ## v1.12.2
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.2)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - إضافة مرحلة إصدار المؤسسات إلى إصدار أدوات المطورين
+
+  ### إصلاحات الأخطاء
+  - الحفاظ على قيمة إرجاع الطريقة كإخراج تدفق لـ @human_feedback مع emit
+
+  ### الوثائق
+  - تحديث سجل التغييرات والإصدار لـ v1.12.1
+  - مراجعة سياسة الأمان وتعليمات الإبلاغ
+
+  ## المساهمون
+
+  @alex-clawd, @greysonlalonde, @joaomdmoura, @theCyberTech
+
+</Update>
+
+<Update label="25 مارس 2026">
+  ## v1.12.1
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.1)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - إضافة request_id إلى HumanFeedbackRequestedEvent
+  - إضافة Qdrant Edge كخلفية تخزين لنظام الذاكرة
+  - إضافة أمر docs-check لتحليل التغييرات وتوليد الوثائق مع الترجمات
+  - إضافة دعم اللغة العربية إلى سجل التغييرات وأدوات الإصدار
+  - إضافة ترجمة باللغة العربية الفصحى لجميع الوثائق
+  - إضافة أمر تسجيل الخروج في واجهة سطر الأوامر
+  - إضافة مهارات الوكيل
+  - تنفيذ root_scope تلقائيًا لعزل الذاكرة الهيكلية
+  - تنفيذ مزودين متوافقين مع OpenAI (OpenRouter، DeepSeek، Ollama، vLLM، Cerebras، Dashscope)
+
+  ### إصلاحات الأخطاء
+  - إصلاح بيانات اعتماد غير صحيحة لدفع دفعات التتبع (404)
+  - حل العديد من الأخطاء في نظام تدفق HITL
+  - إصلاح حفظ ذاكرة الوكيل
+  - حل جميع أخطاء mypy الصارمة عبر حزمة crewai
+  - إصلاح استخدام __router_paths__ لطرق المستمع + الموجه في FlowMeta
+  - إصلاح خطأ القيمة عند عدم دعم الملفات
+  - تصحيح صياغة الحجر الصحي لـ litellm في الوثائق
+  - إصلاح جميع أخطاء mypy في crewai-files وإضافة جميع الحزم إلى فحوصات النوع في CI
+  - تثبيت الحد الأعلى لـ litellm على آخر إصدار تم اختباره (1.82.6)
+
+  ### الوثائق
+  - تحديث سجل التغييرات والإصدار لـ v1.12.0
+  - إضافة CONTRIBUTING.md
+  - إضافة دليل لاستخدام CrewAI بدون LiteLLM
+
+  ## المساهمون
+
+  @akaKuruma، @alex-clawd، @greysonlalonde، @iris-clawd، @joaomdmoura، @lorenzejay، @lucasgomide، @nicoferdi96
+
+</Update>
+
+<Update label="25 مارس 2026">
+  ## v1.12.0
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - إضافة واجهة تخزين Qdrant Edge لنظام الذاكرة
+  - إضافة أمر docs-check لتحليل التغييرات وتوليد الوثائق مع الترجمات
+  - إضافة دعم اللغة العربية لسجل التغييرات وأدوات الإصدار
+  - إضافة ترجمة اللغة العربية الفصحى لجميع الوثائق
+  - إضافة أمر تسجيل الخروج في واجهة سطر الأوامر
+  - تنفيذ مهارات الوكيل
+  - تنفيذ نطاق الجذر التلقائي لعزل الذاكرة الهرمية
+  - تنفيذ موفري خدمات متوافقين مع OpenAI (OpenRouter، DeepSeek، Ollama، vLLM، Cerebras، Dashscope)
+
+  ### إصلاح الأخطاء
+  - إصلاح بيانات الاعتماد السيئة لدفع دفعات التتبع (404)
+  - حل العديد من الأخطاء في نظام تدفق HITL
+  - حل أخطاء mypy في crewai-files وإضافة جميع الحزم إلى فحوصات نوع CI
+  - حل جميع أخطاء mypy الصارمة عبر حزمة crewai-tools
+  - حل جميع أخطاء mypy عبر حزمة crewai
+  - إصلاح حفظ الذاكرة في الوكيل
+  - إصلاح استخدام __router_paths__ لطرق المستمع + الموجه في FlowMeta
+  - رفع خطأ القيمة عند عدم دعم الملفات
+  - تصحيح صياغة الحجر الصحي لـ litellm في الوثائق
+  - استخدام فحص None بدلاً من isinstance للذاكرة في تعلم التغذية الراجعة البشرية
+  - تثبيت الحد الأعلى لـ litellm على آخر إصدار تم اختباره (1.82.6)
+
+  ### الوثائق
+  - تحديث سجل التغييرات والإصدار لـ v1.12.0
+  - إضافة CONTRIBUTING.md
+  - إضافة دليل لاستخدام CrewAI بدون LiteLLM
+
+  ### إعادة الهيكلة
+  - إعادة هيكلة لتجنب تكرار تنفيذ المهام المتزامنة / غير المتزامنة وبدء التشغيل في الوكيل
+  - تبسيط الأنابيب الداخلية من litellm (عد الرموز، ردود النداء، اكتشاف الميزات، الأخطاء)
+
+  ## المساهمون
+
+  @akaKuruma، @alex-clawd، @greysonlalonde، @iris-clawd، @joaomdmoura، @lorenzejay، @nicoferdi96
+
+</Update>
+
 <Update label="26 مارس 2026">
   ## v1.12.0a3
 

docs/en/changelog.mdx

@@ -4,6 +4,171 @@ description: "Product updates, improvements, and bug fixes for CrewAI"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="Mar 27, 2026">
+  ## v1.13.0rc1
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0rc1)
+
+  ## What's Changed
+
+  ### Documentation
+  - Update changelog and version for v1.13.0a2
+
+  ## Contributors
+
+  @greysonlalonde
+
+</Update>
+
+<Update label="Mar 27, 2026">
+  ## v1.13.0a2
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a2)
+
+  ## What's Changed
+
+  ### Features
+  - Auto-update deployment test repo during release
+  - Improve enterprise release resilience and UX
+
+  ### Documentation
+  - Update changelog and version for v1.13.0a1
+
+  ## Contributors
+
+  @greysonlalonde
+
+</Update>
+
+<Update label="Mar 27, 2026">
+  ## v1.13.0a1
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a1)
+
+  ## What's Changed
+
+  ### Bug Fixes
+  - Fix broken links in documentation workflow by pinning Node to LTS 22
+  - Bust the uv cache for freshly published packages in enterprise release
+
+  ### Documentation
+  - Add comprehensive RBAC permissions matrix and deployment guide
+  - Update changelog and version for v1.12.2
+
+  ## Contributors
+
+  @greysonlalonde, @iris-clawd, @joaomdmoura
+
+</Update>
+
+<Update label="Mar 25, 2026">
+  ## v1.12.2
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.2)
+
+  ## What's Changed
+
+  ### Features
+  - Add enterprise release phase to devtools release
+
+  ### Bug Fixes
+  - Preserve method return value as flow output for @human_feedback with emit
+
+  ### Documentation
+  - Update changelog and version for v1.12.1
+  - Revise security policy and reporting instructions
+
+  ## Contributors
+
+  @alex-clawd, @greysonlalonde, @joaomdmoura, @theCyberTech
+
+</Update>
+
+<Update label="Mar 25, 2026">
+  ## v1.12.1
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.1)
+
+  ## What's Changed
+
+  ### Features
+  - Add request_id to HumanFeedbackRequestedEvent
+  - Add Qdrant Edge storage backend for memory system
+  - Add docs-check command to analyze changes and generate docs with translations
+  - Add Arabic language support to changelog and release tooling
+  - Add modern standard Arabic translation of all documentation
+  - Add logout command in CLI
+  - Add agent skills
+  - Implement automatic root_scope for hierarchical memory isolation
+  - Implement native OpenAI-compatible providers (OpenRouter, DeepSeek, Ollama, vLLM, Cerebras, Dashscope)
+
+  ### Bug Fixes
+  - Fix bad credentials for traces batch push (404)
+  - Resolve multiple bugs in HITL flow system
+  - Fix agent memory saving
+  - Resolve all strict mypy errors across crewai package
+  - Fix use of __router_paths__ for listener+router methods in FlowMeta
+  - Fix value error on no file support
+  - Correct litellm quarantine wording in docs
+  - Fix all mypy errors in crewai-files and add all packages to CI type checks
+  - Pin litellm upper bound to last tested version (1.82.6)
+
+  ### Documentation
+  - Update changelog and version for v1.12.0
+  - Add CONTRIBUTING.md
+  - Add guide for using CrewAI without LiteLLM
+
+  ## Contributors
+
+  @akaKuruma, @alex-clawd, @greysonlalonde, @iris-clawd, @joaomdmoura, @lorenzejay, @lucasgomide, @nicoferdi96
+
+</Update>
+
+<Update label="Mar 25, 2026">
+  ## v1.12.0
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0)
+
+  ## What's Changed
+
+  ### Features
+  - Add Qdrant Edge storage backend for memory system
+  - Add docs-check command to analyze changes and generate docs with translations
+  - Add Arabic language support to changelog and release tooling
+  - Add modern standard Arabic translation of all documentation
+  - Add logout command in CLI
+  - Implement agent skills
+  - Implement automatic root_scope for hierarchical memory isolation
+  - Implement native OpenAI-compatible providers (OpenRouter, DeepSeek, Ollama, vLLM, Cerebras, Dashscope)
+
+  ### Bug Fixes
+  - Fix bad credentials for traces batch push (404)
+  - Resolve multiple bugs in HITL flow system
+  - Resolve mypy errors in crewai-files and add all packages to CI type checks
+  - Resolve all strict mypy errors across crewai-tools package
+  - Resolve all mypy errors across crewai package
+  - Fix memory saving in agent
+  - Fix usage of __router_paths__ for listener+router methods in FlowMeta
+  - Raise value error on no file support
+  - Correct litellm quarantine wording in docs
+  - Use None check instead of isinstance for memory in human feedback learn
+  - Pin litellm upper bound to last tested version (1.82.6)
+
+  ### Documentation
+  - Update changelog and version for v1.12.0
+  - Add CONTRIBUTING.md
+  - Add guide for using CrewAI without LiteLLM
+
+  ### Refactoring
+  - Refactor to deduplicate sync/async task execution and kickoff in agent
+  - Simplify internal plumbing from litellm (token counting, callbacks, feature detection, errors)
+
+  ## Contributors
+
+  @akaKuruma, @alex-clawd, @greysonlalonde, @iris-clawd, @joaomdmoura, @lorenzejay, @nicoferdi96
+
+</Update>
+
 <Update label="Mar 26, 2026">
   ## v1.12.0a3
 

docs/en/concepts/agent-capabilities.mdx

@@ -0,0 +1,147 @@
+---
+title: "Agent Capabilities"
+description: "Understand the five ways to extend CrewAI agents: Tools, MCPs, Apps, Skills, and Knowledge."
+icon: puzzle-piece
+mode: "wide"
+---
+
+## Overview
+
+CrewAI agents can be extended with **five distinct capability types**, each serving a different purpose. Understanding when to use each one — and how they work together — is key to building effective agents.
+
+<CardGroup cols={2}>
+  <Card title="Tools" icon="wrench" href="/en/concepts/tools" color="#3B82F6">
+    **Callable functions** — give agents the ability to take action. Web searches, file operations, API calls, code execution.
+  </Card>
+  <Card title="MCP Servers" icon="plug" href="/en/mcp/overview" color="#8B5CF6">
+    **Remote tool servers** — connect agents to external tool servers via the Model Context Protocol. Same effect as tools, but hosted externally.
+  </Card>
+  <Card title="Apps" icon="grid-2" color="#EC4899">
+    **Platform integrations** — connect agents to SaaS apps (Gmail, Slack, Jira, Salesforce) via CrewAI's managed OAuth layer.
+  </Card>
+  <Card title="Skills" icon="bolt" href="/en/concepts/skills" color="#F59E0B">
+    **Domain expertise** — inject instructions, guidelines, and reference material into agent prompts. Skills tell agents *how to think*.
+  </Card>
+  <Card title="Knowledge" icon="book" href="/en/concepts/knowledge" color="#10B981">
+    **Retrieved facts** — provide agents with data from documents, files, and URLs via semantic search (RAG). Knowledge gives agents *what to know*.
+  </Card>
+</CardGroup>
+
+---
+
+## The Key Distinction
+
+The most important thing to understand: **these capabilities fall into two categories**.
+
+### Action Capabilities (Tools, MCPs, Apps)
+
+These give agents the ability to **do things** — call APIs, read files, search the web, send emails. At execution time, all three resolve into the same internal format (`BaseTool` instances) and appear in a unified tool list the agent can call.
+
+```python
+from crewai import Agent
+from crewai_tools import SerperDevTool, FileReadTool
+
+agent = Agent(
+    role="Researcher",
+    goal="Find and compile market data",
+    backstory="Expert market analyst",
+    tools=[SerperDevTool(), FileReadTool()],  # Local tools
+    mcps=["https://mcp.example.com/sse"],     # Remote MCP server tools
+    apps=["gmail", "google_sheets"],           # Platform integrations
+)
+```
+
+### Context Capabilities (Skills, Knowledge)
+
+These modify the agent's **prompt** — injecting expertise, instructions, or retrieved data before the agent starts reasoning. They don't give agents new actions; they shape how agents think and what information they have access to.
+
+```python
+from crewai import Agent
+
+agent = Agent(
+    role="Security Auditor",
+    goal="Audit cloud infrastructure for vulnerabilities",
+    backstory="Expert in cloud security with 10 years of experience",
+    skills=["./skills/security-audit"],        # Domain instructions
+    knowledge_sources=[pdf_source, url_source], # Retrieved facts
+)
+```
+
+---
+
+## When to Use What
+
+| You need...                                       | Use               | Example                                  |
+| :------------------------------------------------ | :---------------- | :--------------------------------------- |
+| Agent to search the web                           | **Tools**         | `tools=[SerperDevTool()]`                |
+| Agent to call a remote API via MCP                | **MCPs**          | `mcps=["https://api.example.com/sse"]`   |
+| Agent to send emails via Gmail                    | **Apps**          | `apps=["gmail"]`                         |
+| Agent to follow specific procedures               | **Skills**        | `skills=["./skills/code-review"]`        |
+| Agent to reference company docs                   | **Knowledge**     | `knowledge_sources=[pdf_source]`         |
+| Agent to search the web AND follow review guidelines | **Tools + Skills** | Use both together                     |
+
+---
+
+## Combining Capabilities
+
+In practice, agents often use **multiple capability types together**. Here's a realistic example:
+
+```python
+from crewai import Agent
+from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool
+
+# A fully-equipped research agent
+researcher = Agent(
+    role="Senior Research Analyst",
+    goal="Produce comprehensive market analysis reports",
+    backstory="Expert analyst with deep industry knowledge",
+
+    # ACTION: What the agent can DO
+    tools=[
+        SerperDevTool(),         # Search the web
+        FileReadTool(),          # Read local files
+        CodeInterpreterTool(),   # Run Python code for analysis
+    ],
+    mcps=["https://data-api.example.com/sse"],  # Access remote data API
+    apps=["google_sheets"],                      # Write to Google Sheets
+
+    # CONTEXT: What the agent KNOWS
+    skills=["./skills/research-methodology"],    # How to conduct research
+    knowledge_sources=[company_docs],            # Company-specific data
+)
+```
+
+---
+
+## Comparison Table
+
+| Feature | Tools | MCPs | Apps | Skills | Knowledge |
+| :--- | :---: | :---: | :---: | :---: | :---: |
+| **Gives agent actions** | ✅ | ✅ | ✅ | ❌ | ❌ |
+| **Modifies prompt** | ❌ | ❌ | ❌ | ✅ | ✅ |
+| **Requires code** | Yes | Config only | Config only | Markdown only | Config only |
+| **Runs locally** | Yes | Depends | No (AMP API) | N/A | Yes |
+| **Needs API keys** | Per tool | Per server | OAuth via AMP | No | Embedder only |
+| **Set on Agent** | `tools=[]` | `mcps=[]` | `apps=[]` | `skills=[]` | `knowledge_sources=[]` |
+| **Set on Crew** | ❌ | ❌ | ❌ | `skills=[]` | `knowledge_sources=[]` |
+
+---
+
+## Deep Dives
+
+Ready to learn more about each capability type?
+
+<CardGroup cols={2}>
+  <Card title="Tools" icon="wrench" href="/en/concepts/tools">
+    Create custom tools, use the 75+ OSS catalog, configure caching and async execution.
+  </Card>
+  <Card title="MCP Integration" icon="plug" href="/en/mcp/overview">
+    Connect to MCP servers via stdio, SSE, or HTTP. Filter tools, configure auth.
+  </Card>
+  <Card title="Skills" icon="bolt" href="/en/concepts/skills">
+    Build skill packages with SKILL.md, inject domain expertise, use progressive disclosure.
+  </Card>
+  <Card title="Knowledge" icon="book" href="/en/concepts/knowledge">
+    Add knowledge from PDFs, CSVs, URLs, and more. Configure embedders and retrieval.
+  </Card>
+</CardGroup>

docs/en/concepts/skills.mdx

@@ -1,27 +1,186 @@
 ---
 title: Skills
-description: Filesystem-based skill packages that inject context into agent prompts.
+description: Filesystem-based skill packages that inject domain expertise and instructions into agent prompts.
 icon: bolt
 mode: "wide"
 ---
 
 ## Overview
 
-Skills are self-contained directories that provide agents with domain-specific instructions, references, and assets. Each skill is defined by a `SKILL.md` file with YAML frontmatter and a markdown body.
+Skills are self-contained directories that provide agents with **domain-specific instructions, guidelines, and reference material**. Each skill is defined by a `SKILL.md` file with YAML frontmatter and a markdown body.
 
-Skills use **progressive disclosure** — metadata is loaded first, full instructions only when activated, and resource catalogs only when needed.
+When activated, a skill's instructions are injected directly into the agent's task prompt — giving the agent expertise without requiring any code changes.
 
-## Directory Structure
+<Note type="info" title="Skills vs Tools — The Key Distinction">
+**Skills are NOT tools.** This is the most common point of confusion.
+
+- **Skills** inject *instructions and context* into the agent's prompt. They tell the agent *how to think* about a problem.
+- **Tools** give the agent *callable functions* to take action (search, read files, call APIs).
+
+You often need **both**: skills for expertise, tools for action. They are configured independently and complement each other.
+</Note>
+
+---
+
+## Quick Start
+
+### 1. Create a Skill Directory
 
 ```
-my-skill/
-├── SKILL.md            # Required — frontmatter + instructions
-├── scripts/            # Optional — executable scripts
-├── references/         # Optional — reference documents
-└── assets/             # Optional — static files (configs, data)
+skills/
+└── code-review/
+    ├── SKILL.md          # Required — instructions
+    ├── references/       # Optional — reference docs
+    │   └── style-guide.md
+    └── scripts/          # Optional — executable scripts
 ```
 
-The directory name must match the `name` field in `SKILL.md`.
+### 2. Write Your SKILL.md
+
+```markdown
+---
+name: code-review
+description: Guidelines for conducting thorough code reviews with focus on security and performance.
+metadata:
+  author: your-team
+  version: "1.0"
+---
+
+## Code Review Guidelines
+
+When reviewing code, follow this checklist:
+
+1. **Security**: Check for injection vulnerabilities, auth bypasses, and data exposure
+2. **Performance**: Look for N+1 queries, unnecessary allocations, and blocking calls
+3. **Readability**: Ensure clear naming, appropriate comments, and consistent style
+4. **Testing**: Verify adequate test coverage for new functionality
+
+### Severity Levels
+- **Critical**: Security vulnerabilities, data loss risks → block merge
+- **Major**: Performance issues, logic errors → request changes
+- **Minor**: Style issues, naming suggestions → approve with comments
+```
+
+### 3. Attach to an Agent
+
+```python
+from crewai import Agent
+from crewai_tools import GithubSearchTool, FileReadTool
+
+reviewer = Agent(
+    role="Senior Code Reviewer",
+    goal="Review pull requests for quality and security issues",
+    backstory="Staff engineer with expertise in secure coding practices.",
+    skills=["./skills"],                          # Injects review guidelines
+    tools=[GithubSearchTool(), FileReadTool()],   # Lets agent read code
+)
+```
+
+The agent now has both **expertise** (from the skill) and **capabilities** (from the tools).
+
+---
+
+## Skills + Tools: Working Together
+
+Here are common patterns showing how skills and tools complement each other:
+
+### Pattern 1: Skills Only (Domain Expertise, No Actions Needed)
+
+Use when the agent needs specific instructions but doesn't need to call external services:
+
+```python
+agent = Agent(
+    role="Technical Writer",
+    goal="Write clear API documentation",
+    backstory="Expert technical writer",
+    skills=["./skills/api-docs-style"],  # Writing guidelines and templates
+    # No tools needed — agent writes based on provided context
+)
+```
+
+### Pattern 2: Tools Only (Actions, No Special Expertise)
+
+Use when the agent needs to take action but doesn't need domain-specific instructions:
+
+```python
+from crewai_tools import SerperDevTool, ScrapeWebsiteTool
+
+agent = Agent(
+    role="Web Researcher",
+    goal="Find information about a topic",
+    backstory="Skilled at finding information online",
+    tools=[SerperDevTool(), ScrapeWebsiteTool()],  # Can search and scrape
+    # No skills needed — general research doesn't need special guidelines
+)
+```
+
+### Pattern 3: Skills + Tools (Expertise AND Actions)
+
+The most common real-world pattern. The skill provides *how* to approach the work; tools provide *what* the agent can do:
+
+```python
+from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool
+
+analyst = Agent(
+    role="Security Analyst",
+    goal="Audit infrastructure for vulnerabilities",
+    backstory="Expert in cloud security and compliance",
+    skills=["./skills/security-audit"],   # Audit methodology and checklists
+    tools=[
+        SerperDevTool(),                  # Research known vulnerabilities
+        FileReadTool(),                   # Read config files
+        CodeInterpreterTool(),            # Run analysis scripts
+    ],
+)
+```
+
+### Pattern 4: Skills + MCPs
+
+Skills work alongside MCP servers the same way they work with tools:
+
+```python
+agent = Agent(
+    role="Data Analyst",
+    goal="Analyze customer data and generate reports",
+    backstory="Expert data analyst with strong statistical background",
+    skills=["./skills/data-analysis"],           # Analysis methodology
+    mcps=["https://data-warehouse.example.com/sse"],  # Remote data access
+)
+```
+
+### Pattern 5: Skills + Apps
+
+Skills can guide how an agent uses platform integrations:
+
+```python
+agent = Agent(
+    role="Customer Support Agent",
+    goal="Respond to customer inquiries professionally",
+    backstory="Experienced support representative",
+    skills=["./skills/support-playbook"],  # Response templates and escalation rules
+    apps=["gmail", "zendesk"],             # Can send emails and update tickets
+)
+```
+
+---
+
+## Crew-Level Skills
+
+Skills can be set on a crew to apply to **all agents**:
+
+```python
+from crewai import Crew
+
+crew = Crew(
+    agents=[researcher, writer, reviewer],
+    tasks=[research_task, write_task, review_task],
+    skills=["./skills"],  # All agents get these skills
+)
+```
+
+Agent-level skills take priority — if the same skill is discovered at both levels, the agent's version is used.
+
+---
 
 ## SKILL.md Format
 
@@ -34,7 +193,7 @@ compatibility: crewai>=0.1.0          # optional
 metadata:                              # optional
   author: your-name
   version: "1.0"
-allowed-tools: web-search file-read   # optional, space-delimited
+allowed-tools: web-search file-read   # optional, experimental
 ---
 
 Instructions for the agent go here. This markdown body is injected
@@ -43,57 +202,46 @@ into the agent's prompt when the skill is activated.
 
 ### Frontmatter Fields
 
-| Field           | Required | Constraints                                                              |
+| Field           | Required | Description                                                              |
 | :-------------- | :------- | :----------------------------------------------------------------------- |
-| `name`          | Yes      | 1–64 chars. Lowercase alphanumeric and hyphens. No leading/trailing/consecutive hyphens. Must match directory name. |
+| `name`          | Yes      | 1–64 chars. Lowercase alphanumeric and hyphens. Must match directory name. |
 | `description`   | Yes      | 1–1024 chars. Describes what the skill does and when to use it.          |
 | `license`       | No       | License name or reference to a bundled license file.                     |
 | `compatibility` | No       | Max 500 chars. Environment requirements (products, packages, network).   |
 | `metadata`      | No       | Arbitrary string key-value mapping.                                      |
 | `allowed-tools` | No       | Space-delimited list of pre-approved tools. Experimental.                |
 
-## Usage
+---
 
-### Agent-level Skills
+## Directory Structure
 
-Pass skill directory paths to an agent:
-
-```python
-from crewai import Agent
-
-agent = Agent(
-    role="Researcher",
-    goal="Find relevant information",
-    backstory="An expert researcher.",
-    skills=["./skills"],  # discovers all skills in this directory
-)
+```
+my-skill/
+├── SKILL.md            # Required — frontmatter + instructions
+├── scripts/            # Optional — executable scripts
+├── references/         # Optional — reference documents
+└── assets/             # Optional — static files (configs, data)
 ```
 
-### Crew-level Skills
+The directory name must match the `name` field in `SKILL.md`. The `scripts/`, `references/`, and `assets/` directories are available on the skill's `path` for agents that need to reference files directly.
 
-Skill paths on a crew are merged into every agent:
+---
 
-```python
-from crewai import Crew
+## Pre-loading Skills
 
-crew = Crew(
-    agents=[agent],
-    tasks=[task],
-    skills=["./skills"],
-)
-```
-
-### Pre-loaded Skills
-
-You can also pass `Skill` objects directly:
+For more control, you can discover and activate skills programmatically:
 
 ```python
 from pathlib import Path
 from crewai.skills import discover_skills, activate_skill
 
+# Discover all skills in a directory
 skills = discover_skills(Path("./skills"))
+
+# Activate them (loads full SKILL.md body)
 activated = [activate_skill(s) for s in skills]
 
+# Pass to an agent
 agent = Agent(
     role="Researcher",
     goal="Find relevant information",
@@ -102,14 +250,57 @@ agent = Agent(
 )
 ```
 
+---
+
 ## How Skills Are Loaded
 
-Skills load progressively — only the data needed at each stage is read:
+Skills use **progressive disclosure** — only loading what's needed at each stage:
 
-| Stage            | What's loaded                                     | When               |
-| :--------------- | :------------------------------------------------ | :----------------- |
-| Discovery        | Name, description, frontmatter fields             | `discover_skills()` |
-| Activation       | Full SKILL.md body text                           | `activate_skill()` |
+| Stage      | What's loaded                         | When                |
+| :--------- | :------------------------------------ | :------------------ |
+| Discovery  | Name, description, frontmatter fields | `discover_skills()` |
+| Activation | Full SKILL.md body text               | `activate_skill()`  |
 
-During normal agent execution, skills are automatically discovered and activated. The `scripts/`, `references/`, and `assets/` directories are available on the skill's `path` for agents that need to reference files directly.
+During normal agent execution (passing directory paths via `skills=["./skills"]`), skills are automatically discovered and activated. The progressive loading only matters when using the programmatic API.
 
+---
+
+## Skills vs Knowledge
+
+Both skills and knowledge modify the agent's prompt, but they serve different purposes:
+
+| Aspect | Skills | Knowledge |
+| :--- | :--- | :--- |
+| **What it provides** | Instructions, procedures, guidelines | Facts, data, information |
+| **How it's stored** | Markdown files (SKILL.md) | Embedded in vector store (ChromaDB) |
+| **How it's retrieved** | Entire body injected into prompt | Semantic search finds relevant chunks |
+| **Best for** | Methodology, checklists, style guides | Company docs, product info, reference data |
+| **Set via** | `skills=["./skills"]` | `knowledge_sources=[source]` |
+
+**Rule of thumb:** If the agent needs to follow a *process*, use a skill. If the agent needs to reference *data*, use knowledge.
+
+---
+
+## Common Questions
+
+<AccordionGroup>
+  <Accordion title="Do I need to set skills AND tools?">
+    It depends on your use case. Skills and tools are **independent** — you can use either, both, or neither.
+
+    - **Skills alone**: When the agent needs expertise but no external actions (e.g., writing with style guidelines)
+    - **Tools alone**: When the agent needs actions but no special methodology (e.g., simple web search)
+    - **Both**: When the agent needs expertise AND actions (e.g., security audit with specific checklists AND ability to scan code)
+  </Accordion>
+
+  <Accordion title="Do skills automatically provide tools?">
+    **No.** The `allowed-tools` field in SKILL.md is experimental metadata only — it does not provision or inject any tools. You must always set tools separately via `tools=[]`, `mcps=[]`, or `apps=[]`.
+  </Accordion>
+
+  <Accordion title="What happens if I set the same skill on both an agent and its crew?">
+    The agent-level skill takes priority. Skills are deduplicated by name — the agent's skills are processed first, so if the same skill name appears at both levels, the agent's version is used.
+  </Accordion>
+
+  <Accordion title="How large can a SKILL.md body be?">
+    There's a soft warning at 50,000 characters, but no hard limit. Keep skills focused and concise for best results — large prompt injections can dilute the agent's attention.
+  </Accordion>
+</AccordionGroup>

docs/en/concepts/tools.mdx

@@ -10,6 +10,10 @@ mode: "wide"
 CrewAI tools empower agents with capabilities ranging from web searching and data analysis to collaboration and delegating tasks among coworkers.
 This documentation outlines how to create, integrate, and leverage these tools within the CrewAI framework, including a new focus on collaboration tools.
 
+<Note type="info" title="Tools are one of five agent capability types">
+  Tools give agents **callable functions** to take action. They work alongside [MCPs](/en/mcp/overview) (remote tool servers), [Apps](/en/concepts/agent-capabilities) (platform integrations), [Skills](/en/concepts/skills) (domain expertise), and [Knowledge](/en/concepts/knowledge) (retrieved facts). See the [Agent Capabilities](/en/concepts/agent-capabilities) overview to understand when to use each.
+</Note>
+
 ## What is a Tool?
 
 A tool in CrewAI is a skill or function that agents can utilize to perform various actions.

docs/en/enterprise/features/rbac.mdx

@@ -7,11 +7,13 @@ mode: "wide"
 
 ## Overview
 
-RBAC in CrewAI AMP enables secure, scalable access management through a combination of organization‑level roles and automation‑level visibility controls.
+RBAC in CrewAI AMP enables secure, scalable access management through two layers:
+
+1. **Feature permissions** — control what each role can do across the platform (manage, read, or no access)
+2. **Entity-level permissions** — fine-grained access on individual automations, environment variables, LLM connections, and Git repositories
 
 <Frame>
   <img src="/images/enterprise/users_and_roles.png" alt="RBAC overview in CrewAI AMP" />
-
 </Frame>
 
 ## Users and Roles
@@ -39,6 +41,13 @@ You can configure users and roles in Settings → Roles.
   </Step>
 </Steps>
 
+### Predefined Roles
+
+| Role       | Description                                                                 |
+| :--------- | :-------------------------------------------------------------------------- |
+| **Owner**  | Full access to all features and settings. Cannot be restricted.             |
+| **Member** | Read access to most features, manage access to Studio projects. Cannot modify organization or default settings. |
+
 ### Configuration summary
 
 | Area                  | Where to configure                 | Options                                 |
@@ -46,23 +55,80 @@ You can configure users and roles in Settings → Roles.
 | Users & Roles         | Settings → Roles                   | Predefined: Owner, Member; Custom roles |
 | Automation visibility | Automation → Settings → Visibility | Private; Whitelist users/roles          |
 
-## Automation‑level Access Control
+---
 
-In addition to organization‑wide roles, CrewAI Automations support fine‑grained visibility settings that let you restrict access to specific automations by user or role.
+## Feature Permissions Matrix
 
-This is useful for:
+Every role has a permission level for each feature area. The three levels are:
+
+- **Manage** — full read/write access (create, edit, delete)
+- **Read** — view-only access
+- **No access** — feature is hidden/inaccessible
+
+| Feature                   | Owner   | Member (default) | Description                                                     |
+| :------------------------ | :------ | :--------------- | :-------------------------------------------------------------- |
+| `usage_dashboards`        | Manage  | Read             | View usage metrics and analytics                                |
+| `crews_dashboards`        | Manage  | Read             | View deployment dashboards, access automation details           |
+| `invitations`             | Manage  | Read             | Invite new members to the organization                          |
+| `training_ui`             | Manage  | Read             | Access training/fine-tuning interfaces                          |
+| `tools`                   | Manage  | Read             | Create and manage tools                                         |
+| `agents`                  | Manage  | Read             | Create and manage agents                                        |
+| `environment_variables`   | Manage  | Read             | Create and manage environment variables                         |
+| `llm_connections`         | Manage  | Read             | Configure LLM provider connections                              |
+| `default_settings`        | Manage  | No access        | Modify organization-wide default settings                       |
+| `organization_settings`   | Manage  | No access        | Manage billing, plans, and organization configuration           |
+| `studio_projects`         | Manage  | Manage           | Create and edit projects in Studio                              |
+
+<Tip>
+  When creating a custom role, you can set each feature independently to **Manage**, **Read**, or **No access** to match your team's needs.
+</Tip>
+
+---
+
+## Deploying from GitHub or Zip
+
+One of the most common RBAC questions is: _"What permissions does a team member need to deploy?"_
+
+### Deploy from GitHub
+
+To deploy an automation from a GitHub repository, a user needs:
+
+1. **`crews_dashboards`**: at least `Read` — required to access the automations dashboard where deployments are created
+2. **Git repository access** (if entity-level RBAC for Git repositories is enabled): the user's role must be granted access to the specific Git repository via entity-level permissions
+3. **`studio_projects`: `Manage`** — if building the crew in Studio before deploying
+
+### Deploy from Zip
+
+To deploy an automation from a Zip file upload, a user needs:
+
+1. **`crews_dashboards`**: at least `Read` — required to access the automations dashboard
+2. **Zip deployments enabled**: the organization must not have disabled zip deployments in organization settings
+
+### Quick Reference: Minimum Permissions for Deployment
+
+| Action               | Required feature permissions          | Additional requirements                          |
+| :------------------- | :------------------------------------ | :----------------------------------------------- |
+| Deploy from GitHub   | `crews_dashboards: Read`              | Git repo entity access (if Git RBAC is enabled)  |
+| Deploy from Zip      | `crews_dashboards: Read`              | Zip deployments must be enabled at the org level |
+| Build in Studio      | `studio_projects: Manage`             | —                                                |
+| Configure LLM keys   | `llm_connections: Manage`             | —                                                |
+| Set environment vars  | `environment_variables: Manage`       | Entity-level access (if entity RBAC is enabled)  |
+
+---
+
+## Automation‑level Access Control (Entity Permissions)
+
+In addition to organization‑wide roles, CrewAI supports fine‑grained entity-level permissions that restrict access to individual resources.
+
+### Automation Visibility
+
+Automations support visibility settings that restrict access by user or role. This is useful for:
 
 - Keeping sensitive or experimental automations private
 - Managing visibility across large teams or external collaborators
 - Testing automations in isolated contexts
 
-Deployments can be configured as private, meaning only whitelisted users and roles will be able to:
-
-- View the deployment
-- Run it or interact with its API
-- Access its logs, metrics, and settings
-
-The organization owner always has access, regardless of visibility settings.
+Deployments can be configured as private, meaning only whitelisted users and roles will be able to interact with them.
 
 You can configure automation‑level access control in Automation → Settings → Visibility tab.
 
@@ -99,9 +165,92 @@ You can configure automation‑level access control in Automation → Settings
 
 <Frame>
   <img src="/images/enterprise/visibility.png" alt="Automation Visibility settings in CrewAI AMP" />
-
 </Frame>
 
+### Deployment Permission Types
+
+When granting entity-level access to a specific automation, you can assign these permission types:
+
+| Permission           | What it allows                                      |
+| :------------------- | :-------------------------------------------------- |
+| `run`                | Execute the automation and use its API               |
+| `traces`             | View execution traces and logs                       |
+| `manage_settings`    | Edit, redeploy, rollback, or delete the automation   |
+| `human_in_the_loop`  | Respond to human-in-the-loop (HITL) requests         |
+| `full_access`        | All of the above                                     |
+
+### Entity-level RBAC for Other Resources
+
+When entity-level RBAC is enabled, access to these resources can also be controlled per user or role:
+
+| Resource               | Controlled by                    | Description                                           |
+| :--------------------- | :------------------------------- | :---------------------------------------------------- |
+| Environment variables  | Entity RBAC feature flag         | Restrict which roles/users can view or manage specific env vars |
+| LLM connections        | Entity RBAC feature flag         | Restrict access to specific LLM provider configurations |
+| Git repositories       | Git repositories RBAC org setting | Restrict which roles/users can access specific connected repos |
+
+---
+
+## Common Role Patterns
+
+While CrewAI ships with Owner and Member roles, most teams benefit from creating custom roles. Here are common patterns:
+
+### Developer Role
+
+A role for team members who build and deploy automations but don't manage organization settings.
+
+| Feature                   | Permission |
+| :------------------------ | :--------- |
+| `usage_dashboards`        | Read       |
+| `crews_dashboards`        | Manage     |
+| `invitations`             | Read       |
+| `training_ui`             | Read       |
+| `tools`                   | Manage     |
+| `agents`                  | Manage     |
+| `environment_variables`   | Manage     |
+| `llm_connections`         | Read       |
+| `default_settings`        | No access  |
+| `organization_settings`   | No access  |
+| `studio_projects`         | Manage     |
+
+### Viewer / Stakeholder Role
+
+A role for non-technical stakeholders who need to monitor automations and view results.
+
+| Feature                   | Permission |
+| :------------------------ | :--------- |
+| `usage_dashboards`        | Read       |
+| `crews_dashboards`        | Read       |
+| `invitations`             | No access  |
+| `training_ui`             | Read       |
+| `tools`                   | Read       |
+| `agents`                  | Read       |
+| `environment_variables`   | No access  |
+| `llm_connections`         | No access  |
+| `default_settings`        | No access  |
+| `organization_settings`   | No access  |
+| `studio_projects`         | Read       |
+
+### Ops / Platform Admin Role
+
+A role for platform operators who manage infrastructure settings but may not build agents.
+
+| Feature                   | Permission |
+| :------------------------ | :--------- |
+| `usage_dashboards`        | Manage     |
+| `crews_dashboards`        | Manage     |
+| `invitations`             | Manage     |
+| `training_ui`             | Read       |
+| `tools`                   | Read       |
+| `agents`                  | Read       |
+| `environment_variables`   | Manage     |
+| `llm_connections`         | Manage     |
+| `default_settings`        | Manage     |
+| `organization_settings`   | Read       |
+| `studio_projects`         | Read       |
+
+---
+
 <Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
   Contact our support team for assistance with RBAC questions.
 </Card>

docs/en/enterprise/features/sso.mdx

@@ -0,0 +1,550 @@
+---
+title: Single Sign-On (SSO)
+icon: "key"
+description: Configure enterprise SSO authentication for CrewAI Platform — SaaS and Factory
+---
+
+## Overview
+
+CrewAI Platform supports enterprise Single Sign-On (SSO) across both **SaaS (AMP)** and **Factory (self-hosted)** deployments. SSO enables your team to authenticate using your organization's existing identity provider, enforcing centralized access control, MFA policies, and user lifecycle management.
+
+### Supported Providers
+
+| Provider | SaaS | Factory | Protocol | CLI Support |
+|---|---|---|---|---|
+| **WorkOS** | ✅ (default) | ✅ | OAuth 2.0 / OIDC | ✅ |
+| **Microsoft Entra ID** (Azure AD) | ✅ (enterprise) | ✅ | OAuth 2.0 / SAML 2.0 | ✅ |
+| **Okta** | ✅ (enterprise) | ✅ | OAuth 2.0 / OIDC | ✅ |
+| **Auth0** | ✅ (enterprise) | ✅ | OAuth 2.0 / OIDC | ✅ |
+| **Keycloak** | — | ✅ | OAuth 2.0 / OIDC | ✅ |
+
+### Key Capabilities
+
+- **SAML 2.0 and OAuth 2.0 / OIDC** protocol support
+- **Device Authorization Grant** flow for CLI authentication
+- **Role-Based Access Control (RBAC)** with custom roles and per-resource permissions
+- **MFA enforcement** delegated to your identity provider
+- **User provisioning** through IdP assignment (users/groups)
+
+---
+
+## SaaS SSO
+
+### Default Authentication
+
+CrewAI's managed SaaS platform (AMP) uses **WorkOS** as the default authentication provider. When you sign up at [app.crewai.com](https://app.crewai.com), authentication is handled through `login.crewai.com` — no additional SSO configuration is required.
+
+### Enterprise Custom SSO
+
+Enterprise SaaS customers can configure SSO with their own identity provider (Entra ID, Okta, Auth0). Contact your CrewAI account team to enable custom SSO for your organization. Once configured:
+
+1. Your team members authenticate through your organization's IdP
+2. Access control and MFA policies are enforced by your IdP
+3. The CrewAI CLI automatically detects your SSO configuration via `crewai enterprise configure`
+
+### CLI Defaults (SaaS)
+
+| Setting | Default Value |
+|---|---|
+| `enterprise_base_url` | `https://app.crewai.com` |
+| `oauth2_provider` | `workos` |
+| `oauth2_domain` | `login.crewai.com` |
+
+---
+
+## Factory SSO Setup
+
+Factory (self-hosted) deployments require you to configure SSO by setting environment variables in your Helm `values.yaml` and registering an application in your identity provider.
+
+### Microsoft Entra ID (Azure AD)
+
+<Steps>
+  <Step title="Register an Application">
+    1. Go to [portal.azure.com](https://portal.azure.com) → **Microsoft Entra ID** → **App registrations** → **New registration**
+    2. Configure:
+       - **Name:** `CrewAI` (or your preferred name)
+       - **Supported account types:** Accounts in this organizational directory only
+       - **Redirect URI:** Select **Web**, enter `https://<your-domain>/auth/entra_id/callback`
+    3. Click **Register**
+  </Step>
+
+  <Step title="Collect Credentials">
+    From the app overview page, copy:
+    - **Application (client) ID** → `ENTRA_ID_CLIENT_ID`
+    - **Directory (tenant) ID** → `ENTRA_ID_TENANT_ID`
+  </Step>
+
+  <Step title="Create Client Secret">
+    1. Navigate to **Certificates & Secrets** → **New client secret**
+    2. Add a description and select expiration period
+    3. Copy the secret value immediately (it won't be shown again) → `ENTRA_ID_CLIENT_SECRET`
+  </Step>
+
+  <Step title="Grant Admin Consent">
+    1. Go to **Enterprise applications** → select your app
+    2. Under **Security** → **Permissions**, click **Grant admin consent**
+    3. Ensure **Microsoft Graph → User.Read** is granted
+  </Step>
+
+  <Step title="Configure App Roles (Recommended)">
+    Under **App registrations** → your app → **App roles**, create:
+
+    | Display Name | Value | Allowed Member Types |
+    |---|---|---|
+    | Member | `member` | Users/Groups |
+    | Factory Admin | `factory-admin` | Users/Groups |
+
+    <Note>
+      The `member` role grants login access. The `factory-admin` role grants admin panel access. Roles are included in the JWT automatically.
+    </Note>
+  </Step>
+
+  <Step title="Assign Users">
+    1. Under **Properties**, set **Assignment required?** to **Yes**
+    2. Under **Users and groups**, assign users/groups with the appropriate role
+  </Step>
+
+  <Step title="Set Environment Variables">
+    ```yaml
+    envVars:
+      AUTH_PROVIDER: "entra_id"
+
+    secrets:
+      ENTRA_ID_CLIENT_ID: "<Application (client) ID>"
+      ENTRA_ID_CLIENT_SECRET: "<Client Secret>"
+      ENTRA_ID_TENANT_ID: "<Directory (tenant) ID>"
+    ```
+  </Step>
+
+  <Step title="Enable CLI Support (Optional)">
+    To allow `crewai login` via Device Authorization Grant:
+
+    1. Under **Authentication** → **Advanced settings**, enable **Allow public client flows**
+    2. Under **Expose an API**, add an Application ID URI (e.g., `api://crewai-cli`)
+    3. Add a scope (e.g., `read`) with **Admins and users** consent
+    4. Under **Manifest**, set `accessTokenAcceptedVersion` to `2`
+    5. Add environment variables:
+
+    ```yaml
+    secrets:
+      ENTRA_ID_DEVICE_AUTHORIZATION_CLIENT_ID: "<Application (client) ID>"
+      ENTRA_ID_CUSTOM_OPENID_SCOPE: "<scope URI, e.g. api://crewai-cli/read>"
+    ```
+  </Step>
+</Steps>
+
+---
+
+### Okta
+
+<Steps>
+  <Step title="Create App Integration">
+    1. Open Okta Admin Console → **Applications** → **Create App Integration**
+    2. Select **OIDC - OpenID Connect** → **Web Application** → **Next**
+    3. Configure:
+       - **App integration name:** `CrewAI SSO`
+       - **Sign-in redirect URI:** `https://<your-domain>/auth/okta/callback`
+       - **Sign-out redirect URI:** `https://<your-domain>`
+       - **Assignments:** Choose who can access (everyone or specific groups)
+    4. Click **Save**
+  </Step>
+
+  <Step title="Collect Credentials">
+    From the app details page:
+    - **Client ID** → `OKTA_CLIENT_ID`
+    - **Client Secret** → `OKTA_CLIENT_SECRET`
+    - **Okta URL** (top-right corner, under your username) → `OKTA_SITE`
+  </Step>
+
+  <Step title="Configure Authorization Server">
+    1. Navigate to **Security** → **API**
+    2. Select your authorization server (default: `default`)
+    3. Under **Access Policies**, add a policy and rule:
+       - In the rule, under **Scopes requested**, select **The following scopes** → **OIDC default scopes**
+    4. Note the **Name** and **Audience** of the authorization server
+
+    <Warning>
+      The authorization server name and audience must match `OKTA_AUTHORIZATION_SERVER` and `OKTA_AUDIENCE` exactly. Mismatches cause `401 Unauthorized` or `Invalid token: Signature verification failed` errors.
+    </Warning>
+  </Step>
+
+  <Step title="Set Environment Variables">
+    ```yaml
+    envVars:
+      AUTH_PROVIDER: "okta"
+
+    secrets:
+      OKTA_CLIENT_ID: "<Okta app client ID>"
+      OKTA_CLIENT_SECRET: "<Okta client secret>"
+      OKTA_SITE: "https://your-domain.okta.com"
+      OKTA_AUTHORIZATION_SERVER: "default"
+      OKTA_AUDIENCE: "api://default"
+    ```
+  </Step>
+
+  <Step title="Enable CLI Support (Optional)">
+    1. Create a **new** app integration: **OIDC** → **Native Application**
+    2. Enable **Device Authorization** and **Refresh Token** grant types
+    3. Allow everyone in your organization to access
+    4. Add environment variable:
+
+    ```yaml
+    secrets:
+      OKTA_DEVICE_AUTHORIZATION_CLIENT_ID: "<Native app client ID>"
+    ```
+
+    <Note>
+      Device Authorization requires a **Native Application** — it cannot use the Web Application created for browser-based SSO.
+    </Note>
+  </Step>
+</Steps>
+
+---
+
+### Keycloak
+
+<Steps>
+  <Step title="Create a Client">
+    1. Open Keycloak Admin Console → navigate to your realm
+    2. **Clients** → **Create client**:
+       - **Client type:** OpenID Connect
+       - **Client ID:** `crewai-factory` (suggested)
+    3. Capability config:
+       - **Client authentication:** On
+       - **Standard flow:** Checked
+    4. Login settings:
+       - **Root URL:** `https://<your-domain>`
+       - **Valid redirect URIs:** `https://<your-domain>/auth/keycloak/callback`
+       - **Valid post logout redirect URIs:** `https://<your-domain>`
+    5. Click **Save**
+  </Step>
+
+  <Step title="Collect Credentials">
+    - **Client ID** → `KEYCLOAK_CLIENT_ID`
+    - Under **Credentials** tab: **Client secret** → `KEYCLOAK_CLIENT_SECRET`
+    - **Realm name** → `KEYCLOAK_REALM`
+    - **Keycloak server URL** → `KEYCLOAK_SITE`
+  </Step>
+
+  <Step title="Set Environment Variables">
+    ```yaml
+    envVars:
+      AUTH_PROVIDER: "keycloak"
+
+    secrets:
+      KEYCLOAK_CLIENT_ID: "<client ID>"
+      KEYCLOAK_CLIENT_SECRET: "<client secret>"
+      KEYCLOAK_SITE: "https://keycloak.yourdomain.com"
+      KEYCLOAK_REALM: "<realm name>"
+      KEYCLOAK_AUDIENCE: "account"
+      # Only set if using a custom base path (pre-v17 migrations):
+      # KEYCLOAK_BASE_URL: "/auth"
+    ```
+
+    <Note>
+      Keycloak includes `account` as the default audience in access tokens. For most installations, `KEYCLOAK_AUDIENCE=account` works without additional configuration. See [Keycloak audience documentation](https://www.keycloak.org/docs/latest/authorization_services/index.html) if you need a custom audience.
+    </Note>
+  </Step>
+
+  <Step title="Enable CLI Support (Optional)">
+    1. Create a **second** client:
+       - **Client type:** OpenID Connect
+       - **Client ID:** `crewai-factory-cli` (suggested)
+       - **Client authentication:** Off (Device Authorization requires a public client)
+       - **Authentication flow:** Check **only** OAuth 2.0 Device Authorization Grant
+    2. Add environment variable:
+
+    ```yaml
+    secrets:
+      KEYCLOAK_DEVICE_AUTHORIZATION_CLIENT_ID: "<CLI client ID>"
+    ```
+  </Step>
+</Steps>
+
+---
+
+### WorkOS
+
+<Steps>
+  <Step title="Configure in WorkOS Dashboard">
+    1. Create an application in the [WorkOS Dashboard](https://dashboard.workos.com)
+    2. Configure the redirect URI: `https://<your-domain>/auth/workos/callback`
+    3. Note the **Client ID** and **AuthKit domain**
+    4. Set up organizations in the WorkOS dashboard
+  </Step>
+
+  <Step title="Set Environment Variables">
+    ```yaml
+    envVars:
+      AUTH_PROVIDER: "workos"
+
+    secrets:
+      WORKOS_CLIENT_ID: "<WorkOS client ID>"
+      WORKOS_AUTHKIT_DOMAIN: "<your-authkit-domain.authkit.com>"
+    ```
+  </Step>
+</Steps>
+
+---
+
+### Auth0
+
+<Steps>
+  <Step title="Create Application">
+    1. In the [Auth0 Dashboard](https://manage.auth0.com), create a new **Regular Web Application**
+    2. Configure:
+       - **Allowed Callback URLs:** `https://<your-domain>/auth/auth0/callback`
+       - **Allowed Logout URLs:** `https://<your-domain>`
+    3. Note the **Domain**, **Client ID**, and **Client Secret**
+  </Step>
+
+  <Step title="Set Environment Variables">
+    ```yaml
+    envVars:
+      AUTH_PROVIDER: "auth0"
+
+    secrets:
+      AUTH0_CLIENT_ID: "<Auth0 client ID>"
+      AUTH0_CLIENT_SECRET: "<Auth0 client secret>"
+      AUTH0_DOMAIN: "<your-tenant.auth0.com>"
+    ```
+  </Step>
+
+  <Step title="Enable CLI Support (Optional)">
+    1. Create a **Native** application in Auth0 for Device Authorization
+    2. Enable the **Device Authorization** grant type under application settings
+    3. Configure the CLI with the appropriate audience and client ID
+  </Step>
+</Steps>
+
+---
+
+## CLI Authentication
+
+The CrewAI CLI supports SSO authentication via the **Device Authorization Grant** flow. This allows developers to authenticate from their terminal without exposing credentials.
+
+### Quick Setup
+
+For Factory installations, the CLI can auto-configure all OAuth2 settings:
+
+```bash
+crewai enterprise configure https://your-factory-url.app
+```
+
+This command fetches the SSO configuration from your Factory instance and sets all required CLI parameters automatically.
+
+Then authenticate:
+
+```bash
+crewai login
+```
+
+<Note>
+  Requires CrewAI CLI version **1.6.0** or higher for Entra ID, **0.159.0** or higher for Okta, and **1.9.0** or higher for Keycloak.
+</Note>
+
+### Manual CLI Configuration
+
+If you need to configure the CLI manually, use `crewai config set`:
+
+```bash
+# Set the provider
+crewai config set oauth2_provider okta
+
+# Set provider-specific values
+crewai config set oauth2_domain your-domain.okta.com
+crewai config set oauth2_client_id your-client-id
+crewai config set oauth2_audience api://default
+
+# Set the enterprise base URL
+crewai config set enterprise_base_url https://your-factory-url.app
+```
+
+### CLI Configuration Reference
+
+| Setting | Description | Example |
+|---|---|---|
+| `enterprise_base_url` | Your CrewAI instance URL | `https://crewai.yourcompany.com` |
+| `oauth2_provider` | Provider name | `workos`, `okta`, `auth0`, `entra_id`, `keycloak` |
+| `oauth2_domain` | Provider domain | `your-domain.okta.com` |
+| `oauth2_client_id` | OAuth2 client ID | `0oaqnwji7pGW7VT6T697` |
+| `oauth2_audience` | API audience identifier | `api://default` |
+
+View current configuration:
+
+```bash
+crewai config list
+```
+
+### How Device Authorization Works
+
+1. Run `crewai login` — the CLI requests a device code from your IdP
+2. A verification URL and code are displayed in your terminal
+3. Your browser opens to the verification URL
+4. Enter the code and authenticate with your IdP credentials
+5. The CLI receives an access token and stores it locally
+
+---
+
+## Role-Based Access Control (RBAC)
+
+CrewAI Platform provides granular RBAC that integrates with your SSO provider.
+
+### Permission Model
+
+| Permission | Description |
+|---|---|
+| **Read** | View resources (dashboards, automations, logs) |
+| **Write** | Create and modify resources |
+| **Manage** | Full control including deletion and configuration |
+
+### Resources
+
+Permissions can be scoped to individual resources:
+
+- **Usage Dashboard** — Platform usage metrics and analytics
+- **Automations Dashboard** — Crew and flow management
+- **Environment Variables** — Secret and configuration management
+- **Individual Automations** — Per-automation access control
+
+### Roles
+
+- **Predefined roles** come out of the box with standard permission sets
+- **Custom roles** can be created with any combination of permissions
+- **Per-resource assignment** — limit specific automations to individual users or roles
+
+### Factory Admin Access
+
+For Factory deployments using Entra ID, admin access is controlled via App Roles:
+
+- Assign the `factory-admin` role to users who need admin panel access
+- Assign the `member` role for standard platform access
+- Roles are communicated via JWT claims — no additional configuration needed after IdP setup
+
+---
+
+## Troubleshooting
+
+### Invalid Redirect URI
+
+**Symptom:** Authentication fails with a redirect URI mismatch error.
+
+**Fix:** Ensure the redirect URI in your IdP exactly matches the expected callback URL:
+
+| Provider | Callback URL |
+|---|---|
+| Entra ID | `https://<domain>/auth/entra_id/callback` |
+| Okta | `https://<domain>/auth/okta/callback` |
+| Keycloak | `https://<domain>/auth/keycloak/callback` |
+| WorkOS | `https://<domain>/auth/workos/callback` |
+| Auth0 | `https://<domain>/auth/auth0/callback` |
+
+### CLI Login Fails (Device Authorization)
+
+**Symptom:** `crewai login` returns an error or times out.
+
+**Fix:**
+- Verify that Device Authorization Grant is enabled in your IdP
+- For Okta: ensure you have a **Native Application** (not Web) with Device Authorization grant
+- For Entra ID: ensure **Allow public client flows** is enabled
+- For Keycloak: ensure the CLI client has **Client authentication: Off** and only Device Authorization Grant enabled
+- Check that `*_DEVICE_AUTHORIZATION_CLIENT_ID` environment variable is set on the server
+
+### Token Validation Errors
+
+**Symptom:** `Invalid token: Signature verification failed` or `401 Unauthorized` after login.
+
+**Fix:**
+- **Okta:** Verify `OKTA_AUTHORIZATION_SERVER` and `OKTA_AUDIENCE` match the authorization server's Name and Audience exactly
+- **Entra ID:** Ensure `accessTokenAcceptedVersion` is set to `2` in the app manifest
+- **Keycloak:** Verify `KEYCLOAK_AUDIENCE` matches the audience in your access tokens (default: `account`)
+
+### Admin Consent Not Granted (Entra ID)
+
+**Symptom:** Users can't log in, see "needs admin approval" message.
+
+**Fix:** Go to **Enterprise applications** → your app → **Permissions** → **Grant admin consent**. Ensure `User.Read` is granted for Microsoft Graph.
+
+### 403 Forbidden After Login
+
+**Symptom:** User authenticates successfully but gets 403 errors.
+
+**Fix:**
+- Check that the user is assigned to the application in your IdP
+- For Entra ID with **Assignment required = Yes**: ensure the user has a role assignment (Member or Factory Admin)
+- For Okta: verify the user or their group is assigned under the app's **Assignments** tab
+
+### CLI Can't Reach Factory Instance
+
+**Symptom:** `crewai enterprise configure` fails to connect.
+
+**Fix:**
+- Verify the Factory URL is reachable from your machine
+- Check that `enterprise_base_url` is set correctly: `crewai config list`
+- Ensure TLS certificates are valid and trusted
+
+---
+
+## Environment Variables Reference
+
+### Common
+
+| Variable | Description |
+|---|---|
+| `AUTH_PROVIDER` | Authentication provider: `entra_id`, `okta`, `workos`, `auth0`, `keycloak`, `local` |
+
+### Microsoft Entra ID
+
+| Variable | Required | Description |
+|---|---|---|
+| `ENTRA_ID_CLIENT_ID` | ✅ | Application (client) ID from Azure |
+| `ENTRA_ID_CLIENT_SECRET` | ✅ | Client secret from Azure |
+| `ENTRA_ID_TENANT_ID` | ✅ | Directory (tenant) ID from Azure |
+| `ENTRA_ID_DEVICE_AUTHORIZATION_CLIENT_ID` | CLI only | Client ID for Device Authorization Grant |
+| `ENTRA_ID_CUSTOM_OPENID_SCOPE` | CLI only | Custom scope from "Expose an API" (e.g., `api://crewai-cli/read`) |
+
+### Okta
+
+| Variable | Required | Description |
+|---|---|---|
+| `OKTA_CLIENT_ID` | ✅ | Okta application client ID |
+| `OKTA_CLIENT_SECRET` | ✅ | Okta client secret |
+| `OKTA_SITE` | ✅ | Okta organization URL (e.g., `https://your-domain.okta.com`) |
+| `OKTA_AUTHORIZATION_SERVER` | ✅ | Authorization server name (e.g., `default`) |
+| `OKTA_AUDIENCE` | ✅ | Authorization server audience (e.g., `api://default`) |
+| `OKTA_DEVICE_AUTHORIZATION_CLIENT_ID` | CLI only | Native app client ID for Device Authorization |
+
+### WorkOS
+
+| Variable | Required | Description |
+|---|---|---|
+| `WORKOS_CLIENT_ID` | ✅ | WorkOS application client ID |
+| `WORKOS_AUTHKIT_DOMAIN` | ✅ | AuthKit domain (e.g., `your-domain.authkit.com`) |
+
+### Auth0
+
+| Variable | Required | Description |
+|---|---|---|
+| `AUTH0_CLIENT_ID` | ✅ | Auth0 application client ID |
+| `AUTH0_CLIENT_SECRET` | ✅ | Auth0 client secret |
+| `AUTH0_DOMAIN` | ✅ | Auth0 tenant domain (e.g., `your-tenant.auth0.com`) |
+
+### Keycloak
+
+| Variable | Required | Description |
+|---|---|---|
+| `KEYCLOAK_CLIENT_ID` | ✅ | Keycloak client ID |
+| `KEYCLOAK_CLIENT_SECRET` | ✅ | Keycloak client secret |
+| `KEYCLOAK_SITE` | ✅ | Keycloak server URL |
+| `KEYCLOAK_REALM` | ✅ | Keycloak realm name |
+| `KEYCLOAK_AUDIENCE` | ✅ | Token audience (default: `account`) |
+| `KEYCLOAK_BASE_URL` | Optional | Base URL path (e.g., `/auth` for pre-v17 migrations) |
+| `KEYCLOAK_DEVICE_AUTHORIZATION_CLIENT_ID` | CLI only | Public client ID for Device Authorization |
+
+---
+
+## Next Steps
+
+- [Installation Guide](/installation) — Get started with CrewAI
+- [Quickstart](/quickstart) — Build your first crew
+- [RBAC Setup](/enterprise/features/rbac) — Detailed role and permission management

docs/ko/changelog.mdx

@@ -4,6 +4,171 @@ description: "CrewAI의 제품 업데이트, 개선 사항 및 버그 수정"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="2026년 3월 27일">
+  ## v1.13.0rc1
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0rc1)
+
+  ## 변경 사항
+
+  ### 문서
+  - v1.13.0a2의 변경 로그 및 버전 업데이트
+
+  ## 기여자
+
+  @greysonlalonde
+
+</Update>
+
+<Update label="2026년 3월 27일">
+  ## v1.13.0a2
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a2)
+
+  ## 변경 사항
+
+  ### 기능
+  - 릴리스 중 자동 업데이트 배포 테스트 리포지토리
+  - 기업 릴리스의 복원력 및 사용자 경험 개선
+
+  ### 문서
+  - v1.13.0a1에 대한 변경 로그 및 버전 업데이트
+
+  ## 기여자
+
+  @greysonlalonde
+
+</Update>
+
+<Update label="2026년 3월 27일">
+  ## v1.13.0a1
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a1)
+
+  ## 변경 사항
+
+  ### 버그 수정
+  - Node를 LTS 22로 고정하여 문서 작업 흐름의 끊어진 링크 수정
+  - 기업 릴리스에서 새로 게시된 패키지의 uv 캐시 초기화
+
+  ### 문서
+  - 포괄적인 RBAC 권한 매트릭스 및 배포 가이드 추가
+  - v1.12.2에 대한 변경 로그 및 버전 업데이트
+
+  ## 기여자
+
+  @greysonlalonde, @iris-clawd, @joaomdmoura
+
+</Update>
+
+<Update label="2026년 3월 25일">
+  ## v1.12.2
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.12.2)
+
+  ## 변경 사항
+
+  ### 기능
+  - devtools 릴리스에 기업 릴리스 단계 추가
+
+  ### 버그 수정
+  - @human_feedback과 함께 emit을 사용할 때 메서드 반환 값을 흐름 출력으로 유지
+
+  ### 문서
+  - v1.12.1에 대한 변경 로그 및 버전 업데이트
+  - 보안 정책 및 보고 지침 수정
+
+  ## 기여자
+
+  @alex-clawd, @greysonlalonde, @joaomdmoura, @theCyberTech
+
+</Update>
+
+<Update label="2026년 3월 25일">
+  ## v1.12.1
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.12.1)
+
+  ## 변경 사항
+
+  ### 기능
+  - HumanFeedbackRequestedEvent에 request_id 추가
+  - 메모리 시스템을 위한 Qdrant Edge 저장소 백엔드 추가
+  - 변경 사항을 분석하고 번역된 문서와 함께 문서를 생성하는 docs-check 명령어 추가
+  - 변경 로그 및 릴리스 도구에 아랍어 지원 추가
+  - 모든 문서에 대한 현대 표준 아랍어 번역 추가
+  - CLI에 로그아웃 명령어 추가
+  - 에이전트 기술 추가
+  - 계층적 메모리 격리를 위한 자동 root_scope 구현
+  - OpenAI 호환 네이티브 제공자 구현 (OpenRouter, DeepSeek, Ollama, vLLM, Cerebras, Dashscope)
+
+  ### 버그 수정
+  - 트레이스 배치 푸시에 대한 잘못된 자격 증명 수정 (404)
+  - HITL 흐름 시스템의 여러 버그 해결
+  - 에이전트 메모리 저장 수정
+  - crewai 패키지 전반에 걸쳐 모든 엄격한 mypy 오류 해결
+  - FlowMeta의 listener+router 메서드에 대한 __router_paths__ 사용 수정
+  - 파일 지원이 없는 경우 값 오류 수정
+  - 문서에서 litellm 격리 단어 수정
+  - crewai-files의 모든 mypy 오류 수정 및 모든 패키지를 CI 유형 검사에 추가
+  - litellm의 상한을 마지막 테스트된 버전 (1.82.6)으로 고정
+
+  ### 문서
+  - v1.12.0에 대한 변경 로그 및 버전 업데이트
+  - CONTRIBUTING.md 추가
+  - LiteLLM 없이 CrewAI를 사용하는 가이드 추가
+
+  ## 기여자
+
+  @akaKuruma, @alex-clawd, @greysonlalonde, @iris-clawd, @joaomdmoura, @lorenzejay, @lucasgomide, @nicoferdi96
+
+</Update>
+
+<Update label="2026년 3월 25일">
+  ## v1.12.0
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0)
+
+  ## 변경 사항
+
+  ### 기능
+  - 메모리 시스템을 위한 Qdrant Edge 스토리지 백엔드 추가
+  - 변경 사항을 분석하고 번역된 문서와 함께 문서를 생성하는 docs-check 명령어 추가
+  - 변경 로그 및 릴리스 도구에 아랍어 지원 추가
+  - 모든 문서의 현대 표준 아랍어 번역 추가
+  - CLI에 로그아웃 명령어 추가
+  - 에이전트 기술 구현
+  - 계층적 메모리 격리를 위한 자동 root_scope 구현
+  - OpenAI 호환 네이티브 제공자 구현 (OpenRouter, DeepSeek, Ollama, vLLM, Cerebras, Dashscope)
+
+  ### 버그 수정
+  - 트레이스 배치 푸시에 대한 잘못된 자격 증명 수정 (404)
+  - HITL 흐름 시스템의 여러 버그 해결
+  - crewai-files의 mypy 오류 해결 및 모든 패키지를 CI 타입 검사에 추가
+  - crewai-tools 패키지 전반의 모든 엄격한 mypy 오류 해결
+  - crewai 패키지 전반의 모든 mypy 오류 해결
+  - 에이전트의 메모리 절약 수정
+  - FlowMeta에서 listener+router 메서드의 __router_paths__ 사용 수정
+  - 파일 지원이 없을 때 값 오류 발생
+  - 문서에서 litellm 격리 단어 수정
+  - 인간 피드백 학습에서 메모리에 대한 isinstance 대신 None 체크 사용
+  - litellm의 상한을 마지막 테스트된 버전(1.82.6)으로 고정
+
+  ### 문서
+  - v1.12.0에 대한 변경 로그 및 버전 업데이트
+  - CONTRIBUTING.md 추가
+  - LiteLLM 없이 CrewAI를 사용하는 가이드 추가
+
+  ### 리팩토링
+  - 에이전트에서 동기/비동기 작업 실행 및 시작을 중복 제거하도록 리팩토링
+  - litellm의 내부 플러밍 단순화 (토큰 카운팅, 콜백, 기능 감지, 오류)
+
+  ## 기여자
+
+  @akaKuruma, @alex-clawd, @greysonlalonde, @iris-clawd, @joaomdmoura, @lorenzejay, @nicoferdi96
+
+</Update>
+
 <Update label="2026년 3월 26일">
   ## v1.12.0a3
 

docs/pt-BR/changelog.mdx

@@ -4,6 +4,171 @@ description: "Atualizações de produto, melhorias e correções do CrewAI"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="27 mar 2026">
+  ## v1.13.0rc1
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0rc1)
+
+  ## O que Mudou
+
+  ### Documentação
+  - Atualizar changelog e versão para v1.13.0a2
+
+  ## Contribuidores
+
+  @greysonlalonde
+
+</Update>
+
+<Update label="27 mar 2026">
+  ## v1.13.0a2
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a2)
+
+  ## O que Mudou
+
+  ### Recursos
+  - Repositório de teste de implantação de autoatualização durante o lançamento
+  - Melhorar a resiliência e a experiência do usuário na versão empresarial
+
+  ### Documentação
+  - Atualizar changelog e versão para v1.13.0a1
+
+  ## Contribuidores
+
+  @greysonlalonde
+
+</Update>
+
+<Update label="27 mar 2026">
+  ## v1.13.0a1
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a1)
+
+  ## O que Mudou
+
+  ### Correções de Bugs
+  - Corrigir links quebrados no fluxo de documentação fixando o Node na LTS 22
+  - Limpar o cache uv para pacotes recém-publicados na versão empresarial
+
+  ### Documentação
+  - Adicionar uma matriz abrangente de permissões RBAC e guia de implantação
+  - Atualizar o changelog e a versão para v1.12.2
+
+  ## Contributors
+
+  @greysonlalonde, @iris-clawd, @joaomdmoura
+
+</Update>
+
+<Update label="25 mar 2026">
+  ## v1.12.2
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.2)
+
+  ## O que Mudou
+
+  ### Recursos
+  - Adicionar fase de lançamento empresarial ao lançamento do devtools
+
+  ### Correções de Bugs
+  - Preservar o valor de retorno do método como saída de fluxo para @human_feedback com emit
+
+  ### Documentação
+  - Atualizar changelog e versão para v1.12.1
+  - Revisar política de segurança e instruções de relatório
+
+  ## Contributors
+
+  @alex-clawd, @greysonlalonde, @joaomdmoura, @theCyberTech
+
+</Update>
+
+<Update label="25 mar 2026">
+  ## v1.12.1
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.1)
+
+  ## O que Mudou
+
+  ### Recursos
+  - Adicionar request_id ao HumanFeedbackRequestedEvent
+  - Adicionar backend de armazenamento Qdrant Edge para sistema de memória
+  - Adicionar comando docs-check para analisar mudanças e gerar documentação com traduções
+  - Adicionar suporte ao idioma árabe para changelog e ferramentas de lançamento
+  - Adicionar tradução em árabe padrão moderno de toda a documentação
+  - Adicionar comando de logout na CLI
+  - Adicionar habilidades de agente
+  - Implementar root_scope automático para isolamento hierárquico de memória
+  - Implementar provedores nativos compatíveis com OpenAI (OpenRouter, DeepSeek, Ollama, vLLM, Cerebras, Dashscope)
+
+  ### Correções de Bugs
+  - Corrigir credenciais incorretas para envio em lote de traces (404)
+  - Resolver múltiplos bugs no sistema de fluxo HITL
+  - Corrigir salvamento de memória do agente
+  - Resolver todos os erros estritos do mypy no pacote crewai
+  - Corrigir uso de __router_paths__ para métodos listener+router em FlowMeta
+  - Corrigir erro de valor em caso de suporte a nenhum arquivo
+  - Corrigir redação da quarentena do litellm na documentação
+  - Corrigir todos os erros do mypy em crewai-files e adicionar todos os pacotes às verificações de tipo do CI
+  - Fixar limite superior do litellm na última versão testada (1.82.6)
+
+  ### Documentação
+  - Atualizar changelog e versão para v1.12.0
+  - Adicionar CONTRIBUTING.md
+  - Adicionar guia para usar CrewAI sem LiteLLM
+
+  ## Contribuidores
+
+  @akaKuruma, @alex-clawd, @greysonlalonde, @iris-clawd, @joaomdmoura, @lorenzejay, @lucasgomide, @nicoferdi96
+
+</Update>
+
+<Update label="25 mar 2026">
+  ## v1.12.0
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0)
+
+  ## O que Mudou
+
+  ### Funcionalidades
+  - Adicionar backend de armazenamento Qdrant Edge para sistema de memória
+  - Adicionar comando docs-check para analisar mudanças e gerar documentos com traduções
+  - Adicionar suporte ao idioma árabe para changelog e ferramentas de lançamento
+  - Adicionar tradução em árabe padrão moderno de toda a documentação
+  - Adicionar comando de logout na CLI
+  - Implementar habilidades de agente
+  - Implementar root_scope automático para isolamento hierárquico de memória
+  - Implementar provedores nativos compatíveis com OpenAI (OpenRouter, DeepSeek, Ollama, vLLM, Cerebras, Dashscope)
+
+  ### Correções de Bugs
+  - Corrigir credenciais inválidas para envio em lote de rastros (404)
+  - Resolver múltiplos bugs no sistema de fluxo HITL
+  - Resolver erros do mypy em crewai-files e adicionar todos os pacotes às verificações de tipo do CI
+  - Resolver todos os erros estritos do mypy no pacote crewai-tools
+  - Resolver todos os erros do mypy no pacote crewai
+  - Corrigir economia de memória no agente
+  - Corrigir uso de __router_paths__ para métodos listener+router em FlowMeta
+  - Levantar erro de valor em caso de suporte a arquivos inexistente
+  - Corrigir a redação da quarentena do litellm na documentação
+  - Usar verificação de None em vez de isinstance para memória no aprendizado de feedback humano
+  - Fixar limite superior do litellm na última versão testada (1.82.6)
+
+  ### Documentação
+  - Atualizar changelog e versão para v1.12.0
+  - Adicionar CONTRIBUTING.md
+  - Adicionar guia para usar CrewAI sem LiteLLM
+
+  ### Refatoração
+  - Refatorar para desduplicar execução de tarefas síncronas/assíncronas e início no agente
+  - Simplificar a infraestrutura interna do litellm (contagem de tokens, callbacks, detecção de recursos, erros)
+
+  ## Contribuidores
+
+  @akaKuruma, @alex-clawd, @greysonlalonde, @iris-clawd, @joaomdmoura, @lorenzejay, @nicoferdi96
+
+</Update>
+
 <Update label="26 mar 2026">
   ## v1.12.0a3
 

lib/crewai-files/src/crewai_files/__init__.py

@@ -152,4 +152,4 @@ __all__ = [
     "wrap_file_source",
 ]
 
-__version__ = "1.12.0a3"
+__version__ = "1.13.0rc1"

lib/crewai-tools/pyproject.toml

@@ -11,7 +11,7 @@ dependencies = [
     "pytube~=15.0.0",
     "requests~=2.32.5",
     "docker~=7.1.0",
-    "crewai==1.12.0a3",
+    "crewai==1.13.0rc1",
     "tiktoken~=0.8.0",
     "beautifulsoup4~=4.13.4",
     "python-docx~=1.2.0",

lib/crewai-tools/src/crewai_tools/__init__.py

@@ -309,4 +309,4 @@ __all__ = [
     "ZapierActionTools",
 ]
 
-__version__ = "1.12.0a3"
+__version__ = "1.13.0rc1"

lib/crewai/pyproject.toml

@@ -43,7 +43,7 @@ dependencies = [
     "uv~=0.9.13",
     "aiosqlite~=0.21.0",
     "pyyaml~=6.0",
-    "lancedb>=0.29.2",
+    "lancedb>=0.29.2,<0.30.1",
 ]
 
 [project.urls]
@@ -54,7 +54,7 @@ Repository = "https://github.com/crewAIInc/crewAI"
 
 [project.optional-dependencies]
 tools = [
-    "crewai-tools==1.12.0a3",
+    "crewai-tools==1.13.0rc1",
 ]
 embeddings = [
     "tiktoken~=0.8.0"

lib/crewai/src/crewai/__init__.py

@@ -42,7 +42,7 @@ def _suppress_pydantic_deprecation_warnings() -> None:
 
 _suppress_pydantic_deprecation_warnings()
 
-__version__ = "1.12.0a3"
+__version__ = "1.13.0rc1"
 _telemetry_submitted = False
 
 

lib/crewai/src/crewai/agent/core.py

@@ -25,7 +25,6 @@ from pydantic import (
     BaseModel,
     ConfigDict,
     Field,
-    InstanceOf,
     PrivateAttr,
     model_validator,
 )
@@ -167,10 +166,10 @@ class Agent(BaseAgent):
         default=True,
         description="Use system prompt for the agent.",
     )
-    llm: str | InstanceOf[BaseLLM] | None = Field(
+    llm: str | BaseLLM | None = Field(
         description="Language model that will run the agent.", default=None
     )
-    function_calling_llm: str | InstanceOf[BaseLLM] | None = Field(
+    function_calling_llm: str | BaseLLM | None = Field(
         description="Language model that will run the agent.", default=None
     )
     system_template: str | None = Field(

lib/crewai/src/crewai/agents/agent_builder/base_agent.py

@@ -12,7 +12,6 @@ from pydantic import (
     UUID4,
     BaseModel,
     Field,
-    InstanceOf,
     PrivateAttr,
     field_validator,
     model_validator,
@@ -185,7 +184,7 @@ class BaseAgent(BaseModel, ABC, metaclass=AgentMeta):
         default=None,
         description="Knowledge sources for the agent.",
     )
-    knowledge_storage: InstanceOf[BaseKnowledgeStorage] | None = Field(
+    knowledge_storage: BaseKnowledgeStorage | None = Field(
         default=None,
         description="Custom knowledge storage for the agent.",
     )

lib/crewai/src/crewai/cli/plus_api.py

@@ -73,6 +73,7 @@ class PlusAPI:
         description: str | None,
         encoded_file: str,
         available_exports: list[dict[str, Any]] | None = None,
+        tools_metadata: list[dict[str, Any]] | None = None,
     ) -> httpx.Response:
         params = {
             "handle": handle,
@@ -81,6 +82,9 @@ class PlusAPI:
             "file": encoded_file,
             "description": description,
             "available_exports": available_exports,
+            "tools_metadata": {"package": handle, "tools": tools_metadata}
+            if tools_metadata is not None
+            else None,
         }
         return self._make_request("POST", f"{self.TOOLS_RESOURCE}", json=params)
 

lib/crewai/src/crewai/cli/templates/crew/pyproject.toml

@@ -5,7 +5,7 @@ description = "{{name}} using crewAI"
 authors = [{ name = "Your Name", email = "you@example.com" }]
 requires-python = ">=3.10,<3.14"
 dependencies = [
-    "crewai[tools]==1.12.0a3"
+    "crewai[tools]==1.13.0rc1"
 ]
 
 [project.scripts]

lib/crewai/src/crewai/cli/templates/flow/pyproject.toml

@@ -5,7 +5,7 @@ description = "{{name}} using crewAI"
 authors = [{ name = "Your Name", email = "you@example.com" }]
 requires-python = ">=3.10,<3.14"
 dependencies = [
-    "crewai[tools]==1.12.0a3"
+    "crewai[tools]==1.13.0rc1"
 ]
 
 [project.scripts]

lib/crewai/src/crewai/cli/templates/tool/pyproject.toml

@@ -5,7 +5,7 @@ description = "Power up your crews with {{folder_name}}"
 readme = "README.md"
 requires-python = ">=3.10,<3.14"
 dependencies = [
-    "crewai[tools]==1.12.0a3"
+    "crewai[tools]==1.13.0rc1"
 ]
 
 [tool.crewai]

lib/crewai/src/crewai/cli/tools/main.py

@@ -17,6 +17,7 @@ from crewai.cli.constants import DEFAULT_CREWAI_ENTERPRISE_URL
 from crewai.cli.utils import (
     build_env_with_tool_repository_credentials,
     extract_available_exports,
+    extract_tools_metadata,
     get_project_description,
     get_project_name,
     get_project_version,
@@ -101,6 +102,18 @@ class ToolCommand(BaseCommand, PlusAPIMixin):
             console.print(
                 f"[green]Found these tools to publish: {', '.join([e['name'] for e in available_exports])}[/green]"
             )
+
+        console.print("[bold blue]Extracting tool metadata...[/bold blue]")
+        try:
+            tools_metadata = extract_tools_metadata()
+        except Exception as e:
+            console.print(
+                f"[yellow]Warning: Could not extract tool metadata: {e}[/yellow]\n"
+                f"Publishing will continue without detailed metadata."
+            )
+            tools_metadata = []
+
+        self._print_tools_preview(tools_metadata)
         self._print_current_organization()
 
         with tempfile.TemporaryDirectory() as temp_build_dir:
@@ -118,7 +131,7 @@ class ToolCommand(BaseCommand, PlusAPIMixin):
                     "Project build failed. Please ensure that the command `uv build --sdist` completes successfully.",
                     style="bold red",
                 )
-                raise SystemExit
+                raise SystemExit(1)
 
             tarball_path = os.path.join(temp_build_dir, tarball_filename)
             with open(tarball_path, "rb") as file:
@@ -134,6 +147,7 @@ class ToolCommand(BaseCommand, PlusAPIMixin):
             description=project_description,
             encoded_file=f"data:application/x-gzip;base64,{encoded_tarball}",
             available_exports=available_exports,
+            tools_metadata=tools_metadata,
         )
 
         self._validate_response(publish_response)
@@ -246,6 +260,55 @@ class ToolCommand(BaseCommand, PlusAPIMixin):
             )
             raise SystemExit
 
+    def _print_tools_preview(self, tools_metadata: list[dict[str, Any]]) -> None:
+        if not tools_metadata:
+            console.print("[yellow]No tool metadata extracted.[/yellow]")
+            return
+
+        console.print(
+            f"\n[bold]Tools to be published ({len(tools_metadata)}):[/bold]\n"
+        )
+
+        for tool in tools_metadata:
+            console.print(f"  [bold cyan]{tool.get('name', 'Unknown')}[/bold cyan]")
+            if tool.get("module"):
+                console.print(f"    Module: {tool.get('module')}")
+            console.print(f"    Name: {tool.get('humanized_name', 'N/A')}")
+            console.print(
+                f"    Description: {tool.get('description', 'N/A')[:80]}{'...' if len(tool.get('description', '')) > 80 else ''}"
+            )
+
+            init_params = tool.get("init_params_schema", {}).get("properties", {})
+            if init_params:
+                required = tool.get("init_params_schema", {}).get("required", [])
+                console.print("    Init parameters:")
+                for param_name, param_info in init_params.items():
+                    param_type = param_info.get("type", "any")
+                    is_required = param_name in required
+                    req_marker = "[red]*[/red]" if is_required else ""
+                    default = (
+                        f" = {param_info['default']}" if "default" in param_info else ""
+                    )
+                    console.print(
+                        f"      - {param_name}: {param_type}{default} {req_marker}"
+                    )
+
+            env_vars = tool.get("env_vars", [])
+            if env_vars:
+                console.print("    Environment variables:")
+                for env_var in env_vars:
+                    req_marker = "[red]*[/red]" if env_var.get("required") else ""
+                    default = (
+                        f" (default: {env_var['default']})"
+                        if env_var.get("default")
+                        else ""
+                    )
+                    console.print(
+                        f"      - {env_var['name']}: {env_var.get('description', 'N/A')}{default} {req_marker}"
+                    )
+
+            console.print()
+
     def _print_current_organization(self) -> None:
         settings = Settings()
         if settings.org_uuid:

lib/crewai/src/crewai/cli/utils.py

@@ -1,10 +1,15 @@
-from functools import reduce
+from collections.abc import Generator, Mapping
+from contextlib import contextmanager
+from functools import lru_cache, reduce
+import hashlib
 import importlib.util
+import inspect
 from inspect import getmro, isclass, isfunction, ismethod
 import os
 from pathlib import Path
 import shutil
 import sys
+import types
 from typing import Any, cast, get_type_hints
 
 import click
@@ -544,43 +549,62 @@ def build_env_with_tool_repository_credentials(
     return env
 
 
+@contextmanager
+def _load_module_from_file(
+    init_file: Path, module_name: str | None = None
+) -> Generator[types.ModuleType | None, None, None]:
+    """
+    Context manager for loading a module from file with automatic cleanup.
+
+    Yields the loaded module or None if loading fails.
+    """
+    if module_name is None:
+        module_name = (
+            f"temp_module_{hashlib.sha256(str(init_file).encode()).hexdigest()[:8]}"
+        )
+
+    spec = importlib.util.spec_from_file_location(module_name, init_file)
+    if not spec or not spec.loader:
+        yield None
+        return
+
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+
+    try:
+        spec.loader.exec_module(module)
+        yield module
+    finally:
+        sys.modules.pop(module_name, None)
+
+
 def _load_tools_from_init(init_file: Path) -> list[dict[str, Any]]:
     """
     Load and validate tools from a given __init__.py file.
     """
-    spec = importlib.util.spec_from_file_location("temp_module", init_file)
-
-    if not spec or not spec.loader:
-        return []
-
-    module = importlib.util.module_from_spec(spec)
-    sys.modules["temp_module"] = module
-
     try:
-        spec.loader.exec_module(module)
+        with _load_module_from_file(init_file) as module:
+            if module is None:
+                return []
 
-        if not hasattr(module, "__all__"):
-            console.print(
-                f"Warning: No __all__ defined in {init_file}",
-                style="bold yellow",
-            )
-            raise SystemExit(1)
-
-        return [
-            {
-                "name": name,
-            }
-            for name in module.__all__
-            if hasattr(module, name) and is_valid_tool(getattr(module, name))
-        ]
+            if not hasattr(module, "__all__"):
+                console.print(
+                    f"Warning: No __all__ defined in {init_file}",
+                    style="bold yellow",
+                )
+                raise SystemExit(1)
 
+            return [
+                {"name": name}
+                for name in module.__all__
+                if hasattr(module, name) and is_valid_tool(getattr(module, name))
+            ]
+    except SystemExit:
+        raise
     except Exception as e:
         console.print(f"[red]Warning: Could not load {init_file}: {e!s}[/red]")
         raise SystemExit(1) from e
 
-    finally:
-        sys.modules.pop("temp_module", None)
-
 
 def _print_no_tools_warning() -> None:
     """
@@ -610,3 +634,242 @@ def _print_no_tools_warning() -> None:
         "    # ... implementation\n"
         "    return result\n"
     )
+
+
+def extract_tools_metadata(dir_path: str = "src") -> list[dict[str, Any]]:
+    """
+    Extract rich metadata from tool classes in the project.
+
+    Returns a list of tool metadata dictionaries containing:
+    - name: Class name
+    - humanized_name: From name field default
+    - description: From description field default
+    - run_params_schema: JSON Schema for _run() params (from args_schema)
+    - init_params_schema: JSON Schema for __init__ params (filtered)
+    - env_vars: List of environment variable dicts
+    """
+    tools_metadata: list[dict[str, Any]] = []
+
+    for init_file in Path(dir_path).glob("**/__init__.py"):
+        tools = _extract_tool_metadata_from_init(init_file)
+        tools_metadata.extend(tools)
+
+    return tools_metadata
+
+
+def _extract_tool_metadata_from_init(init_file: Path) -> list[dict[str, Any]]:
+    """
+    Load module from init file and extract metadata from valid tool classes.
+    """
+    from crewai.tools.base_tool import BaseTool
+
+    try:
+        with _load_module_from_file(init_file) as module:
+            if module is None:
+                return []
+
+            exported_names = getattr(module, "__all__", None)
+            if not exported_names:
+                return []
+
+            tools_metadata = []
+            for name in exported_names:
+                obj = getattr(module, name, None)
+                if obj is None or not (
+                    inspect.isclass(obj) and issubclass(obj, BaseTool)
+                ):
+                    continue
+                if tool_info := _extract_single_tool_metadata(obj):
+                    tools_metadata.append(tool_info)
+
+            return tools_metadata
+    except Exception as e:
+        console.print(
+            f"[yellow]Warning: Could not extract metadata from {init_file}: {e}[/yellow]"
+        )
+        return []
+
+
+def _extract_single_tool_metadata(tool_class: type) -> dict[str, Any] | None:
+    """
+    Extract metadata from a single tool class.
+    """
+    try:
+        core_schema = cast(Any, tool_class).__pydantic_core_schema__
+        if not core_schema:
+            return None
+
+        schema = _unwrap_schema(core_schema)
+        fields = schema.get("schema", {}).get("fields", {})
+
+        try:
+            file_path = inspect.getfile(tool_class)
+            relative_path = Path(file_path).relative_to(Path.cwd())
+            module_path = relative_path.with_suffix("")
+            if module_path.parts[0] == "src":
+                module_path = Path(*module_path.parts[1:])
+            if module_path.name == "__init__":
+                module_path = module_path.parent
+            module = ".".join(module_path.parts)
+        except (TypeError, ValueError):
+            module = tool_class.__module__
+
+        return {
+            "name": tool_class.__name__,
+            "module": module,
+            "humanized_name": _extract_field_default(
+                fields.get("name"), fallback=tool_class.__name__
+            ),
+            "description": str(
+                _extract_field_default(fields.get("description"))
+            ).strip(),
+            "run_params_schema": _extract_run_params_schema(fields.get("args_schema")),
+            "init_params_schema": _extract_init_params_schema(tool_class),
+            "env_vars": _extract_env_vars(fields.get("env_vars")),
+        }
+
+    except Exception:
+        return None
+
+
+def _unwrap_schema(schema: Mapping[str, Any] | dict[str, Any]) -> dict[str, Any]:
+    """
+    Unwrap nested schema structures to get to the actual schema definition.
+    """
+    result: dict[str, Any] = dict(schema)
+    while (
+        result.get("type")
+        in {"function-after", "function-before", "function-wrap", "default"}
+        and "schema" in result
+    ):
+        result = dict(result["schema"])
+    if result.get("type") == "definitions" and "schema" in result:
+        result = dict(result["schema"])
+    return result
+
+
+def _extract_field_default(
+    field: dict[str, Any] | None, fallback: str | list[Any] = ""
+) -> str | list[Any] | int:
+    """
+    Extract the default value from a field schema.
+    """
+    if not field:
+        return fallback
+
+    schema = field.get("schema", {})
+    default = schema.get("default")
+    return default if isinstance(default, (list, str, int)) else fallback
+
+
+@lru_cache(maxsize=1)
+def _get_schema_generator() -> type:
+    """Get a SchemaGenerator that omits non-serializable defaults."""
+    from pydantic.json_schema import GenerateJsonSchema
+    from pydantic_core import PydanticOmit
+
+    class SchemaGenerator(GenerateJsonSchema):
+        def handle_invalid_for_json_schema(
+            self, schema: Any, error_info: Any
+        ) -> dict[str, Any]:
+            raise PydanticOmit
+
+    return SchemaGenerator
+
+
+def _extract_run_params_schema(
+    args_schema_field: dict[str, Any] | None,
+) -> dict[str, Any]:
+    """
+    Extract JSON Schema for the tool's run parameters from args_schema field.
+    """
+    from pydantic import BaseModel
+
+    if not args_schema_field:
+        return {}
+
+    args_schema_class = args_schema_field.get("schema", {}).get("default")
+    if not (
+        inspect.isclass(args_schema_class) and issubclass(args_schema_class, BaseModel)
+    ):
+        return {}
+
+    try:
+        return args_schema_class.model_json_schema(
+            schema_generator=_get_schema_generator()
+        )
+    except Exception:
+        return {}
+
+
+_IGNORED_INIT_PARAMS = frozenset(
+    {
+        "name",
+        "description",
+        "env_vars",
+        "args_schema",
+        "description_updated",
+        "cache_function",
+        "result_as_answer",
+        "max_usage_count",
+        "current_usage_count",
+        "package_dependencies",
+    }
+)
+
+
+def _extract_init_params_schema(tool_class: type) -> dict[str, Any]:
+    """
+    Extract JSON Schema for the tool's __init__ parameters, filtering out base fields.
+    """
+    try:
+        json_schema: dict[str, Any] = cast(Any, tool_class).model_json_schema(
+            schema_generator=_get_schema_generator(), mode="serialization"
+        )
+        filtered_properties = {
+            key: value
+            for key, value in json_schema.get("properties", {}).items()
+            if key not in _IGNORED_INIT_PARAMS
+        }
+        json_schema["properties"] = filtered_properties
+        if "required" in json_schema:
+            json_schema["required"] = [
+                key for key in json_schema["required"] if key in filtered_properties
+            ]
+        return json_schema
+    except Exception:
+        return {}
+
+
+def _extract_env_vars(env_vars_field: dict[str, Any] | None) -> list[dict[str, Any]]:
+    """
+    Extract environment variable definitions from env_vars field.
+    """
+    from crewai.tools.base_tool import EnvVar
+
+    if not env_vars_field:
+        return []
+
+    schema = env_vars_field.get("schema", {})
+    default = schema.get("default")
+    if default is None:
+        default_factory = schema.get("default_factory")
+        if callable(default_factory):
+            try:
+                default = default_factory()
+            except Exception:
+                default = []
+
+    if not isinstance(default, list):
+        return []
+
+    return [
+        {
+            "name": env_var.name,
+            "description": env_var.description,
+            "required": env_var.required,
+            "default": env_var.default,
+        }
+        for env_var in default
+        if isinstance(env_var, EnvVar)
+    ]

lib/crewai/src/crewai/crew.py

@@ -22,7 +22,6 @@ from pydantic import (
     UUID4,
     BaseModel,
     Field,
-    InstanceOf,
     Json,
     PrivateAttr,
     field_validator,
@@ -176,7 +175,7 @@ class Crew(FlowTrackable, BaseModel):
     _rpm_controller: RPMController = PrivateAttr()
     _logger: Logger = PrivateAttr()
     _file_handler: FileHandler = PrivateAttr()
-    _cache_handler: InstanceOf[CacheHandler] = PrivateAttr(default_factory=CacheHandler)
+    _cache_handler: CacheHandler = PrivateAttr(default_factory=CacheHandler)
     _memory: Memory | MemoryScope | MemorySlice | None = PrivateAttr(default=None)
     _train: bool | None = PrivateAttr(default=False)
     _train_iteration: int | None = PrivateAttr()
@@ -210,13 +209,13 @@ class Crew(FlowTrackable, BaseModel):
         default=None,
         description="Metrics for the LLM usage during all tasks execution.",
     )
-    manager_llm: str | InstanceOf[BaseLLM] | None = Field(
+    manager_llm: str | BaseLLM | None = Field(
         description="Language model that will run the agent.", default=None
     )
     manager_agent: BaseAgent | None = Field(
         description="Custom agent that will be used as manager.", default=None
     )
-    function_calling_llm: str | InstanceOf[LLM] | None = Field(
+    function_calling_llm: str | LLM | None = Field(
         description="Language model that will run the agent.", default=None
     )
     config: Json[dict[str, Any]] | dict[str, Any] | None = Field(default=None)
@@ -267,7 +266,7 @@ class Crew(FlowTrackable, BaseModel):
         default=False,
         description="Plan the crew execution and add the plan to the crew.",
     )
-    planning_llm: str | InstanceOf[BaseLLM] | Any | None = Field(
+    planning_llm: str | BaseLLM | Any | None = Field(
         default=None,
         description=(
             "Language model that will run the AgentPlanner if planning is True."
@@ -288,7 +287,7 @@ class Crew(FlowTrackable, BaseModel):
             "knowledge object."
         ),
     )
-    chat_llm: str | InstanceOf[BaseLLM] | Any | None = Field(
+    chat_llm: str | BaseLLM | Any | None = Field(
         default=None,
         description="LLM used to handle chatting with the crew.",
     )
@@ -1800,7 +1799,7 @@ class Crew(FlowTrackable, BaseModel):
     def test(
         self,
         n_iterations: int,
-        eval_llm: str | InstanceOf[BaseLLM],
+        eval_llm: str | BaseLLM,
         inputs: dict[str, Any] | None = None,
     ) -> None:
         """Test and evaluate the Crew with the given inputs for n iterations.

lib/crewai/src/crewai/events/types/flow_events.py

@@ -178,12 +178,15 @@ class HumanFeedbackRequestedEvent(FlowEvent):
         output: The method output shown to the human for review.
         message: The message displayed when requesting feedback.
         emit: Optional list of possible outcomes for routing.
+        request_id: Platform-assigned identifier for this feedback request,
+            used for correlating the request across system boundaries.
     """
 
     method_name: str
     output: Any
     message: str
     emit: list[str] | None = None
+    request_id: str | None = None
     type: str = "human_feedback_requested"
 
 
@@ -198,9 +201,12 @@ class HumanFeedbackReceivedEvent(FlowEvent):
         method_name: Name of the method that received feedback.
         feedback: The raw text feedback provided by the human.
         outcome: The collapsed outcome string (if emit was specified).
+        request_id: Platform-assigned identifier for this feedback request,
+            used for correlating the response back to its originating request.
     """
 
     method_name: str
     feedback: str
     outcome: str | None = None
+    request_id: str | None = None
     type: str = "human_feedback_received"

lib/crewai/src/crewai/experimental/agent_executor.py

@@ -1966,37 +1966,6 @@ class AgentExecutor(Flow[AgentExecutorState], CrewAgentExecutorMixin):
             "original_tool": original_tool,
         }
 
-    def _extract_tool_name(self, tool_call: Any) -> str:
-        """Extract tool name from various tool call formats."""
-        if hasattr(tool_call, "function"):
-            return sanitize_tool_name(tool_call.function.name)
-        if hasattr(tool_call, "function_call") and tool_call.function_call:
-            return sanitize_tool_name(tool_call.function_call.name)
-        if hasattr(tool_call, "name"):
-            return sanitize_tool_name(tool_call.name)
-        if isinstance(tool_call, dict):
-            func_info = tool_call.get("function", {})
-            return sanitize_tool_name(
-                func_info.get("name", "") or tool_call.get("name", "unknown")
-            )
-        return "unknown"
-
-    @router(execute_native_tool)
-    def check_native_todo_completion(
-        self,
-    ) -> Literal["todo_satisfied", "todo_not_satisfied"]:
-        """Check if the native tool execution satisfied the active todo.
-
-        Similar to check_todo_completion but for native tool execution path.
-        """
-        current_todo = self.state.todos.current_todo
-
-        if not current_todo:
-            return "todo_not_satisfied"
-
-        # For native tools, any tool execution satisfies the todo
-        return "todo_satisfied"
-
     @listen("initialized")
     def continue_iteration(self) -> Literal["check_iteration"]:
         """Bridge listener that connects iteration loop back to iteration check."""

lib/crewai/src/crewai/flow/flow.py

@@ -883,6 +883,9 @@ class Flow(Generic[T], metaclass=FlowMeta):
         self.human_feedback_history: list[HumanFeedbackResult] = []
         self.last_human_feedback: HumanFeedbackResult | None = None
         self._pending_feedback_context: PendingFeedbackContext | None = None
+        # Per-method stash for real @human_feedback output (keyed by method name)
+        # Used to decouple routing outcome from method return value when emit is set
+        self._human_feedback_method_outputs: dict[str, Any] = {}
         self.suppress_flow_events: bool = suppress_flow_events
 
         # User input history (for self.ask())
@@ -2290,6 +2293,17 @@ class Flow(Generic[T], metaclass=FlowMeta):
                 result = await result
 
             self._method_outputs.append(result)
+
+            # For @human_feedback methods with emit, the result is the collapsed outcome
+            # (e.g., "approved") used for routing. But we want the actual method output
+            # to be the stored result (for final flow output). Replace the last entry
+            # if a stashed output exists. Dict-based stash is concurrency-safe and
+            # handles None return values (presence in dict = stashed, not value).
+            if method_name in self._human_feedback_method_outputs:
+                self._method_outputs[-1] = self._human_feedback_method_outputs.pop(
+                    method_name
+                )
+
             self._method_execution_counts[method_name] = (
                 self._method_execution_counts.get(method_name, 0) + 1
             )

lib/crewai/src/crewai/flow/human_feedback.py

@@ -591,6 +591,13 @@ def human_feedback(
                 ):
                     _distill_and_store_lessons(self, method_output, raw_feedback)
 
+                # Stash the real method output for final flow result when emit is set
+                # (result is the collapsed outcome string for routing, but we want to
+                # preserve the actual method output as the flow's final result)
+                # Uses per-method dict for concurrency safety and to handle None returns
+                if emit:
+                    self._human_feedback_method_outputs[func.__name__] = method_output
+
                 return result
 
             wrapper: Any = async_wrapper
@@ -615,6 +622,13 @@ def human_feedback(
                 ):
                     _distill_and_store_lessons(self, method_output, raw_feedback)
 
+                # Stash the real method output for final flow result when emit is set
+                # (result is the collapsed outcome string for routing, but we want to
+                # preserve the actual method output as the flow's final result)
+                # Uses per-method dict for concurrency safety and to handle None returns
+                if emit:
+                    self._human_feedback_method_outputs[func.__name__] = method_output
+
                 return result
 
             wrapper = sync_wrapper

lib/crewai/src/crewai/knowledge/storage/base_knowledge_storage.py

@@ -3,12 +3,15 @@ from __future__ import annotations
 from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING, Any
 
+from pydantic import BaseModel, ConfigDict
+
 
 if TYPE_CHECKING:
     from crewai.rag.types import SearchResult
 
 
-class BaseKnowledgeStorage(ABC):
+class BaseKnowledgeStorage(BaseModel, ABC):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
     """Abstract base class for knowledge storage implementations."""
 
     @abstractmethod

lib/crewai/src/crewai/knowledge/storage/knowledge_storage.py

@@ -3,6 +3,9 @@ import traceback
 from typing import Any, cast
 import warnings
 
+from pydantic import Field, PrivateAttr, model_validator
+from typing_extensions import Self
+
 from crewai.knowledge.storage.base_knowledge_storage import BaseKnowledgeStorage
 from crewai.rag.chromadb.config import ChromaDBConfig
 from crewai.rag.chromadb.types import ChromaEmbeddingFunctionWrapper
@@ -22,31 +25,32 @@ class KnowledgeStorage(BaseKnowledgeStorage):
     search efficiency.
     """
 
-    def __init__(
-        self,
-        embedder: ProviderSpec
+    collection_name: str | None = None
+    embedder: (
+        ProviderSpec
         | BaseEmbeddingsProvider[Any]
         | type[BaseEmbeddingsProvider[Any]]
-        | None = None,
-        collection_name: str | None = None,
-    ) -> None:
-        self.collection_name = collection_name
-        self._client: BaseClient | None = None
+        | None
+    ) = Field(default=None, exclude=True)
+    _client: BaseClient | None = PrivateAttr(default=None)
 
+    @model_validator(mode="after")
+    def _init_client(self) -> Self:
         warnings.filterwarnings(
             "ignore",
             message=r".*'model_fields'.*is deprecated.*",
             module=r"^chromadb(\.|$)",
         )
 
-        if embedder:
-            embedding_function = build_embedder(embedder)  # type: ignore[arg-type]
+        if self.embedder:
+            embedding_function = build_embedder(self.embedder)  # type: ignore[arg-type]
             config = ChromaDBConfig(
                 embedding_function=cast(
                     ChromaEmbeddingFunctionWrapper, embedding_function
                 )
             )
             self._client = create_client(config)
+        return self
 
     def _get_client(self) -> BaseClient:
         """Get the appropriate client - instance-specific or global."""

lib/crewai/src/crewai/lite_agent.py

@@ -22,7 +22,6 @@ from pydantic import (
     UUID4,
     BaseModel,
     Field,
-    InstanceOf,
     PrivateAttr,
     field_validator,
     model_validator,
@@ -204,7 +203,7 @@ class LiteAgent(FlowTrackable, BaseModel):
     role: str = Field(description="Role of the agent")
     goal: str = Field(description="Goal of the agent")
     backstory: str = Field(description="Backstory of the agent")
-    llm: str | InstanceOf[BaseLLM] | Any | None = Field(
+    llm: str | BaseLLM | Any | None = Field(
         default=None, description="Language model that will run the agent"
     )
     tools: list[BaseTool] = Field(

lib/crewai/src/crewai/llm.py

@@ -20,8 +20,7 @@ from typing import (
 )
 
 from dotenv import load_dotenv
-import httpx
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_validator
 from typing_extensions import Self
 
 from crewai.events.event_bus import crewai_event_bus
@@ -37,7 +36,12 @@ from crewai.events.types.tool_usage_events import (
     ToolUsageFinishedEvent,
     ToolUsageStartedEvent,
 )
-from crewai.llms.base_llm import BaseLLM, get_current_call_id, llm_call_context
+from crewai.llms.base_llm import (
+    BaseLLM,
+    JsonResponseFormat,
+    get_current_call_id,
+    llm_call_context,
+)
 from crewai.llms.constants import (
     ANTHROPIC_MODELS,
     AZURE_MODELS,
@@ -63,8 +67,6 @@ except ImportError:
 
 if TYPE_CHECKING:
     from crewai.agent.core import Agent
-    from crewai.llms.hooks.base import BaseInterceptor
-    from crewai.llms.providers.anthropic.completion import AnthropicThinkingConfig
     from crewai.task import Task
     from crewai.tools.base_tool import BaseTool
     from crewai.utilities.types import LLMMessage
@@ -342,6 +344,27 @@ class AccumulatedToolArgs(BaseModel):
 
 class LLM(BaseLLM):
     completion_cost: float | None = None
+    timeout: float | int | None = None
+    top_p: float | None = None
+    n: int | None = None
+    max_completion_tokens: int | None = None
+    max_tokens: int | float | None = None
+    presence_penalty: float | None = None
+    frequency_penalty: float | None = None
+    logit_bias: dict[int, float] | None = None
+    response_format: JsonResponseFormat | type[BaseModel] | None = None
+    seed: int | None = None
+    logprobs: int | None = None
+    top_logprobs: int | None = None
+    api_base: str | None = None
+    api_version: str | None = None
+    callbacks: list[Any] | None = None
+    reasoning_effort: Literal["none", "low", "medium", "high"] | None = None
+    stream: bool = False
+    interceptor: Any = None
+    thinking: Any = None
+    context_window_size: int = 0
+    is_anthropic: bool = False
 
     def __new__(cls, model: str, is_litellm: bool = False, **kwargs: Any) -> LLM:
         """Factory method that routes to native SDK or falls back to LiteLLM.
@@ -436,10 +459,7 @@ class LLM(BaseLLM):
             logger.error(error_msg)
             raise ImportError(error_msg) from None
 
-        instance = object.__new__(cls)
-        super(LLM, instance).__init__(model=model, is_litellm=True, **kwargs)
-        instance.is_litellm = True
-        return instance
+        return object.__new__(cls)
 
     @classmethod
     def _matches_provider_pattern(cls, model: str, provider: str) -> bool:
@@ -483,8 +503,8 @@ class LLM(BaseLLM):
                 for prefix in ["gpt-", "gpt-35-", "o1", "o3", "o4", "azure-"]
             )
 
-        # OpenAI-compatible providers - accept any model name since these
-        # providers host many different models with varied naming conventions
+        # OpenAI-compatible providers - most accept any model name, but some
+        # (DeepSeek, Dashscope) restrict to their own model prefixes
         if provider == "deepseek":
             return model_lower.startswith("deepseek")
 
@@ -624,89 +644,23 @@ class LLM(BaseLLM):
 
         return None
 
-    def __init__(
-        self,
-        model: str,
-        timeout: float | int | None = None,
-        temperature: float | None = None,
-        top_p: float | None = None,
-        n: int | None = None,
-        stop: str | list[str] | None = None,
-        max_completion_tokens: int | None = None,
-        max_tokens: int | float | None = None,
-        presence_penalty: float | None = None,
-        frequency_penalty: float | None = None,
-        logit_bias: dict[int, float] | None = None,
-        response_format: type[BaseModel] | None = None,
-        seed: int | None = None,
-        logprobs: int | None = None,
-        top_logprobs: int | None = None,
-        base_url: str | None = None,
-        api_base: str | None = None,
-        api_version: str | None = None,
-        api_key: str | None = None,
-        callbacks: list[Any] | None = None,
-        reasoning_effort: Literal["none", "low", "medium", "high"] | None = None,
-        stream: bool = False,
-        interceptor: BaseInterceptor[httpx.Request, httpx.Response] | None = None,
-        thinking: AnthropicThinkingConfig | dict[str, Any] | None = None,
-        prefer_upload: bool = False,
-        **kwargs: Any,
-    ) -> None:
-        """Initialize LLM instance.
+    @model_validator(mode="before")
+    @classmethod
+    def _validate_llm_fields(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+        model = data.get("model", "")
+        data["is_anthropic"] = cls._is_anthropic_model(model)
+        return data
 
-        Note: This __init__ method is only called for fallback instances.
-        Native provider instances handle their own initialization in their respective classes.
-        """
-        super().__init__(
-            model=model,
-            temperature=temperature,
-            api_key=api_key,
-            base_url=base_url,
-            timeout=timeout,
-            **kwargs,
-        )
-        self.model = model
-        self.timeout = timeout
-        self.temperature = temperature
-        self.top_p = top_p
-        self.n = n
-        self.max_completion_tokens = max_completion_tokens
-        self.max_tokens = max_tokens
-        self.presence_penalty = presence_penalty
-        self.frequency_penalty = frequency_penalty
-        self.logit_bias = logit_bias
-        self.response_format = response_format
-        self.seed = seed
-        self.logprobs = logprobs
-        self.top_logprobs = top_logprobs
-        self.base_url = base_url
-        self.api_base = api_base
-        self.api_version = api_version
-        self.api_key = api_key
-        self.callbacks = callbacks
-        self.context_window_size = 0
-        self.reasoning_effort = reasoning_effort
-        self.prefer_upload = prefer_upload
-        self.additional_params = {
-            k: v for k, v in kwargs.items() if k not in ("is_litellm", "provider")
-        }
-        self.is_anthropic = self._is_anthropic_model(model)
-        self.stream = stream
-        self.interceptor = interceptor
-
-        litellm.drop_params = True
-
-        # Normalize self.stop to always be a list[str]
-        if stop is None:
-            self.stop: list[str] = []
-        elif isinstance(stop, str):
-            self.stop = [stop]
-        else:
-            self.stop = stop
-
-        self.set_callbacks(callbacks or [])
-        self.set_env_callbacks()
+    @model_validator(mode="after")
+    def _init_litellm(self) -> LLM:
+        self.is_litellm = True
+        if LITELLM_AVAILABLE:
+            litellm.drop_params = True
+            self.set_callbacks(self.callbacks or [])
+            self.set_env_callbacks()
+        return self
 
     @staticmethod
     def _is_anthropic_model(model: str) -> bool:
@@ -753,7 +707,7 @@ class LLM(BaseLLM):
             "temperature": self.temperature,
             "top_p": self.top_p,
             "n": self.n,
-            "stop": self.stop or None,
+            "stop": (self.stop or None) if self.supports_stop_words() else None,
             "max_tokens": self.max_tokens or self.max_completion_tokens,
             "presence_penalty": self.presence_penalty,
             "frequency_penalty": self.frequency_penalty,
@@ -1825,9 +1779,11 @@ class LLM(BaseLLM):
                     # whether to summarize the content or abort based on the respect_context_window flag
                     raise
                 except Exception as e:
-                    unsupported_stop = "Unsupported parameter" in str(
-                        e
-                    ) and "'stop'" in str(e)
+                    error_str = str(e)
+                    unsupported_stop = "'stop'" in error_str and (
+                        "Unsupported parameter" in error_str
+                        or "does not support parameters" in error_str
+                    )
 
                     if unsupported_stop:
                         if (
@@ -1961,9 +1917,11 @@ class LLM(BaseLLM):
                 except LLMContextLengthExceededError:
                     raise
                 except Exception as e:
-                    unsupported_stop = "Unsupported parameter" in str(
-                        e
-                    ) and "'stop'" in str(e)
+                    error_str = str(e)
+                    unsupported_stop = "'stop'" in error_str and (
+                        "Unsupported parameter" in error_str
+                        or "does not support parameters" in error_str
+                    )
 
                     if unsupported_stop:
                         if (
@@ -2263,6 +2221,10 @@ class LLM(BaseLLM):
         Note: This method is only used by the litellm fallback path.
         Native providers override this method with their own implementation.
         """
+        model_lower = self.model.lower() if self.model else ""
+        if "gpt-5" in model_lower:
+            return False
+
         if not LITELLM_AVAILABLE or get_supported_openai_params is None:
             # When litellm is not available, assume stop words are supported
             return True
@@ -2434,7 +2396,7 @@ class LLM(BaseLLM):
             **filtered_params,
         )
 
-    def __deepcopy__(self, memo: dict[int, Any] | None) -> LLM:
+    def __deepcopy__(self, memo: dict[int, Any] | None = None) -> LLM:
         """Create a deep copy of the LLM instance."""
         import copy
 

lib/crewai/src/crewai/llms/base_llm.py

@@ -14,10 +14,18 @@ from datetime import datetime
 import json
 import logging
 import re
-from typing import TYPE_CHECKING, Any, Final
+from typing import TYPE_CHECKING, Any, Final, Literal
 import uuid
 
-from pydantic import BaseModel
+from pydantic import (
+    AliasChoices,
+    BaseModel,
+    ConfigDict,
+    Field,
+    PrivateAttr,
+    model_validator,
+)
+from typing_extensions import TypedDict
 
 from crewai.events.event_bus import crewai_event_bus
 from crewai.events.types.llm_events import (
@@ -51,6 +59,12 @@ if TYPE_CHECKING:
     from crewai.utilities.types import LLMMessage
 
 
+class JsonResponseFormat(TypedDict):
+    """Response format requesting raw JSON output (e.g. ``{"type": "json_object"}``)."""
+
+    type: Literal["json_object"]
+
+
 DEFAULT_CONTEXT_WINDOW_SIZE: Final[int] = 4096
 DEFAULT_SUPPORTS_STOP_WORDS: Final[bool] = True
 _JSON_EXTRACTION_PATTERN: Final[re.Pattern[str]] = re.compile(r"\{.*}", re.DOTALL)
@@ -82,7 +96,7 @@ def get_current_call_id() -> str:
     return call_id
 
 
-class BaseLLM(ABC):
+class BaseLLM(BaseModel, ABC):
     """Abstract base class for LLM implementations.
 
     This class defines the interface that all LLM implementations must follow.
@@ -101,56 +115,100 @@ class BaseLLM(ABC):
         additional_params: Additional provider-specific parameters.
     """
 
+    model_config = ConfigDict(arbitrary_types_allowed=True, populate_by_name=True)
+
+    model: str
+    temperature: float | None = None
+    api_key: str | None = None
+    base_url: str | None = None
+    provider: str = Field(default="openai")
+    prefer_upload: bool = False
     is_litellm: bool = False
+    stop: list[str] = Field(
+        default_factory=list,
+        validation_alias=AliasChoices("stop", "stop_sequences"),
+    )
+    additional_params: dict[str, Any] = Field(default_factory=dict)
 
-    def __init__(
-        self,
-        model: str,
-        temperature: float | None = None,
-        api_key: str | None = None,
-        base_url: str | None = None,
-        provider: str | None = None,
-        prefer_upload: bool = False,
-        **kwargs: Any,
-    ) -> None:
-        """Initialize the BaseLLM with default attributes.
+    def __setattr__(self, name: str, value: Any) -> None:
+        if name in ("stop", "stop_sequences"):
+            if value is None:
+                value = []
+            elif isinstance(value, str):
+                value = [value]
+            elif not isinstance(value, list):
+                value = list(value)
+            name = "stop"
+        try:
+            super().__setattr__(name, value)
+        except ValueError:
+            if name in self.model_fields:
+                raise  # Re-raise validation errors on declared fields
+            # Fallback for attributes not declared as fields (e.g. mock patching)
+            object.__setattr__(self, name, value)
+        except AttributeError:
+            object.__setattr__(self, name, value)
 
-        Args:
-            model: The model identifier/name.
-            temperature: Optional temperature setting for response generation.
-            stop: Optional list of stop sequences for generation.
-            prefer_upload: Whether to prefer file upload over inline base64.
-            **kwargs: Additional provider-specific parameters.
+    def __delattr__(self, name: str) -> None:
+        try:
+            super().__delattr__(name)
+        except AttributeError:
+            object.__delattr__(self, name)
+
+    @property
+    def stop_sequences(self) -> list[str]:
+        """Alias for ``stop`` — kept for backward compatibility with provider APIs.
+
+        Writes are handled by ``__setattr__``, which normalizes and redirects
+        ``stop_sequences`` assignments to the ``stop`` field.
         """
-        if not model:
-            raise ValueError("Model name is required and cannot be empty")
+        return self.stop
 
-        self.model = model
-        self.temperature = temperature
-        self.api_key = api_key
-        self.base_url = base_url
-        self.prefer_upload = prefer_upload
-        # Store additional parameters for provider-specific use
-        self.additional_params = kwargs
-        self._provider = provider or "openai"
-
-        stop = kwargs.pop("stop", None)
-        if stop is None:
-            self.stop: list[str] = []
-        elif isinstance(stop, str):
-            self.stop = [stop]
-        elif isinstance(stop, list):
-            self.stop = stop
-        else:
-            self.stop = []
-
-        self._token_usage = {
+    _token_usage: dict[str, int] = PrivateAttr(
+        default_factory=lambda: {
             "total_tokens": 0,
             "prompt_tokens": 0,
             "completion_tokens": 0,
             "successful_requests": 0,
             "cached_prompt_tokens": 0,
         }
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def _validate_init_fields(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+
+        if not data.get("model"):
+            raise ValueError("Model name is required and cannot be empty")
+
+        # Normalize stop: accept str, list, or None; also accept stop_sequences alias
+        stop_seqs = data.pop("stop_sequences", None)
+        stop = stop_seqs if stop_seqs is not None else data.get("stop")
+        if stop is None:
+            data["stop"] = []
+        elif isinstance(stop, str):
+            data["stop"] = [stop]
+        elif isinstance(stop, list):
+            data["stop"] = stop
+        else:
+            data["stop"] = list(stop)
+
+        # Default provider
+        if not data.get("provider"):
+            data["provider"] = "openai"
+
+        # Collect unknown kwargs into additional_params
+        known_fields = set(cls.model_fields.keys())
+        extras = {k: v for k, v in data.items() if k not in known_fields}
+        for k in extras:
+            data.pop(k)
+        existing = data.get("additional_params") or {}
+        existing.update(extras)
+        data["additional_params"] = existing
+
+        return data
 
     def to_config_dict(self) -> dict[str, Any]:
         """Serialize this LLM to a dict that can reconstruct it via ``LLM(**config)``.
@@ -174,16 +232,6 @@ class BaseLLM(ABC):
 
         return config
 
-    @property
-    def provider(self) -> str:
-        """Get the provider of the LLM."""
-        return self._provider
-
-    @provider.setter
-    def provider(self, value: str) -> None:
-        """Set the provider of the LLM."""
-        self._provider = value
-
     @abstractmethod
     def call(
         self,

lib/crewai/src/crewai/llms/providers/anthropic/completion.py

@@ -3,12 +3,13 @@ from __future__ import annotations
 import json
 import logging
 import os
-from typing import TYPE_CHECKING, Any, Final, Literal, TypeGuard, cast
+from typing import Any, Final, Literal, TypeGuard, cast
 
-from pydantic import BaseModel
+from pydantic import BaseModel, PrivateAttr, model_validator
 
 from crewai.events.types.llm_events import LLMCallType
-from crewai.llms.base_llm import BaseLLM, llm_call_context
+from crewai.llms.base_llm import BaseLLM, JsonResponseFormat, llm_call_context
+from crewai.llms.hooks.base import BaseInterceptor
 from crewai.llms.hooks.transport import AsyncHTTPTransport, HTTPTransport
 from crewai.utilities.agent_utils import is_context_length_exceeded
 from crewai.utilities.exceptions.context_window_exceeding_exception import (
@@ -17,9 +18,6 @@ from crewai.utilities.exceptions.context_window_exceeding_exception import (
 from crewai.utilities.types import LLMMessage
 
 
-if TYPE_CHECKING:
-    from crewai.llms.hooks.base import BaseInterceptor
-
 try:
     from anthropic import Anthropic, AsyncAnthropic, transform_schema
     from anthropic.types import (
@@ -150,60 +148,47 @@ class AnthropicCompletion(BaseLLM):
     offering native tool use, streaming support, and proper message formatting.
     """
 
-    def __init__(
-        self,
-        model: str = "claude-3-5-sonnet-20241022",
-        api_key: str | None = None,
-        base_url: str | None = None,
-        timeout: float | None = None,
-        max_retries: int = 2,
-        temperature: float | None = None,
-        max_tokens: int = 4096,  # Required for Anthropic
-        top_p: float | None = None,
-        stop_sequences: list[str] | None = None,
-        stream: bool = False,
-        client_params: dict[str, Any] | None = None,
-        interceptor: BaseInterceptor[httpx.Request, httpx.Response] | None = None,
-        thinking: AnthropicThinkingConfig | None = None,
-        response_format: type[BaseModel] | None = None,
-        tool_search: AnthropicToolSearchConfig | bool | None = None,
-        **kwargs: Any,
-    ):
-        """Initialize Anthropic chat completion client.
+    model: str = "claude-3-5-sonnet-20241022"
+    timeout: float | None = None
+    max_retries: int = 2
+    max_tokens: int = 4096
+    top_p: float | None = None
+    stream: bool = False
+    client_params: dict[str, Any] | None = None
+    interceptor: BaseInterceptor[httpx.Request, httpx.Response] | None = None
+    thinking: AnthropicThinkingConfig | None = None
+    response_format: JsonResponseFormat | type[BaseModel] | None = None
+    tool_search: AnthropicToolSearchConfig | None = None
+    is_claude_3: bool = False
+    supports_tools: bool = True
 
-        Args:
-            model: Anthropic model name (e.g., 'claude-3-5-sonnet-20241022')
-            api_key: Anthropic API key (defaults to ANTHROPIC_API_KEY env var)
-            base_url: Custom base URL for Anthropic API
-            timeout: Request timeout in seconds
-            max_retries: Maximum number of retries
-            temperature: Sampling temperature (0-1)
-            max_tokens: Maximum tokens in response (required for Anthropic)
-            top_p: Nucleus sampling parameter
-            stop_sequences: Stop sequences (Anthropic uses stop_sequences, not stop)
-            stream: Enable streaming responses
-            client_params: Additional parameters for the Anthropic client
-            interceptor: HTTP interceptor for modifying requests/responses at transport level.
-            response_format: Pydantic model for structured output. When provided, responses
-                will be validated against this model schema.
-            tool_search: Enable Anthropic's server-side tool search. When True, uses "bm25"
-                variant by default. Pass an AnthropicToolSearchConfig to choose "regex" or
-                "bm25". When enabled, tools are automatically marked with defer_loading=True
-                and a tool search tool is injected into the tools list.
-            **kwargs: Additional parameters
-        """
-        super().__init__(
-            model=model, temperature=temperature, stop=stop_sequences or [], **kwargs
-        )
+    _client: Any = PrivateAttr(default=None)
+    _async_client: Any = PrivateAttr(default=None)
+    _previous_thinking_blocks: list[Any] = PrivateAttr(default_factory=list)
 
-        # Client params
-        self.interceptor = interceptor
-        self.client_params = client_params
-        self.base_url = base_url
-        self.timeout = timeout
-        self.max_retries = max_retries
+    @model_validator(mode="before")
+    @classmethod
+    def _normalize_anthropic_fields(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+        # Anthropic uses stop_sequences; normalize from stop kwarg
+        popped = data.pop("stop_sequences", None)
+        seqs = popped if popped is not None else (data.get("stop") or [])
+        if isinstance(seqs, str):
+            seqs = [seqs]
+        data["stop"] = seqs
+        data["is_claude_3"] = "claude-3" in data.get("model", "").lower()
+        # Normalize tool_search
+        ts = data.get("tool_search")
+        if ts is True:
+            data["tool_search"] = AnthropicToolSearchConfig()
+        elif ts is not None and not isinstance(ts, AnthropicToolSearchConfig):
+            data["tool_search"] = None
+        return data
 
-        self.client = Anthropic(**self._get_client_params())
+    @model_validator(mode="after")
+    def _init_clients(self) -> AnthropicCompletion:
+        self._client = Anthropic(**self._get_client_params())
 
         async_client_params = self._get_client_params()
         if self.interceptor:
@@ -211,51 +196,8 @@ class AnthropicCompletion(BaseLLM):
             async_http_client = httpx.AsyncClient(transport=async_transport)
             async_client_params["http_client"] = async_http_client
 
-        self.async_client = AsyncAnthropic(**async_client_params)
-
-        # Store completion parameters
-        self.max_tokens = max_tokens
-        self.top_p = top_p
-        self.stream = stream
-        self.stop_sequences = stop_sequences or []
-        self.thinking = thinking
-        self.previous_thinking_blocks: list[ThinkingBlock] = []
-        self.response_format = response_format
-        # Tool search config
-        self.tool_search: AnthropicToolSearchConfig | None
-        if tool_search is True:
-            self.tool_search = AnthropicToolSearchConfig()
-        elif isinstance(tool_search, AnthropicToolSearchConfig):
-            self.tool_search = tool_search
-        else:
-            self.tool_search = None
-        # Model-specific settings
-        self.is_claude_3 = "claude-3" in model.lower()
-        self.supports_tools = True
-
-    @property
-    def stop(self) -> list[str]:
-        """Get stop sequences sent to the API."""
-        return self.stop_sequences
-
-    @stop.setter
-    def stop(self, value: list[str] | str | None) -> None:
-        """Set stop sequences.
-
-        Synchronizes stop_sequences to ensure values set by CrewAgentExecutor
-        are properly sent to the Anthropic API.
-
-        Args:
-            value: Stop sequences as a list, single string, or None
-        """
-        if value is None:
-            self.stop_sequences = []
-        elif isinstance(value, str):
-            self.stop_sequences = [value]
-        elif isinstance(value, list):
-            self.stop_sequences = value
-        else:
-            self.stop_sequences = []
+        self._async_client = AsyncAnthropic(**async_client_params)
+        return self
 
     def to_config_dict(self) -> dict[str, Any]:
         """Extend base config with Anthropic-specific fields."""
@@ -751,11 +693,11 @@ class AnthropicCompletion(BaseLLM):
                         )
                 elif isinstance(content, list):
                     formatted_messages.append({"role": "assistant", "content": content})
-                elif self.thinking and self.previous_thinking_blocks:
+                elif self.thinking and self._previous_thinking_blocks:
                     structured_content = cast(
                         list[dict[str, Any]],
                         [
-                            *self.previous_thinking_blocks,
+                            *self._previous_thinking_blocks,
                             {"type": "text", "text": content if content else ""},
                         ],
                     )
@@ -809,7 +751,7 @@ class AnthropicCompletion(BaseLLM):
         available_functions: dict[str, Any] | None = None,
         from_task: Any | None = None,
         from_agent: Any | None = None,
-        response_model: type[BaseModel] | None = None,
+        response_model: JsonResponseFormat | type[BaseModel] | None = None,
     ) -> str | Any:
         """Handle non-streaming message completion."""
         uses_file_api = _contains_file_id_reference(params.get("messages", []))
@@ -843,11 +785,11 @@ class AnthropicCompletion(BaseLLM):
         try:
             if betas:
                 params["betas"] = betas
-                response = self.client.beta.messages.create(
+                response = self._client.beta.messages.create(
                     **params, extra_body=extra_body
                 )
             else:
-                response = self.client.messages.create(**params)
+                response = self._client.messages.create(**params)
 
         except Exception as e:
             if is_context_length_exceeded(e):
@@ -928,7 +870,7 @@ class AnthropicCompletion(BaseLLM):
                         thinking_blocks.append(cast(ThinkingBlock, thinking_block))
 
         if thinking_blocks:
-            self.previous_thinking_blocks = thinking_blocks
+            self._previous_thinking_blocks = thinking_blocks
 
         content = self._apply_stop_words(content)
         self._emit_call_completed_event(
@@ -952,7 +894,7 @@ class AnthropicCompletion(BaseLLM):
         available_functions: dict[str, Any] | None = None,
         from_task: Any | None = None,
         from_agent: Any | None = None,
-        response_model: type[BaseModel] | None = None,
+        response_model: JsonResponseFormat | type[BaseModel] | None = None,
     ) -> str | Any:
         """Handle streaming message completion."""
         betas: list[str] = []
@@ -991,9 +933,9 @@ class AnthropicCompletion(BaseLLM):
         current_tool_calls: dict[int, dict[str, Any]] = {}
 
         stream_context = (
-            self.client.beta.messages.stream(**stream_params, extra_body=extra_body)
+            self._client.beta.messages.stream(**stream_params, extra_body=extra_body)
             if betas
-            else self.client.messages.stream(**stream_params)
+            else self._client.messages.stream(**stream_params)
         )
         with stream_context as stream:
             response_id = None
@@ -1072,7 +1014,7 @@ class AnthropicCompletion(BaseLLM):
                     thinking_blocks.append(cast(ThinkingBlock, thinking_block))
 
         if thinking_blocks:
-            self.previous_thinking_blocks = thinking_blocks
+            self._previous_thinking_blocks = thinking_blocks
 
         usage = self._extract_anthropic_token_usage(final_message)
         self._track_token_usage_internal(usage)
@@ -1269,7 +1211,7 @@ class AnthropicCompletion(BaseLLM):
 
         try:
             # Send tool results back to Claude for final response
-            final_response: Message = self.client.messages.create(**follow_up_params)
+            final_response: Message = self._client.messages.create(**follow_up_params)
 
             # Track token usage for follow-up call
             follow_up_usage = self._extract_anthropic_token_usage(final_response)
@@ -1288,7 +1230,7 @@ class AnthropicCompletion(BaseLLM):
                             thinking_blocks.append(cast(ThinkingBlock, thinking_block))
 
             if thinking_blocks:
-                self.previous_thinking_blocks = thinking_blocks
+                self._previous_thinking_blocks = thinking_blocks
 
             final_content = self._apply_stop_words(final_content)
 
@@ -1330,7 +1272,7 @@ class AnthropicCompletion(BaseLLM):
         available_functions: dict[str, Any] | None = None,
         from_task: Any | None = None,
         from_agent: Any | None = None,
-        response_model: type[BaseModel] | None = None,
+        response_model: JsonResponseFormat | type[BaseModel] | None = None,
     ) -> str | Any:
         """Handle non-streaming async message completion."""
         uses_file_api = _contains_file_id_reference(params.get("messages", []))
@@ -1364,11 +1306,11 @@ class AnthropicCompletion(BaseLLM):
         try:
             if betas:
                 params["betas"] = betas
-                response = await self.async_client.beta.messages.create(
+                response = await self._async_client.beta.messages.create(
                     **params, extra_body=extra_body
                 )
             else:
-                response = await self.async_client.messages.create(**params)
+                response = await self._async_client.messages.create(**params)
 
         except Exception as e:
             if is_context_length_exceeded(e):
@@ -1461,7 +1403,7 @@ class AnthropicCompletion(BaseLLM):
         available_functions: dict[str, Any] | None = None,
         from_task: Any | None = None,
         from_agent: Any | None = None,
-        response_model: type[BaseModel] | None = None,
+        response_model: JsonResponseFormat | type[BaseModel] | None = None,
     ) -> str | Any:
         """Handle async streaming message completion."""
         betas: list[str] = []
@@ -1498,11 +1440,11 @@ class AnthropicCompletion(BaseLLM):
         current_tool_calls: dict[int, dict[str, Any]] = {}
 
         stream_context = (
-            self.async_client.beta.messages.stream(
+            self._async_client.beta.messages.stream(
                 **stream_params, extra_body=extra_body
             )
             if betas
-            else self.async_client.messages.stream(**stream_params)
+            else self._async_client.messages.stream(**stream_params)
         )
         async with stream_context as stream:
             response_id = None
@@ -1664,7 +1606,7 @@ class AnthropicCompletion(BaseLLM):
         ]
 
         try:
-            final_response: Message = await self.async_client.messages.create(
+            final_response: Message = await self._async_client.messages.create(
                 **follow_up_params
             )
 
@@ -1786,8 +1728,8 @@ class AnthropicCompletion(BaseLLM):
             from crewai_files.uploaders.anthropic import AnthropicFileUploader
 
             return AnthropicFileUploader(
-                client=self.client,
-                async_client=self.async_client,
+                client=self._client,
+                async_client=self._async_client,
             )
         except ImportError:
             return None

lib/crewai/src/crewai/llms/providers/azure/completion.py

@@ -3,11 +3,13 @@ from __future__ import annotations
 import json
 import logging
 import os
-from typing import TYPE_CHECKING, Any, TypedDict
+from typing import Any, TypedDict
+from urllib.parse import urlparse
 
-from pydantic import BaseModel
+from pydantic import BaseModel, PrivateAttr, model_validator
 from typing_extensions import Self
 
+from crewai.llms.hooks.base import BaseInterceptor
 from crewai.utilities.agent_utils import is_context_length_exceeded
 from crewai.utilities.exceptions.context_window_exceeding_exception import (
     LLMContextLengthExceededError,
@@ -16,10 +18,6 @@ from crewai.utilities.pydantic_schema_utils import generate_model_description
 from crewai.utilities.types import LLMMessage
 
 
-if TYPE_CHECKING:
-    from crewai.llms.hooks.base import BaseInterceptor
-
-
 try:
     from azure.ai.inference import (
         ChatCompletionsClient,
@@ -76,109 +74,84 @@ class AzureCompletion(BaseLLM):
     offering native function calling, streaming support, and proper Azure authentication.
     """
 
-    def __init__(
-        self,
-        model: str,
-        api_key: str | None = None,
-        endpoint: str | None = None,
-        api_version: str | None = None,
-        timeout: float | None = None,
-        max_retries: int = 2,
-        temperature: float | None = None,
-        top_p: float | None = None,
-        frequency_penalty: float | None = None,
-        presence_penalty: float | None = None,
-        max_tokens: int | None = None,
-        stop: list[str] | None = None,
-        stream: bool = False,
-        interceptor: BaseInterceptor[Any, Any] | None = None,
-        response_format: type[BaseModel] | None = None,
-        **kwargs: Any,
-    ):
-        """Initialize Azure AI Inference chat completion client.
+    endpoint: str | None = None
+    api_version: str | None = None
+    timeout: float | None = None
+    max_retries: int = 2
+    top_p: float | None = None
+    frequency_penalty: float | None = None
+    presence_penalty: float | None = None
+    max_tokens: int | None = None
+    stream: bool = False
+    interceptor: BaseInterceptor[Any, Any] | None = None
+    response_format: type[BaseModel] | None = None
+    is_openai_model: bool = False
+    is_azure_openai_endpoint: bool = False
 
-        Args:
-            model: Azure deployment name or model name
-            api_key: Azure API key (defaults to AZURE_API_KEY env var)
-            endpoint: Azure endpoint URL (defaults to AZURE_ENDPOINT env var)
-            api_version: Azure API version (defaults to AZURE_API_VERSION env var)
-            timeout: Request timeout in seconds
-            max_retries: Maximum number of retries
-            temperature: Sampling temperature (0-2)
-            top_p: Nucleus sampling parameter
-            frequency_penalty: Frequency penalty (-2 to 2)
-            presence_penalty: Presence penalty (-2 to 2)
-            max_tokens: Maximum tokens in response
-            stop: Stop sequences
-            stream: Enable streaming responses
-            interceptor: HTTP interceptor (not yet supported for Azure).
-            response_format: Pydantic model for structured output. Used as default when
-                           response_model is not passed to call()/acall() methods.
-                           Only works with OpenAI models deployed on Azure.
-            **kwargs: Additional parameters
-        """
-        if interceptor is not None:
+    _client: Any = PrivateAttr(default=None)
+    _async_client: Any = PrivateAttr(default=None)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _normalize_azure_fields(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+
+        if data.get("interceptor") is not None:
             raise NotImplementedError(
                 "HTTP interceptors are not yet supported for Azure AI Inference provider. "
                 "Interceptors are currently supported for OpenAI and Anthropic providers only."
             )
 
-        super().__init__(
-            model=model, temperature=temperature, stop=stop or [], **kwargs
-        )
-
-        self.api_key = api_key or os.getenv("AZURE_API_KEY")
-        self.endpoint = (
-            endpoint
+        # Resolve env vars
+        data["api_key"] = data.get("api_key") or os.getenv("AZURE_API_KEY")
+        data["endpoint"] = (
+            data.get("endpoint")
             or os.getenv("AZURE_ENDPOINT")
             or os.getenv("AZURE_OPENAI_ENDPOINT")
             or os.getenv("AZURE_API_BASE")
         )
-        self.api_version = api_version or os.getenv("AZURE_API_VERSION") or "2024-06-01"
-        self.timeout = timeout
-        self.max_retries = max_retries
+        data["api_version"] = (
+            data.get("api_version") or os.getenv("AZURE_API_VERSION") or "2024-06-01"
+        )
 
-        if not self.api_key:
+        if not data["api_key"]:
             raise ValueError(
                 "Azure API key is required. Set AZURE_API_KEY environment variable or pass api_key parameter."
             )
-        if not self.endpoint:
+        if not data["endpoint"]:
             raise ValueError(
                 "Azure endpoint is required. Set AZURE_ENDPOINT environment variable or pass endpoint parameter."
             )
 
-        # Validate and potentially fix Azure OpenAI endpoint URL
-        self.endpoint = self._validate_and_fix_endpoint(self.endpoint, model)
+        model = data.get("model", "")
+        data["endpoint"] = AzureCompletion._validate_and_fix_endpoint(
+            data["endpoint"], model
+        )
+        data["is_openai_model"] = any(
+            prefix in model.lower() for prefix in ["gpt-", "o1-", "text-"]
+        )
+        parsed = urlparse(data["endpoint"])
+        hostname = parsed.hostname or ""
+        data["is_azure_openai_endpoint"] = (
+            hostname == "openai.azure.com" or hostname.endswith(".openai.azure.com")
+        ) and "/openai/deployments/" in data["endpoint"]
+        return data
 
-        # Build client kwargs
-        client_kwargs = {
+    @model_validator(mode="after")
+    def _init_clients(self) -> AzureCompletion:
+        if not self.api_key:
+            raise ValueError("Azure API key is required.")
+        client_kwargs: dict[str, Any] = {
             "endpoint": self.endpoint,
             "credential": AzureKeyCredential(self.api_key),
         }
-
-        # Add api_version if specified (primarily for Azure OpenAI endpoints)
         if self.api_version:
             client_kwargs["api_version"] = self.api_version
 
-        self.client = ChatCompletionsClient(**client_kwargs)  # type: ignore[arg-type]
-
-        self.async_client = AsyncChatCompletionsClient(**client_kwargs)  # type: ignore[arg-type]
-
-        self.top_p = top_p
-        self.frequency_penalty = frequency_penalty
-        self.presence_penalty = presence_penalty
-        self.max_tokens = max_tokens
-        self.stream = stream
-        self.response_format = response_format
-
-        self.is_openai_model = any(
-            prefix in model.lower() for prefix in ["gpt-", "o1-", "text-"]
-        )
-
-        self.is_azure_openai_endpoint = (
-            "openai.azure.com" in self.endpoint
-            and "/openai/deployments/" in self.endpoint
-        )
+        self._client = ChatCompletionsClient(**client_kwargs)
+        self._async_client = AsyncChatCompletionsClient(**client_kwargs)
+        return self
 
     def to_config_dict(self) -> dict[str, Any]:
         """Extend base config with Azure-specific fields."""
@@ -215,7 +188,11 @@ class AzureCompletion(BaseLLM):
         Returns:
             Validated and potentially corrected endpoint URL
         """
-        if "openai.azure.com" in endpoint and "/openai/deployments/" not in endpoint:
+        ep_host = urlparse(endpoint).hostname or ""
+        is_azure_openai = ep_host == "openai.azure.com" or ep_host.endswith(
+            ".openai.azure.com"
+        )
+        if is_azure_openai and "/openai/deployments/" not in endpoint:
             endpoint = endpoint.rstrip("/")
 
             if not endpoint.endswith("/openai/deployments"):
@@ -731,7 +708,7 @@ class AzureCompletion(BaseLLM):
         """Handle non-streaming chat completion."""
         try:
             # Cast params to Any to avoid type checking issues with TypedDict unpacking
-            response: ChatCompletions = self.client.complete(**params)  # type: ignore[assignment,arg-type]
+            response: ChatCompletions = self._client.complete(**params)
             return self._process_completion_response(
                 response=response,
                 params=params,
@@ -926,7 +903,7 @@ class AzureCompletion(BaseLLM):
         tool_calls: dict[int, dict[str, Any]] = {}
 
         usage_data = {"total_tokens": 0}
-        for update in self.client.complete(**params):  # type: ignore[arg-type]
+        for update in self._client.complete(**params):
             if isinstance(update, StreamingChatCompletionsUpdate):
                 if update.usage:
                     usage = update.usage
@@ -967,7 +944,7 @@ class AzureCompletion(BaseLLM):
         """Handle non-streaming chat completion asynchronously."""
         try:
             # Cast params to Any to avoid type checking issues with TypedDict unpacking
-            response: ChatCompletions = await self.async_client.complete(**params)  # type: ignore[assignment,arg-type]
+            response: ChatCompletions = await self._async_client.complete(**params)
             return self._process_completion_response(
                 response=response,
                 params=params,
@@ -993,8 +970,8 @@ class AzureCompletion(BaseLLM):
 
         usage_data = {"total_tokens": 0}
 
-        stream = await self.async_client.complete(**params)  # type: ignore[arg-type]
-        async for update in stream:  # type: ignore[union-attr]
+        stream = await self._async_client.complete(**params)
+        async for update in stream:
             if isinstance(update, StreamingChatCompletionsUpdate):
                 if hasattr(update, "usage") and update.usage:
                     usage = update.usage
@@ -1110,8 +1087,8 @@ class AzureCompletion(BaseLLM):
         This ensures proper cleanup of the underlying aiohttp session
         to avoid unclosed connector warnings.
         """
-        if hasattr(self.async_client, "close"):
-            await self.async_client.close()
+        if hasattr(self._async_client, "close"):
+            await self._async_client.close()
 
     async def __aenter__(self) -> Self:
         """Async context manager entry."""

lib/crewai/src/crewai/llms/providers/bedrock/completion.py

@@ -7,7 +7,7 @@ import logging
 import os
 from typing import TYPE_CHECKING, Any, TypedDict, cast
 
-from pydantic import BaseModel
+from pydantic import BaseModel, PrivateAttr, model_validator
 from typing_extensions import Required
 
 from crewai.events.types.llm_events import LLMCallType
@@ -33,7 +33,7 @@ if TYPE_CHECKING:
         ToolTypeDef,
     )
 
-    from crewai.llms.hooks.base import BaseInterceptor
+from crewai.llms.hooks.base import BaseInterceptor
 
 
 try:
@@ -228,129 +228,97 @@ class BedrockCompletion(BaseLLM):
     - Model-specific conversation format handling (e.g., Cohere requirements)
     """
 
-    def __init__(
-        self,
-        model: str = "anthropic.claude-3-5-sonnet-20241022-v2:0",
-        aws_access_key_id: str | None = None,
-        aws_secret_access_key: str | None = None,
-        aws_session_token: str | None = None,
-        region_name: str | None = None,
-        temperature: float | None = None,
-        max_tokens: int | None = None,
-        top_p: float | None = None,
-        top_k: int | None = None,
-        stop_sequences: Sequence[str] | None = None,
-        stream: bool = False,
-        guardrail_config: dict[str, Any] | None = None,
-        additional_model_request_fields: dict[str, Any] | None = None,
-        additional_model_response_field_paths: list[str] | None = None,
-        interceptor: BaseInterceptor[Any, Any] | None = None,
-        response_format: type[BaseModel] | None = None,
-        **kwargs: Any,
-    ) -> None:
-        """Initialize AWS Bedrock completion client.
+    model: str = "anthropic.claude-3-5-sonnet-20241022-v2:0"
+    aws_access_key_id: str | None = None
+    aws_secret_access_key: str | None = None
+    aws_session_token: str | None = None
+    region_name: str | None = None
+    max_tokens: int | None = None
+    top_p: float | None = None
+    top_k: int | None = None
+    stream: bool = False
+    guardrail_config: dict[str, Any] | None = None
+    additional_model_request_fields: dict[str, Any] | None = None
+    additional_model_response_field_paths: list[str] | None = None
+    interceptor: BaseInterceptor[Any, Any] | None = None
+    response_format: type[BaseModel] | None = None
+    is_claude_model: bool = False
+    supports_tools: bool = True
+    supports_streaming: bool = True
+    model_id: str = ""
 
-        Args:
-            model: The Bedrock model ID to use
-            aws_access_key_id: AWS access key (defaults to environment variable)
-            aws_secret_access_key: AWS secret key (defaults to environment variable)
-            aws_session_token: AWS session token for temporary credentials
-            region_name: AWS region name
-            temperature: Sampling temperature for response generation
-            max_tokens: Maximum tokens to generate
-            top_p: Nucleus sampling parameter
-            top_k: Top-k sampling parameter (Claude models only)
-            stop_sequences: List of sequences that stop generation
-            stream: Whether to use streaming responses
-            guardrail_config: Guardrail configuration for content filtering
-            additional_model_request_fields: Model-specific request parameters
-            additional_model_response_field_paths: Custom response field paths
-            interceptor: HTTP interceptor (not yet supported for Bedrock).
-            response_format: Pydantic model for structured output. Used as default when
-                           response_model is not passed to call()/acall() methods.
-            **kwargs: Additional parameters
-        """
-        if interceptor is not None:
+    _client: Any = PrivateAttr(default=None)
+    _async_exit_stack: Any = PrivateAttr(default=None)
+    _async_client_initialized: bool = PrivateAttr(default=False)
+    _async_client: Any = PrivateAttr(default=None)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _normalize_bedrock_fields(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+
+        if data.get("interceptor") is not None:
             raise NotImplementedError(
                 "HTTP interceptors are not yet supported for AWS Bedrock provider. "
                 "Interceptors are currently supported for OpenAI and Anthropic providers only."
             )
 
-        # Extract provider from kwargs to avoid duplicate argument
-        kwargs.pop("provider", None)
+        # Force provider to bedrock
+        data.pop("provider", None)
+        data["provider"] = "bedrock"
 
-        super().__init__(
-            model=model,
-            temperature=temperature,
-            stop=stop_sequences or [],
-            provider="bedrock",
-            **kwargs,
+        # Normalize stop_sequences from stop kwarg
+        popped = data.pop("stop_sequences", None)
+        seqs = popped if popped is not None else (data.get("stop") or [])
+        if isinstance(seqs, str):
+            seqs = [seqs]
+        elif isinstance(seqs, Sequence) and not isinstance(seqs, list):
+            seqs = list(seqs)
+        data["stop"] = seqs
+
+        # Resolve env vars
+        data["aws_access_key_id"] = data.get("aws_access_key_id") or os.getenv(
+            "AWS_ACCESS_KEY_ID"
         )
-
-        # Configure client with timeouts and retries following AWS best practices
-        config = Config(
-            read_timeout=300,
-            retries={
-                "max_attempts": 3,
-                "mode": "adaptive",
-            },
-            tcp_keepalive=True,
+        data["aws_secret_access_key"] = data.get("aws_secret_access_key") or os.getenv(
+            "AWS_SECRET_ACCESS_KEY"
         )
-
-        self.region_name = (
-            region_name
+        data["aws_session_token"] = data.get("aws_session_token") or os.getenv(
+            "AWS_SESSION_TOKEN"
+        )
+        data["region_name"] = (
+            data.get("region_name")
             or os.getenv("AWS_DEFAULT_REGION")
             or os.getenv("AWS_REGION_NAME")
             or "us-east-1"
         )
 
-        self.aws_access_key_id = aws_access_key_id or os.getenv("AWS_ACCESS_KEY_ID")
-        self.aws_secret_access_key = aws_secret_access_key or os.getenv(
-            "AWS_SECRET_ACCESS_KEY"
-        )
-        self.aws_session_token = aws_session_token or os.getenv("AWS_SESSION_TOKEN")
+        model = data.get("model", "anthropic.claude-3-5-sonnet-20241022-v2:0")
+        data["is_claude_model"] = "claude" in model.lower()
+        data["model_id"] = model
+        return data
 
-        # Initialize Bedrock client with proper configuration
+    @model_validator(mode="after")
+    def _init_clients(self) -> BedrockCompletion:
+        config = Config(
+            read_timeout=300,
+            retries={"max_attempts": 3, "mode": "adaptive"},
+            tcp_keepalive=True,
+        )
         session = Session(
             aws_access_key_id=self.aws_access_key_id,
             aws_secret_access_key=self.aws_secret_access_key,
             aws_session_token=self.aws_session_token,
             region_name=self.region_name,
         )
-
-        self.client = session.client("bedrock-runtime", config=config)
-
+        self._client = session.client("bedrock-runtime", config=config)
         self._async_exit_stack = AsyncExitStack() if AIOBOTOCORE_AVAILABLE else None
-        self._async_client_initialized = False
-
-        # Store completion parameters
-        self.max_tokens = max_tokens
-        self.top_p = top_p
-        self.top_k = top_k
-        self.stream = stream
-        self.stop_sequences = stop_sequences
-        self.response_format = response_format
-
-        # Store advanced features (optional)
-        self.guardrail_config = guardrail_config
-        self.additional_model_request_fields = additional_model_request_fields
-        self.additional_model_response_field_paths = (
-            additional_model_response_field_paths
-        )
-
-        # Model-specific settings
-        self.is_claude_model = "claude" in model.lower()
-        self.supports_tools = True  # Converse API supports tools for most models
-        self.supports_streaming = True
-
-        # Handle inference profiles for newer models
-        self.model_id = model
+        return self
 
     def to_config_dict(self) -> dict[str, Any]:
         """Extend base config with Bedrock-specific fields."""
         config = super().to_config_dict()
-        # NOTE: AWS credentials (access_key, secret_key, session_token) are
-        # intentionally excluded — they must come from env on resume.
         if self.region_name and self.region_name != "us-east-1":
             config["region_name"] = self.region_name
         if self.max_tokens is not None:
@@ -363,30 +331,6 @@ class BedrockCompletion(BaseLLM):
             config["guardrail_config"] = self.guardrail_config
         return config
 
-    @property
-    def stop(self) -> list[str]:
-        """Get stop sequences sent to the API."""
-        return [] if self.stop_sequences is None else list(self.stop_sequences)
-
-    @stop.setter
-    def stop(self, value: Sequence[str] | str | None) -> None:
-        """Set stop sequences.
-
-        Synchronizes stop_sequences to ensure values set by CrewAgentExecutor
-        are properly sent to the Bedrock API.
-
-        Args:
-            value: Stop sequences as a Sequence, single string, or None
-        """
-        if value is None:
-            self.stop_sequences = []
-        elif isinstance(value, str):
-            self.stop_sequences = [value]
-        elif isinstance(value, Sequence):
-            self.stop_sequences = list(value)
-        else:
-            self.stop_sequences = []
-
     def call(
         self,
         messages: str | list[LLMMessage],
@@ -710,7 +654,7 @@ class BedrockCompletion(BaseLLM):
                     raise ValueError(f"Invalid message format at index {i}")
 
             # Call Bedrock Converse API with proper error handling
-            response = self.client.converse(
+            response = self._client.converse(
                 modelId=self.model_id,
                 messages=cast(
                     "Sequence[MessageTypeDef | MessageOutputTypeDef]",
@@ -994,13 +938,13 @@ class BedrockCompletion(BaseLLM):
         accumulated_tool_input = ""
 
         try:
-            response = self.client.converse_stream(
+            response = self._client.converse_stream(
                 modelId=self.model_id,
                 messages=cast(
                     "Sequence[MessageTypeDef | MessageOutputTypeDef]",
                     cast(object, messages),
                 ),
-                **body,  # type: ignore[arg-type]
+                **body,
             )
 
             stream = response.get("stream")

lib/crewai/src/crewai/llms/providers/gemini/completion.py

@@ -5,12 +5,13 @@ import json
 import logging
 import os
 import re
-from typing import TYPE_CHECKING, Any, Literal, cast
+from typing import Any, Literal, cast
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field, PrivateAttr, model_validator
 
 from crewai.events.types.llm_events import LLMCallType
 from crewai.llms.base_llm import BaseLLM, llm_call_context
+from crewai.llms.hooks.base import BaseInterceptor
 from crewai.utilities.agent_utils import is_context_length_exceeded
 from crewai.utilities.exceptions.context_window_exceeding_exception import (
     LLMContextLengthExceededError,
@@ -19,10 +20,6 @@ from crewai.utilities.pydantic_schema_utils import generate_model_description
 from crewai.utilities.types import LLMMessage
 
 
-if TYPE_CHECKING:
-    from crewai.llms.hooks.base import BaseInterceptor
-
-
 try:
     from google import genai
     from google.genai import types
@@ -44,137 +41,84 @@ class GeminiCompletion(BaseLLM):
     offering native function calling, streaming support, and proper Gemini formatting.
     """
 
-    def __init__(
-        self,
-        model: str = "gemini-2.0-flash-001",
-        api_key: str | None = None,
-        project: str | None = None,
-        location: str | None = None,
-        temperature: float | None = None,
-        top_p: float | None = None,
-        top_k: int | None = None,
-        max_output_tokens: int | None = None,
-        stop_sequences: list[str] | None = None,
-        stream: bool = False,
-        safety_settings: dict[str, Any] | None = None,
-        client_params: dict[str, Any] | None = None,
-        interceptor: BaseInterceptor[Any, Any] | None = None,
-        use_vertexai: bool | None = None,
-        response_format: type[BaseModel] | None = None,
-        thinking_config: types.ThinkingConfig | None = None,
-        **kwargs: Any,
-    ):
-        """Initialize Google Gemini chat completion client.
+    model: str = "gemini-2.0-flash-001"
+    project: str | None = None
+    location: str | None = None
+    top_p: float | None = None
+    top_k: int | None = None
+    max_output_tokens: int | None = None
+    stream: bool = False
+    safety_settings: dict[str, Any] = Field(default_factory=dict)
+    client_params: dict[str, Any] = Field(default_factory=dict)
+    interceptor: BaseInterceptor[Any, Any] | None = None
+    use_vertexai: bool = False
+    response_format: type[BaseModel] | None = None
+    thinking_config: Any = None
+    tools: list[dict[str, Any]] | None = None
+    supports_tools: bool = False
+    is_gemini_2_0: bool = False
 
-        Args:
-            model: Gemini model name (e.g., 'gemini-2.0-flash-001', 'gemini-1.5-pro')
-            api_key: Google API key for Gemini API authentication.
-                    Defaults to GOOGLE_API_KEY or GEMINI_API_KEY env var.
-                    NOTE: Cannot be used with Vertex AI (project parameter). Use Gemini API instead.
-            project: Google Cloud project ID for Vertex AI with ADC authentication.
-                    Requires Application Default Credentials (gcloud auth application-default login).
-                    NOTE: Vertex AI does NOT support API keys, only OAuth2/ADC.
-                    If both api_key and project are set, api_key takes precedence.
-            location: Google Cloud location (for Vertex AI with ADC, defaults to 'us-central1')
-            temperature: Sampling temperature (0-2)
-            top_p: Nucleus sampling parameter
-            top_k: Top-k sampling parameter
-            max_output_tokens: Maximum tokens in response
-            stop_sequences: Stop sequences
-            stream: Enable streaming responses
-            safety_settings: Safety filter settings
-            client_params: Additional parameters to pass to the Google Gen AI Client constructor.
-                          Supports parameters like http_options, credentials, debug_config, etc.
-            interceptor: HTTP interceptor (not yet supported for Gemini).
-            use_vertexai: Whether to use Vertex AI instead of Gemini API.
-                         - True: Use Vertex AI (with ADC or Express mode with API key)
-                         - False: Use Gemini API (explicitly override env var)
-                         - None (default): Check GOOGLE_GENAI_USE_VERTEXAI env var
-                         When using Vertex AI with API key (Express mode), http_options with
-                         api_version="v1" is automatically configured.
-            response_format: Pydantic model for structured output. Used as default when
-                           response_model is not passed to call()/acall() methods.
-            thinking_config: ThinkingConfig for thinking models (gemini-2.5+, gemini-3+).
-                           Controls thought output via include_thoughts, thinking_budget,
-                           and thinking_level. When None, thinking models automatically
-                           get include_thoughts=True so thought content is surfaced.
-            **kwargs: Additional parameters
-        """
-        if interceptor is not None:
+    _client: Any = PrivateAttr(default=None)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _normalize_gemini_fields(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+
+        if data.get("interceptor") is not None:
             raise NotImplementedError(
                 "HTTP interceptors are not yet supported for Google Gemini provider. "
                 "Interceptors are currently supported for OpenAI and Anthropic providers only."
             )
 
-        super().__init__(
-            model=model, temperature=temperature, stop=stop_sequences or [], **kwargs
+        # Normalize stop_sequences from stop kwarg
+        popped = data.pop("stop_sequences", None)
+        seqs = popped if popped is not None else (data.get("stop") or [])
+        if isinstance(seqs, str):
+            seqs = [seqs]
+        data["stop"] = seqs
+
+        # Resolve env vars
+        data["api_key"] = (
+            data.get("api_key")
+            or os.getenv("GOOGLE_API_KEY")
+            or os.getenv("GEMINI_API_KEY")
+        )
+        data["project"] = data.get("project") or os.getenv("GOOGLE_CLOUD_PROJECT")
+        data["location"] = (
+            data.get("location") or os.getenv("GOOGLE_CLOUD_LOCATION") or "us-central1"
         )
 
-        # Store client params for later use
-        self.client_params = client_params or {}
-
-        # Get API configuration with environment variable fallbacks
-        self.api_key = (
-            api_key or os.getenv("GOOGLE_API_KEY") or os.getenv("GEMINI_API_KEY")
-        )
-        self.project = project or os.getenv("GOOGLE_CLOUD_PROJECT")
-        self.location = location or os.getenv("GOOGLE_CLOUD_LOCATION") or "us-central1"
-
-        if use_vertexai is None:
-            use_vertexai = os.getenv("GOOGLE_GENAI_USE_VERTEXAI", "").lower() == "true"
-
-        self.client = self._initialize_client(use_vertexai)
-
-        # Store completion parameters
-        self.top_p = top_p
-        self.top_k = top_k
-        self.max_output_tokens = max_output_tokens
-        self.stream = stream
-        self.safety_settings = safety_settings or {}
-        self.stop_sequences = stop_sequences or []
-        self.tools: list[dict[str, Any]] | None = None
-        self.response_format = response_format
+        use_vx = data.get("use_vertexai")
+        if use_vx is None:
+            use_vx = os.getenv("GOOGLE_GENAI_USE_VERTEXAI", "").lower() == "true"
+        data["use_vertexai"] = use_vx
 
         # Model-specific settings
+        model = data.get("model", "gemini-2.0-flash-001")
         version_match = re.search(r"gemini-(\d+(?:\.\d+)?)", model.lower())
-        self.supports_tools = bool(
+        data["supports_tools"] = bool(
             version_match and float(version_match.group(1)) >= 1.5
         )
-        self.is_gemini_2_0 = bool(
+        data["is_gemini_2_0"] = bool(
             version_match and float(version_match.group(1)) >= 2.0
         )
 
-        self.thinking_config = thinking_config
+        # Auto-enable thinking for gemini-2.5+
         if (
-            self.thinking_config is None
+            data.get("thinking_config") is None
             and version_match
             and float(version_match.group(1)) >= 2.5
         ):
-            self.thinking_config = types.ThinkingConfig(include_thoughts=True)
+            data["thinking_config"] = types.ThinkingConfig(include_thoughts=True)
 
-    @property
-    def stop(self) -> list[str]:
-        """Get stop sequences sent to the API."""
-        return self.stop_sequences
+        return data
 
-    @stop.setter
-    def stop(self, value: list[str] | str | None) -> None:
-        """Set stop sequences.
-
-        Synchronizes stop_sequences to ensure values set by CrewAgentExecutor
-        are properly sent to the Gemini API.
-
-        Args:
-            value: Stop sequences as a list, single string, or None
-        """
-        if value is None:
-            self.stop_sequences = []
-        elif isinstance(value, str):
-            self.stop_sequences = [value]
-        elif isinstance(value, list):
-            self.stop_sequences = value
-        else:
-            self.stop_sequences = []
+    @model_validator(mode="after")
+    def _init_client(self) -> GeminiCompletion:
+        self._client = self._initialize_client(self.use_vertexai)
+        return self
 
     def to_config_dict(self) -> dict[str, Any]:
         """Extend base config with Gemini/Vertex-specific fields."""
@@ -283,8 +227,8 @@ class GeminiCompletion(BaseLLM):
 
         if (
             hasattr(self, "client")
-            and hasattr(self.client, "vertexai")
-            and self.client.vertexai
+            and hasattr(self._client, "vertexai")
+            and self._client.vertexai
         ):
             # Vertex AI configuration
             params.update(
@@ -1152,7 +1096,7 @@ class GeminiCompletion(BaseLLM):
         try:
             # The API accepts list[Content] but mypy is overly strict about variance
             contents_for_api: Any = contents
-            response = self.client.models.generate_content(
+            response = self._client.models.generate_content(
                 model=self.model,
                 contents=contents_for_api,
                 config=config,
@@ -1192,7 +1136,7 @@ class GeminiCompletion(BaseLLM):
 
         # The API accepts list[Content] but mypy is overly strict about variance
         contents_for_api: Any = contents
-        for chunk in self.client.models.generate_content_stream(
+        for chunk in self._client.models.generate_content_stream(
             model=self.model,
             contents=contents_for_api,
             config=config,
@@ -1230,7 +1174,7 @@ class GeminiCompletion(BaseLLM):
         try:
             # The API accepts list[Content] but mypy is overly strict about variance
             contents_for_api: Any = contents
-            response = await self.client.aio.models.generate_content(
+            response = await self._client.aio.models.generate_content(
                 model=self.model,
                 contents=contents_for_api,
                 config=config,
@@ -1270,7 +1214,7 @@ class GeminiCompletion(BaseLLM):
 
         # The API accepts list[Content] but mypy is overly strict about variance
         contents_for_api: Any = contents
-        stream = await self.client.aio.models.generate_content_stream(
+        stream = await self._client.aio.models.generate_content_stream(
             model=self.model,
             contents=contents_for_api,
             config=config,
@@ -1474,6 +1418,6 @@ class GeminiCompletion(BaseLLM):
         try:
             from crewai_files.uploaders.gemini import GeminiFileUploader
 
-            return GeminiFileUploader(client=self.client)
+            return GeminiFileUploader(client=self._client)
         except ImportError:
             return None

lib/crewai/src/crewai/llms/providers/openai/completion.py

@@ -14,10 +14,11 @@ from openai.types.chat import ChatCompletion, ChatCompletionChunk
 from openai.types.chat.chat_completion import Choice
 from openai.types.chat.chat_completion_chunk import ChoiceDelta
 from openai.types.responses import Response
-from pydantic import BaseModel
+from pydantic import BaseModel, PrivateAttr, model_validator
 
 from crewai.events.types.llm_events import LLMCallType
-from crewai.llms.base_llm import BaseLLM, llm_call_context
+from crewai.llms.base_llm import BaseLLM, JsonResponseFormat, llm_call_context
+from crewai.llms.hooks.base import BaseInterceptor
 from crewai.llms.hooks.transport import AsyncHTTPTransport, HTTPTransport
 from crewai.utilities.agent_utils import is_context_length_exceeded
 from crewai.utilities.exceptions.context_window_exceeding_exception import (
@@ -29,7 +30,6 @@ from crewai.utilities.types import LLMMessage
 
 if TYPE_CHECKING:
     from crewai.agent.core import Agent
-    from crewai.llms.hooks.base import BaseInterceptor
     from crewai.task import Task
     from crewai.tools.base_tool import BaseTool
 
@@ -183,77 +183,69 @@ class OpenAICompletion(BaseLLM):
         "computer_use": "computer_use_preview",
     }
 
-    def __init__(
-        self,
-        model: str = "gpt-4o",
-        api_key: str | None = None,
-        base_url: str | None = None,
-        organization: str | None = None,
-        project: str | None = None,
-        timeout: float | None = None,
-        max_retries: int = 2,
-        default_headers: dict[str, str] | None = None,
-        default_query: dict[str, Any] | None = None,
-        client_params: dict[str, Any] | None = None,
-        temperature: float | None = None,
-        top_p: float | None = None,
-        frequency_penalty: float | None = None,
-        presence_penalty: float | None = None,
-        max_tokens: int | None = None,
-        max_completion_tokens: int | None = None,
-        seed: int | None = None,
-        stream: bool = False,
-        response_format: dict[str, Any] | type[BaseModel] | None = None,
-        logprobs: bool | None = None,
-        top_logprobs: int | None = None,
-        reasoning_effort: str | None = None,
-        provider: str | None = None,
-        interceptor: BaseInterceptor[httpx.Request, httpx.Response] | None = None,
-        api: Literal["completions", "responses"] = "completions",
-        instructions: str | None = None,
-        store: bool | None = None,
-        previous_response_id: str | None = None,
-        include: list[str] | None = None,
-        builtin_tools: list[str] | None = None,
-        parse_tool_outputs: bool = False,
-        auto_chain: bool = False,
-        auto_chain_reasoning: bool = False,
-        **kwargs: Any,
-    ) -> None:
-        """Initialize OpenAI completion client."""
+    model: str = "gpt-4o"
+    organization: str | None = None
+    project: str | None = None
+    timeout: float | None = None
+    max_retries: int = 2
+    default_headers: dict[str, str] | None = None
+    default_query: dict[str, Any] | None = None
+    client_params: dict[str, Any] | None = None
+    top_p: float | None = None
+    frequency_penalty: float | None = None
+    presence_penalty: float | None = None
+    max_tokens: int | None = None
+    max_completion_tokens: int | None = None
+    seed: int | None = None
+    stream: bool = False
+    response_format: JsonResponseFormat | type[BaseModel] | None = None
+    logprobs: bool | None = None
+    top_logprobs: int | None = None
+    reasoning_effort: str | None = None
+    interceptor: BaseInterceptor[httpx.Request, httpx.Response] | None = None
+    api: Literal["completions", "responses"] = "completions"
+    instructions: str | None = None
+    store: bool | None = None
+    previous_response_id: str | None = None
+    include: list[str] | None = None
+    builtin_tools: list[str] | None = None
+    parse_tool_outputs: bool = False
+    auto_chain: bool = False
+    auto_chain_reasoning: bool = False
+    api_base: str | None = None
+    is_o1_model: bool = False
+    is_gpt4_model: bool = False
 
-        if provider is None:
-            provider = kwargs.pop("provider", "openai")
+    _client: Any = PrivateAttr(default=None)
+    _async_client: Any = PrivateAttr(default=None)
+    _last_response_id: str | None = PrivateAttr(default=None)
+    _last_reasoning_items: list[Any] | None = PrivateAttr(default=None)
 
-        self.interceptor = interceptor
-        # Client configuration attributes
-        self.organization = organization
-        self.project = project
-        self.max_retries = max_retries
-        self.default_headers = default_headers
-        self.default_query = default_query
-        self.client_params = client_params
-        self.timeout = timeout
-        self.base_url = base_url
-        self.api_base = kwargs.pop("api_base", None)
-
-        super().__init__(
-            model=model,
-            temperature=temperature,
-            api_key=api_key or os.getenv("OPENAI_API_KEY"),
-            base_url=base_url,
-            timeout=timeout,
-            provider=provider,
-            **kwargs,
-        )
+    @model_validator(mode="before")
+    @classmethod
+    def _normalize_openai_fields(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+        if not data.get("provider"):
+            data["provider"] = "openai"
+        data["api_key"] = data.get("api_key") or os.getenv("OPENAI_API_KEY")
+        # Extract api_base from kwargs if present
+        if "api_base" not in data:
+            data["api_base"] = None
+        model = data.get("model", "gpt-4o")
+        data["is_o1_model"] = "o1" in model.lower()
+        data["is_gpt4_model"] = "gpt-4" in model.lower()
+        return data
 
+    @model_validator(mode="after")
+    def _init_clients(self) -> OpenAICompletion:
         client_config = self._get_client_params()
         if self.interceptor:
             transport = HTTPTransport(interceptor=self.interceptor)
             http_client = httpx.Client(transport=transport)
             client_config["http_client"] = http_client
 
-        self.client = OpenAI(**client_config)
+        self._client = OpenAI(**client_config)
 
         async_client_config = self._get_client_params()
         if self.interceptor:
@@ -261,35 +253,8 @@ class OpenAICompletion(BaseLLM):
             async_http_client = httpx.AsyncClient(transport=async_transport)
             async_client_config["http_client"] = async_http_client
 
-        self.async_client = AsyncOpenAI(**async_client_config)
-
-        # Completion parameters
-        self.top_p = top_p
-        self.frequency_penalty = frequency_penalty
-        self.presence_penalty = presence_penalty
-        self.max_tokens = max_tokens
-        self.max_completion_tokens = max_completion_tokens
-        self.seed = seed
-        self.stream = stream
-        self.response_format = response_format
-        self.logprobs = logprobs
-        self.top_logprobs = top_logprobs
-        self.reasoning_effort = reasoning_effort
-        self.is_o1_model = "o1" in model.lower()
-        self.is_gpt4_model = "gpt-4" in model.lower()
-
-        # API selection and Responses API parameters
-        self.api = api
-        self.instructions = instructions
-        self.store = store
-        self.previous_response_id = previous_response_id
-        self.include = include
-        self.builtin_tools = builtin_tools
-        self.parse_tool_outputs = parse_tool_outputs
-        self.auto_chain = auto_chain
-        self.auto_chain_reasoning = auto_chain_reasoning
-        self._last_response_id: str | None = None
-        self._last_reasoning_items: list[Any] | None = None
+        self._async_client = AsyncOpenAI(**async_client_config)
+        return self
 
     @property
     def last_response_id(self) -> str | None:
@@ -818,7 +783,7 @@ class OpenAICompletion(BaseLLM):
     ) -> str | ResponsesAPIResult | Any:
         """Handle non-streaming Responses API call."""
         try:
-            response: Response = self.client.responses.create(**params)
+            response: Response = self._client.responses.create(**params)
 
             # Track response ID for auto-chaining
             if self.auto_chain and response.id:
@@ -950,7 +915,7 @@ class OpenAICompletion(BaseLLM):
     ) -> str | ResponsesAPIResult | Any:
         """Handle async non-streaming Responses API call."""
         try:
-            response: Response = await self.async_client.responses.create(**params)
+            response: Response = await self._async_client.responses.create(**params)
 
             # Track response ID for auto-chaining
             if self.auto_chain and response.id:
@@ -1081,7 +1046,7 @@ class OpenAICompletion(BaseLLM):
         function_calls: list[dict[str, Any]] = []
         final_response: Response | None = None
 
-        stream = self.client.responses.create(**params)
+        stream = self._client.responses.create(**params)
         response_id_stream = None
 
         for event in stream:
@@ -1205,7 +1170,7 @@ class OpenAICompletion(BaseLLM):
         function_calls: list[dict[str, Any]] = []
         final_response: Response | None = None
 
-        stream = await self.async_client.responses.create(**params)
+        stream = await self._async_client.responses.create(**params)
         response_id_stream = None
 
         async for event in stream:
@@ -1595,7 +1560,7 @@ class OpenAICompletion(BaseLLM):
                 parse_params = {
                     k: v for k, v in params.items() if k != "response_format"
                 }
-                parsed_response = self.client.beta.chat.completions.parse(
+                parsed_response = self._client.beta.chat.completions.parse(
                     **parse_params,
                     response_format=response_model,
                 )
@@ -1618,7 +1583,7 @@ class OpenAICompletion(BaseLLM):
                     )
                     return parsed_object
 
-            response: ChatCompletion = self.client.chat.completions.create(**params)
+            response: ChatCompletion = self._client.chat.completions.create(**params)
 
             usage = self._extract_openai_token_usage(response)
 
@@ -1837,7 +1802,7 @@ class OpenAICompletion(BaseLLM):
             }
 
             stream: ChatCompletionStream[BaseModel]
-            with self.client.beta.chat.completions.stream(
+            with self._client.beta.chat.completions.stream(
                 **parse_params, response_format=response_model
             ) as stream:
                 for chunk in stream:
@@ -1873,7 +1838,7 @@ class OpenAICompletion(BaseLLM):
             return ""
 
         completion_stream: Stream[ChatCompletionChunk] = (
-            self.client.chat.completions.create(**params)
+            self._client.chat.completions.create(**params)
         )
 
         usage_data = {"total_tokens": 0}
@@ -1970,7 +1935,7 @@ class OpenAICompletion(BaseLLM):
                 parse_params = {
                     k: v for k, v in params.items() if k != "response_format"
                 }
-                parsed_response = await self.async_client.beta.chat.completions.parse(
+                parsed_response = await self._async_client.beta.chat.completions.parse(
                     **parse_params,
                     response_format=response_model,
                 )
@@ -1993,7 +1958,7 @@ class OpenAICompletion(BaseLLM):
                     )
                     return parsed_object
 
-            response: ChatCompletion = await self.async_client.chat.completions.create(
+            response: ChatCompletion = await self._async_client.chat.completions.create(
                 **params
             )
 
@@ -2111,7 +2076,7 @@ class OpenAICompletion(BaseLLM):
         if response_model:
             completion_stream: AsyncIterator[
                 ChatCompletionChunk
-            ] = await self.async_client.chat.completions.create(**params)
+            ] = await self._async_client.chat.completions.create(**params)
 
             accumulated_content = ""
             usage_data = {"total_tokens": 0}
@@ -2164,7 +2129,7 @@ class OpenAICompletion(BaseLLM):
 
         stream: AsyncIterator[
             ChatCompletionChunk
-        ] = await self.async_client.chat.completions.create(**params)
+        ] = await self._async_client.chat.completions.create(**params)
 
         usage_data = {"total_tokens": 0}
 
@@ -2245,6 +2210,9 @@ class OpenAICompletion(BaseLLM):
 
     def supports_stop_words(self) -> bool:
         """Check if the model supports stop words."""
+        model_lower = self.model.lower() if self.model else ""
+        if "gpt-5" in model_lower:
+            return False
         return not self.is_o1_model
 
     def get_context_window_size(self) -> int:
@@ -2353,8 +2321,8 @@ class OpenAICompletion(BaseLLM):
             from crewai_files.uploaders.openai import OpenAIFileUploader
 
             return OpenAIFileUploader(
-                client=self.client,
-                async_client=self.async_client,
+                client=self._client,
+                async_client=self._async_client,
             )
         except ImportError:
             return None

lib/crewai/src/crewai/llms/providers/openai_compatible/completion.py

@@ -16,6 +16,8 @@ from dataclasses import dataclass, field
 import os
 from typing import Any
 
+from pydantic import model_validator
+
 from crewai.llms.providers.openai.completion import OpenAICompletion
 
 
@@ -140,31 +142,13 @@ class OpenAICompatibleCompletion(OpenAICompletion):
         )
     """
 
-    def __init__(
-        self,
-        model: str,
-        provider: str,
-        api_key: str | None = None,
-        base_url: str | None = None,
-        default_headers: dict[str, str] | None = None,
-        **kwargs: Any,
-    ) -> None:
-        """Initialize OpenAI-compatible completion client.
+    @model_validator(mode="before")
+    @classmethod
+    def _resolve_provider_config(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
 
-        Args:
-            model: The model identifier.
-            provider: The provider name (must be in OPENAI_COMPATIBLE_PROVIDERS).
-            api_key: Optional API key override. If not provided, uses the
-                provider's configured environment variable.
-            base_url: Optional base URL override. If not provided, uses the
-                provider's configured default or environment variable.
-            default_headers: Optional headers to merge with provider defaults.
-            **kwargs: Additional arguments passed to OpenAICompletion.
-
-        Raises:
-            ValueError: If the provider is not supported or required API key
-                is missing.
-        """
+        provider = data.get("provider", "")
         config = OPENAI_COMPATIBLE_PROVIDERS.get(provider)
         if config is None:
             supported = ", ".join(sorted(OPENAI_COMPATIBLE_PROVIDERS.keys()))
@@ -173,21 +157,15 @@ class OpenAICompatibleCompletion(OpenAICompletion):
                 f"Supported providers: {supported}"
             )
 
-        resolved_api_key = self._resolve_api_key(api_key, config, provider)
-        resolved_base_url = self._resolve_base_url(base_url, config, provider)
-        resolved_headers = self._resolve_headers(default_headers, config)
-
-        super().__init__(
-            model=model,
-            provider=provider,
-            api_key=resolved_api_key,
-            base_url=resolved_base_url,
-            default_headers=resolved_headers,
-            **kwargs,
+        data["api_key"] = cls._resolve_api_key(data.get("api_key"), config, provider)
+        data["base_url"] = cls._resolve_base_url(data.get("base_url"), config, provider)
+        data["default_headers"] = cls._resolve_headers(
+            data.get("default_headers"), config
         )
+        return data
 
+    @staticmethod
     def _resolve_api_key(
-        self,
         api_key: str | None,
         config: ProviderConfig,
         provider: str,
@@ -220,8 +198,8 @@ class OpenAICompatibleCompletion(OpenAICompletion):
 
         return config.default_api_key
 
+    @staticmethod
     def _resolve_base_url(
-        self,
         base_url: str | None,
         config: ProviderConfig,
         provider: str,
@@ -239,7 +217,8 @@ class OpenAICompatibleCompletion(OpenAICompletion):
         if base_url:
             resolved = base_url
         elif config.base_url_env:
-            resolved = os.getenv(config.base_url_env, config.base_url)
+            env_value = os.getenv(config.base_url_env)
+            resolved = env_value if env_value else config.base_url
         else:
             resolved = config.base_url
 
@@ -248,8 +227,8 @@ class OpenAICompatibleCompletion(OpenAICompletion):
 
         return resolved
 
+    @staticmethod
     def _resolve_headers(
-        self,
         headers: dict[str, str] | None,
         config: ProviderConfig,
     ) -> dict[str, str] | None:
@@ -274,9 +253,11 @@ class OpenAICompatibleCompletion(OpenAICompletion):
     def supports_function_calling(self) -> bool:
         """Check if the provider supports function calling.
 
-        All modern OpenAI-compatible providers support function calling.
+        Delegates to the parent OpenAI implementation which handles
+        edge cases like o1 models (which may be routed through
+        OpenRouter or other compatible providers).
 
         Returns:
-            True, as all supported providers have function calling support.
+            Whether the model supports function calling.
         """
-        return True
+        return super().supports_function_calling()

lib/crewai/src/crewai/llms/third_party/__init__.py

@@ -1 +0,0 @@
-"""Third-party LLM implementations for crewAI."""

lib/crewai/src/crewai/utilities/evaluators/crew_evaluator_handler.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from collections import defaultdict
 from typing import TYPE_CHECKING, Any
 
-from pydantic import BaseModel, Field, InstanceOf
+from pydantic import BaseModel, Field
 from rich.box import HEAVY_EDGE
 from rich.console import Console
 from rich.table import Table
@@ -39,9 +39,9 @@ class CrewEvaluator:
     def __init__(
         self,
         crew: Crew,
-        eval_llm: InstanceOf[BaseLLM] | str | None = None,
+        eval_llm: BaseLLM | str | None = None,
         openai_model_name: str | None = None,
-        llm: InstanceOf[BaseLLM] | str | None = None,
+        llm: BaseLLM | str | None = None,
     ) -> None:
         self.crew = crew
         self.llm = eval_llm

lib/crewai/tests/agents/test_agent.py

@@ -1692,9 +1692,27 @@ def test_agent_with_knowledge_sources_works_with_copy():
         ) as mock_knowledge_storage:
             from crewai.knowledge.storage.base_knowledge_storage import BaseKnowledgeStorage
 
-            mock_knowledge_storage_instance = mock_knowledge_storage.return_value
-            mock_knowledge_storage_instance.__class__ = BaseKnowledgeStorage
-            agent.knowledge_storage = mock_knowledge_storage_instance
+            class _StubStorage(BaseKnowledgeStorage):
+                def search(self, query, limit=5, metadata_filter=None, score_threshold=0.6):
+                    return []
+
+                async def asearch(self, query, limit=5, metadata_filter=None, score_threshold=0.6):
+                    return []
+
+                def save(self, documents):
+                    pass
+
+                async def asave(self, documents):
+                    pass
+
+                def reset(self):
+                    pass
+
+                async def areset(self):
+                    pass
+
+            mock_knowledge_storage.return_value = _StubStorage()
+            agent.knowledge_storage = _StubStorage()
 
             agent_copy = agent.copy()
 

lib/crewai/tests/agents/test_agent_executor.py

@@ -879,30 +879,6 @@ class TestNativeToolExecution:
         assert len(tool_messages) == 1
         assert tool_messages[0]["tool_call_id"] == "call_1"
 
-    def test_check_native_todo_completion_requires_current_todo(
-        self, mock_dependencies
-    ):
-        from crewai.utilities.planning_types import TodoList
-
-        executor = AgentExecutor(**mock_dependencies)
-
-        # No current todo → not satisfied
-        executor.state.todos = TodoList(items=[])
-        assert executor.check_native_todo_completion() == "todo_not_satisfied"
-
-        # With a current todo that has tool_to_use → satisfied
-        running = TodoItem(
-            step_number=1,
-            description="Use the expected tool",
-            tool_to_use="expected_tool",
-            status="running",
-        )
-        executor.state.todos = TodoList(items=[running])
-        assert executor.check_native_todo_completion() == "todo_satisfied"
-
-        # With a current todo without tool_to_use → still satisfied
-        running.tool_to_use = None
-        assert executor.check_native_todo_completion() == "todo_satisfied"
 
 
 class TestPlannerObserver:

lib/crewai/tests/cassettes/llms/openai/test_openai_responses_api_cached_prompt_tokens_with_tools.yaml

@@ -1,7 +1,11 @@
 interactions:
 - request:
-    body: '{"messages":[{"role":"system","content":"You are a helpful assistant that
-      uses tools. This is padding text to ensure the prompt is large enough for caching.
+    body: '{"input":[{"role":"user","content":"What is the weather in Tokyo?"}],"model":"gpt-4.1","instructions":"You
+      are a helpful assistant that uses tools. This is padding text to ensure the
+      prompt is large enough for caching. This is padding text to ensure the prompt
+      is large enough for caching. This is padding text to ensure the prompt is large
+      enough for caching. This is padding text to ensure the prompt is large enough
+      for caching. This is padding text to ensure the prompt is large enough for caching.
       This is padding text to ensure the prompt is large enough for caching. This
       is padding text to ensure the prompt is large enough for caching. This is padding
       text to ensure the prompt is large enough for caching. This is padding text
@@ -68,13 +72,9 @@ interactions:
       for caching. This is padding text to ensure the prompt is large enough for caching.
       This is padding text to ensure the prompt is large enough for caching. This
       is padding text to ensure the prompt is large enough for caching. This is padding
-      text to ensure the prompt is large enough for caching. This is padding text
-      to ensure the prompt is large enough for caching. This is padding text to ensure
-      the prompt is large enough for caching. This is padding text to ensure the prompt
-      is large enough for caching. This is padding text to ensure the prompt is large
-      enough for caching. "},{"role":"user","content":"What is the weather in Tokyo?"}],"model":"gpt-4.1","tool_choice":"auto","tools":[{"type":"function","function":{"name":"get_weather","description":"Get
-      the current weather for a location","strict":true,"parameters":{"type":"object","properties":{"location":{"type":"string","description":"The
-      city name"}},"required":["location"],"additionalProperties":false}}}]}'
+      text to ensure the prompt is large enough for caching. ","tools":[{"type":"function","name":"get_weather","description":"Get
+      the current weather for a location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The
+      city name"}},"required":["location"]}}]}'
     headers:
       User-Agent:
       - X-USER-AGENT-XXX
@@ -87,7 +87,7 @@ interactions:
       connection:
       - keep-alive
       content-length:
-      - '6158'
+      - '6065'
       content-type:
       - application/json
       host:
@@ -109,26 +109,113 @@ interactions:
       x-stainless-runtime:
       - CPython
       x-stainless-runtime-version:
-      - 3.13.3
+      - 3.13.12
     method: POST
-    uri: https://api.openai.com/v1/chat/completions
+    uri: https://api.openai.com/v1/responses
   response:
     body:
-      string: "{\n  \"id\": \"chatcmpl-D7mXQCgT3p3ViImkiqDiZGqLREQtp\",\n  \"object\":
-        \"chat.completion\",\n  \"created\": 1770747248,\n  \"model\": \"gpt-4.1-2025-04-14\",\n
-        \ \"choices\": [\n    {\n      \"index\": 0,\n      \"message\": {\n        \"role\":
-        \"assistant\",\n        \"content\": null,\n        \"tool_calls\": [\n          {\n
-        \           \"id\": \"call_9ZqMavn3J1fBnQEaqpYol0Bd\",\n            \"type\":
-        \"function\",\n            \"function\": {\n              \"name\": \"get_weather\",\n
-        \             \"arguments\": \"{\\\"location\\\":\\\"Tokyo\\\"}\"\n            }\n
-        \         }\n        ],\n        \"refusal\": null,\n        \"annotations\":
-        []\n      },\n      \"logprobs\": null,\n      \"finish_reason\": \"tool_calls\"\n
-        \   }\n  ],\n  \"usage\": {\n    \"prompt_tokens\": 1187,\n    \"completion_tokens\":
-        14,\n    \"total_tokens\": 1201,\n    \"prompt_tokens_details\": {\n      \"cached_tokens\":
-        1152,\n      \"audio_tokens\": 0\n    },\n    \"completion_tokens_details\":
-        {\n      \"reasoning_tokens\": 0,\n      \"audio_tokens\": 0,\n      \"accepted_prediction_tokens\":
-        0,\n      \"rejected_prediction_tokens\": 0\n    }\n  },\n  \"service_tier\":
-        \"default\",\n  \"system_fingerprint\": \"fp_8b22347a3e\"\n}\n"
+      string: "{\n  \"id\": \"resp_0d68149bcc0d14810069caf464a4b48197bd9f098abb2f6303\",\n
+        \ \"object\": \"response\",\n  \"created_at\": 1774908516,\n  \"status\":
+        \"completed\",\n  \"background\": false,\n  \"billing\": {\n    \"payer\":
+        \"developer\"\n  },\n  \"completed_at\": 1774908517,\n  \"error\": null,\n
+        \ \"frequency_penalty\": 0.0,\n  \"incomplete_details\": null,\n  \"instructions\":
+        \"You are a helpful assistant that uses tools. This is padding text to ensure
+        the prompt is large enough for caching. This is padding text to ensure the
+        prompt is large enough for caching. This is padding text to ensure the prompt
+        is large enough for caching. This is padding text to ensure the prompt is
+        large enough for caching. This is padding text to ensure the prompt is large
+        enough for caching. This is padding text to ensure the prompt is large enough
+        for caching. This is padding text to ensure the prompt is large enough for
+        caching. This is padding text to ensure the prompt is large enough for caching.
+        This is padding text to ensure the prompt is large enough for caching. This
+        is padding text to ensure the prompt is large enough for caching. This is
+        padding text to ensure the prompt is large enough for caching. This is padding
+        text to ensure the prompt is large enough for caching. This is padding text
+        to ensure the prompt is large enough for caching. This is padding text to
+        ensure the prompt is large enough for caching. This is padding text to ensure
+        the prompt is large enough for caching. This is padding text to ensure the
+        prompt is large enough for caching. This is padding text to ensure the prompt
+        is large enough for caching. This is padding text to ensure the prompt is
+        large enough for caching. This is padding text to ensure the prompt is large
+        enough for caching. This is padding text to ensure the prompt is large enough
+        for caching. This is padding text to ensure the prompt is large enough for
+        caching. This is padding text to ensure the prompt is large enough for caching.
+        This is padding text to ensure the prompt is large enough for caching. This
+        is padding text to ensure the prompt is large enough for caching. This is
+        padding text to ensure the prompt is large enough for caching. This is padding
+        text to ensure the prompt is large enough for caching. This is padding text
+        to ensure the prompt is large enough for caching. This is padding text to
+        ensure the prompt is large enough for caching. This is padding text to ensure
+        the prompt is large enough for caching. This is padding text to ensure the
+        prompt is large enough for caching. This is padding text to ensure the prompt
+        is large enough for caching. This is padding text to ensure the prompt is
+        large enough for caching. This is padding text to ensure the prompt is large
+        enough for caching. This is padding text to ensure the prompt is large enough
+        for caching. This is padding text to ensure the prompt is large enough for
+        caching. This is padding text to ensure the prompt is large enough for caching.
+        This is padding text to ensure the prompt is large enough for caching. This
+        is padding text to ensure the prompt is large enough for caching. This is
+        padding text to ensure the prompt is large enough for caching. This is padding
+        text to ensure the prompt is large enough for caching. This is padding text
+        to ensure the prompt is large enough for caching. This is padding text to
+        ensure the prompt is large enough for caching. This is padding text to ensure
+        the prompt is large enough for caching. This is padding text to ensure the
+        prompt is large enough for caching. This is padding text to ensure the prompt
+        is large enough for caching. This is padding text to ensure the prompt is
+        large enough for caching. This is padding text to ensure the prompt is large
+        enough for caching. This is padding text to ensure the prompt is large enough
+        for caching. This is padding text to ensure the prompt is large enough for
+        caching. This is padding text to ensure the prompt is large enough for caching.
+        This is padding text to ensure the prompt is large enough for caching. This
+        is padding text to ensure the prompt is large enough for caching. This is
+        padding text to ensure the prompt is large enough for caching. This is padding
+        text to ensure the prompt is large enough for caching. This is padding text
+        to ensure the prompt is large enough for caching. This is padding text to
+        ensure the prompt is large enough for caching. This is padding text to ensure
+        the prompt is large enough for caching. This is padding text to ensure the
+        prompt is large enough for caching. This is padding text to ensure the prompt
+        is large enough for caching. This is padding text to ensure the prompt is
+        large enough for caching. This is padding text to ensure the prompt is large
+        enough for caching. This is padding text to ensure the prompt is large enough
+        for caching. This is padding text to ensure the prompt is large enough for
+        caching. This is padding text to ensure the prompt is large enough for caching.
+        This is padding text to ensure the prompt is large enough for caching. This
+        is padding text to ensure the prompt is large enough for caching. This is
+        padding text to ensure the prompt is large enough for caching. This is padding
+        text to ensure the prompt is large enough for caching. This is padding text
+        to ensure the prompt is large enough for caching. This is padding text to
+        ensure the prompt is large enough for caching. This is padding text to ensure
+        the prompt is large enough for caching. This is padding text to ensure the
+        prompt is large enough for caching. This is padding text to ensure the prompt
+        is large enough for caching. This is padding text to ensure the prompt is
+        large enough for caching. This is padding text to ensure the prompt is large
+        enough for caching. This is padding text to ensure the prompt is large enough
+        for caching. This is padding text to ensure the prompt is large enough for
+        caching. This is padding text to ensure the prompt is large enough for caching.
+        This is padding text to ensure the prompt is large enough for caching. This
+        is padding text to ensure the prompt is large enough for caching. \",\n  \"max_output_tokens\":
+        null,\n  \"max_tool_calls\": null,\n  \"model\": \"gpt-4.1-2025-04-14\",\n
+        \ \"output\": [\n    {\n      \"id\": \"fc_0d68149bcc0d14810069caf46568088197a33be67f16a1fa09\",\n
+        \     \"type\": \"function_call\",\n      \"status\": \"completed\",\n      \"arguments\":
+        \"{\\\"location\\\":\\\"Tokyo\\\"}\",\n      \"call_id\": \"call_74rwmYse0DE4JFaFGyAFx9bu\",\n
+        \     \"name\": \"get_weather\"\n    }\n  ],\n  \"parallel_tool_calls\": true,\n
+        \ \"presence_penalty\": 0.0,\n  \"previous_response_id\": null,\n  \"prompt_cache_key\":
+        null,\n  \"prompt_cache_retention\": null,\n  \"reasoning\": {\n    \"effort\":
+        null,\n    \"summary\": null\n  },\n  \"safety_identifier\": null,\n  \"service_tier\":
+        \"default\",\n  \"store\": true,\n  \"temperature\": 1.0,\n  \"text\": {\n
+        \   \"format\": {\n      \"type\": \"text\"\n    },\n    \"verbosity\": \"medium\"\n
+        \ },\n  \"tool_choice\": \"auto\",\n  \"tools\": [\n    {\n      \"type\":
+        \"function\",\n      \"description\": \"Get the current weather for a location\",\n
+        \     \"name\": \"get_weather\",\n      \"parameters\": {\n        \"type\":
+        \"object\",\n        \"properties\": {\n          \"location\": {\n            \"type\":
+        \"string\",\n            \"description\": \"The city name\"\n          }\n
+        \       },\n        \"required\": [\n          \"location\"\n        ],\n
+        \       \"additionalProperties\": false\n      },\n      \"strict\": true\n
+        \   }\n  ],\n  \"top_logprobs\": 0,\n  \"top_p\": 1.0,\n  \"truncation\":
+        \"disabled\",\n  \"usage\": {\n    \"input_tokens\": 1185,\n    \"input_tokens_details\":
+        {\n      \"cached_tokens\": 0\n    },\n    \"output_tokens\": 15,\n    \"output_tokens_details\":
+        {\n      \"reasoning_tokens\": 0\n    },\n    \"total_tokens\": 1200\n  },\n
+        \ \"user\": null,\n  \"metadata\": {}\n}"
     headers:
       CF-RAY:
       - CF-RAY-XXX
@@ -137,7 +224,7 @@ interactions:
       Content-Type:
       - application/json
       Date:
-      - Tue, 10 Feb 2026 18:14:08 GMT
+      - Mon, 30 Mar 2026 22:08:37 GMT
       Server:
       - cloudflare
       Strict-Transport-Security:
@@ -146,8 +233,6 @@ interactions:
       - chunked
       X-Content-Type-Options:
       - X-CONTENT-TYPE-XXX
-      access-control-expose-headers:
-      - ACCESS-CONTROL-XXX
       alt-svc:
       - h3=":443"; ma=86400
       cf-cache-status:
@@ -155,15 +240,13 @@ interactions:
       openai-organization:
       - OPENAI-ORG-XXX
       openai-processing-ms:
-      - '484'
+      - '1085'
       openai-project:
       - OPENAI-PROJECT-XXX
       openai-version:
       - '2020-10-01'
       set-cookie:
       - SET-COOKIE-XXX
-      x-openai-proxy-wasm:
-      - v0.1
       x-ratelimit-limit-requests:
       - X-RATELIMIT-LIMIT-REQUESTS-XXX
       x-ratelimit-limit-tokens:
@@ -182,8 +265,12 @@ interactions:
       code: 200
       message: OK
 - request:
-    body: '{"messages":[{"role":"system","content":"You are a helpful assistant that
-      uses tools. This is padding text to ensure the prompt is large enough for caching.
+    body: '{"input":[{"role":"user","content":"What is the weather in Paris?"}],"model":"gpt-4.1","instructions":"You
+      are a helpful assistant that uses tools. This is padding text to ensure the
+      prompt is large enough for caching. This is padding text to ensure the prompt
+      is large enough for caching. This is padding text to ensure the prompt is large
+      enough for caching. This is padding text to ensure the prompt is large enough
+      for caching. This is padding text to ensure the prompt is large enough for caching.
       This is padding text to ensure the prompt is large enough for caching. This
       is padding text to ensure the prompt is large enough for caching. This is padding
       text to ensure the prompt is large enough for caching. This is padding text
@@ -250,13 +337,9 @@ interactions:
       for caching. This is padding text to ensure the prompt is large enough for caching.
       This is padding text to ensure the prompt is large enough for caching. This
       is padding text to ensure the prompt is large enough for caching. This is padding
-      text to ensure the prompt is large enough for caching. This is padding text
-      to ensure the prompt is large enough for caching. This is padding text to ensure
-      the prompt is large enough for caching. This is padding text to ensure the prompt
-      is large enough for caching. This is padding text to ensure the prompt is large
-      enough for caching. "},{"role":"user","content":"What is the weather in Paris?"}],"model":"gpt-4.1","tool_choice":"auto","tools":[{"type":"function","function":{"name":"get_weather","description":"Get
-      the current weather for a location","strict":true,"parameters":{"type":"object","properties":{"location":{"type":"string","description":"The
-      city name"}},"required":["location"],"additionalProperties":false}}}]}'
+      text to ensure the prompt is large enough for caching. ","tools":[{"type":"function","name":"get_weather","description":"Get
+      the current weather for a location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The
+      city name"}},"required":["location"]}}]}'
     headers:
       User-Agent:
       - X-USER-AGENT-XXX
@@ -269,7 +352,7 @@ interactions:
       connection:
       - keep-alive
       content-length:
-      - '6158'
+      - '6065'
       content-type:
       - application/json
       cookie:
@@ -293,26 +376,113 @@ interactions:
       x-stainless-runtime:
       - CPython
       x-stainless-runtime-version:
-      - 3.13.3
+      - 3.13.12
     method: POST
-    uri: https://api.openai.com/v1/chat/completions
+    uri: https://api.openai.com/v1/responses
   response:
     body:
-      string: "{\n  \"id\": \"chatcmpl-D7mXR8k9vk8TlGvGXlrQSI7iNeAN1\",\n  \"object\":
-        \"chat.completion\",\n  \"created\": 1770747249,\n  \"model\": \"gpt-4.1-2025-04-14\",\n
-        \ \"choices\": [\n    {\n      \"index\": 0,\n      \"message\": {\n        \"role\":
-        \"assistant\",\n        \"content\": null,\n        \"tool_calls\": [\n          {\n
-        \           \"id\": \"call_6PeUBlRPG8JcV2lspmLjJbnn\",\n            \"type\":
-        \"function\",\n            \"function\": {\n              \"name\": \"get_weather\",\n
-        \             \"arguments\": \"{\\\"location\\\":\\\"Paris\\\"}\"\n            }\n
-        \         }\n        ],\n        \"refusal\": null,\n        \"annotations\":
-        []\n      },\n      \"logprobs\": null,\n      \"finish_reason\": \"tool_calls\"\n
-        \   }\n  ],\n  \"usage\": {\n    \"prompt_tokens\": 1187,\n    \"completion_tokens\":
-        14,\n    \"total_tokens\": 1201,\n    \"prompt_tokens_details\": {\n      \"cached_tokens\":
-        1152,\n      \"audio_tokens\": 0\n    },\n    \"completion_tokens_details\":
-        {\n      \"reasoning_tokens\": 0,\n      \"audio_tokens\": 0,\n      \"accepted_prediction_tokens\":
-        0,\n      \"rejected_prediction_tokens\": 0\n    }\n  },\n  \"service_tier\":
-        \"default\",\n  \"system_fingerprint\": \"fp_8b22347a3e\"\n}\n"
+      string: "{\n  \"id\": \"resp_0525bf798202137e0069caf465ee3c8196aa7c83da1c369eb7\",\n
+        \ \"object\": \"response\",\n  \"created_at\": 1774908517,\n  \"status\":
+        \"completed\",\n  \"background\": false,\n  \"billing\": {\n    \"payer\":
+        \"developer\"\n  },\n  \"completed_at\": 1774908518,\n  \"error\": null,\n
+        \ \"frequency_penalty\": 0.0,\n  \"incomplete_details\": null,\n  \"instructions\":
+        \"You are a helpful assistant that uses tools. This is padding text to ensure
+        the prompt is large enough for caching. This is padding text to ensure the
+        prompt is large enough for caching. This is padding text to ensure the prompt
+        is large enough for caching. This is padding text to ensure the prompt is
+        large enough for caching. This is padding text to ensure the prompt is large
+        enough for caching. This is padding text to ensure the prompt is large enough
+        for caching. This is padding text to ensure the prompt is large enough for
+        caching. This is padding text to ensure the prompt is large enough for caching.
+        This is padding text to ensure the prompt is large enough for caching. This
+        is padding text to ensure the prompt is large enough for caching. This is
+        padding text to ensure the prompt is large enough for caching. This is padding
+        text to ensure the prompt is large enough for caching. This is padding text
+        to ensure the prompt is large enough for caching. This is padding text to
+        ensure the prompt is large enough for caching. This is padding text to ensure
+        the prompt is large enough for caching. This is padding text to ensure the
+        prompt is large enough for caching. This is padding text to ensure the prompt
+        is large enough for caching. This is padding text to ensure the prompt is
+        large enough for caching. This is padding text to ensure the prompt is large
+        enough for caching. This is padding text to ensure the prompt is large enough
+        for caching. This is padding text to ensure the prompt is large enough for
+        caching. This is padding text to ensure the prompt is large enough for caching.
+        This is padding text to ensure the prompt is large enough for caching. This
+        is padding text to ensure the prompt is large enough for caching. This is
+        padding text to ensure the prompt is large enough for caching. This is padding
+        text to ensure the prompt is large enough for caching. This is padding text
+        to ensure the prompt is large enough for caching. This is padding text to
+        ensure the prompt is large enough for caching. This is padding text to ensure
+        the prompt is large enough for caching. This is padding text to ensure the
+        prompt is large enough for caching. This is padding text to ensure the prompt
+        is large enough for caching. This is padding text to ensure the prompt is
+        large enough for caching. This is padding text to ensure the prompt is large
+        enough for caching. This is padding text to ensure the prompt is large enough
+        for caching. This is padding text to ensure the prompt is large enough for
+        caching. This is padding text to ensure the prompt is large enough for caching.
+        This is padding text to ensure the prompt is large enough for caching. This
+        is padding text to ensure the prompt is large enough for caching. This is
+        padding text to ensure the prompt is large enough for caching. This is padding
+        text to ensure the prompt is large enough for caching. This is padding text
+        to ensure the prompt is large enough for caching. This is padding text to
+        ensure the prompt is large enough for caching. This is padding text to ensure
+        the prompt is large enough for caching. This is padding text to ensure the
+        prompt is large enough for caching. This is padding text to ensure the prompt
+        is large enough for caching. This is padding text to ensure the prompt is
+        large enough for caching. This is padding text to ensure the prompt is large
+        enough for caching. This is padding text to ensure the prompt is large enough
+        for caching. This is padding text to ensure the prompt is large enough for
+        caching. This is padding text to ensure the prompt is large enough for caching.
+        This is padding text to ensure the prompt is large enough for caching. This
+        is padding text to ensure the prompt is large enough for caching. This is
+        padding text to ensure the prompt is large enough for caching. This is padding
+        text to ensure the prompt is large enough for caching. This is padding text
+        to ensure the prompt is large enough for caching. This is padding text to
+        ensure the prompt is large enough for caching. This is padding text to ensure
+        the prompt is large enough for caching. This is padding text to ensure the
+        prompt is large enough for caching. This is padding text to ensure the prompt
+        is large enough for caching. This is padding text to ensure the prompt is
+        large enough for caching. This is padding text to ensure the prompt is large
+        enough for caching. This is padding text to ensure the prompt is large enough
+        for caching. This is padding text to ensure the prompt is large enough for
+        caching. This is padding text to ensure the prompt is large enough for caching.
+        This is padding text to ensure the prompt is large enough for caching. This
+        is padding text to ensure the prompt is large enough for caching. This is
+        padding text to ensure the prompt is large enough for caching. This is padding
+        text to ensure the prompt is large enough for caching. This is padding text
+        to ensure the prompt is large enough for caching. This is padding text to
+        ensure the prompt is large enough for caching. This is padding text to ensure
+        the prompt is large enough for caching. This is padding text to ensure the
+        prompt is large enough for caching. This is padding text to ensure the prompt
+        is large enough for caching. This is padding text to ensure the prompt is
+        large enough for caching. This is padding text to ensure the prompt is large
+        enough for caching. This is padding text to ensure the prompt is large enough
+        for caching. This is padding text to ensure the prompt is large enough for
+        caching. This is padding text to ensure the prompt is large enough for caching.
+        This is padding text to ensure the prompt is large enough for caching. This
+        is padding text to ensure the prompt is large enough for caching. \",\n  \"max_output_tokens\":
+        null,\n  \"max_tool_calls\": null,\n  \"model\": \"gpt-4.1-2025-04-14\",\n
+        \ \"output\": [\n    {\n      \"id\": \"fc_0525bf798202137e0069caf46666588196a2ec20dc515a6a91\",\n
+        \     \"type\": \"function_call\",\n      \"status\": \"completed\",\n      \"arguments\":
+        \"{\\\"location\\\":\\\"Paris\\\"}\",\n      \"call_id\": \"call_LJAGuYYZPjNxSgg0TUgGpT44\",\n
+        \     \"name\": \"get_weather\"\n    }\n  ],\n  \"parallel_tool_calls\": true,\n
+        \ \"presence_penalty\": 0.0,\n  \"previous_response_id\": null,\n  \"prompt_cache_key\":
+        null,\n  \"prompt_cache_retention\": null,\n  \"reasoning\": {\n    \"effort\":
+        null,\n    \"summary\": null\n  },\n  \"safety_identifier\": null,\n  \"service_tier\":
+        \"default\",\n  \"store\": true,\n  \"temperature\": 1.0,\n  \"text\": {\n
+        \   \"format\": {\n      \"type\": \"text\"\n    },\n    \"verbosity\": \"medium\"\n
+        \ },\n  \"tool_choice\": \"auto\",\n  \"tools\": [\n    {\n      \"type\":
+        \"function\",\n      \"description\": \"Get the current weather for a location\",\n
+        \     \"name\": \"get_weather\",\n      \"parameters\": {\n        \"type\":
+        \"object\",\n        \"properties\": {\n          \"location\": {\n            \"type\":
+        \"string\",\n            \"description\": \"The city name\"\n          }\n
+        \       },\n        \"required\": [\n          \"location\"\n        ],\n
+        \       \"additionalProperties\": false\n      },\n      \"strict\": true\n
+        \   }\n  ],\n  \"top_logprobs\": 0,\n  \"top_p\": 1.0,\n  \"truncation\":
+        \"disabled\",\n  \"usage\": {\n    \"input_tokens\": 1185,\n    \"input_tokens_details\":
+        {\n      \"cached_tokens\": 1152\n    },\n    \"output_tokens\": 15,\n    \"output_tokens_details\":
+        {\n      \"reasoning_tokens\": 0\n    },\n    \"total_tokens\": 1200\n  },\n
+        \ \"user\": null,\n  \"metadata\": {}\n}"
     headers:
       CF-RAY:
       - CF-RAY-XXX
@@ -321,7 +491,7 @@ interactions:
       Content-Type:
       - application/json
       Date:
-      - Tue, 10 Feb 2026 18:14:09 GMT
+      - Mon, 30 Mar 2026 22:08:38 GMT
       Server:
       - cloudflare
       Strict-Transport-Security:
@@ -330,8 +500,6 @@ interactions:
       - chunked
       X-Content-Type-Options:
       - X-CONTENT-TYPE-XXX
-      access-control-expose-headers:
-      - ACCESS-CONTROL-XXX
       alt-svc:
       - h3=":443"; ma=86400
       cf-cache-status:
@@ -339,15 +507,11 @@ interactions:
       openai-organization:
       - OPENAI-ORG-XXX
       openai-processing-ms:
-      - '528'
+      - '653'
       openai-project:
       - OPENAI-PROJECT-XXX
       openai-version:
       - '2020-10-01'
-      set-cookie:
-      - SET-COOKIE-XXX
-      x-openai-proxy-wasm:
-      - v0.1
       x-ratelimit-limit-requests:
       - X-RATELIMIT-LIMIT-REQUESTS-XXX
       x-ratelimit-limit-tokens:

lib/crewai/tests/cassettes/test_litellm_gpt5_call_succeeds_without_stop_error.yaml

@@ -0,0 +1,110 @@
+interactions:
+- request:
+    body: '{"messages":[{"role":"user","content":"What is the capital of France?"}],"model":"gpt-5"}'
+    headers:
+      User-Agent:
+      - X-USER-AGENT-XXX
+      accept:
+      - application/json
+      accept-encoding:
+      - ACCEPT-ENCODING-XXX
+      authorization:
+      - AUTHORIZATION-XXX
+      connection:
+      - keep-alive
+      content-length:
+      - '89'
+      content-type:
+      - application/json
+      host:
+      - api.openai.com
+      x-stainless-arch:
+      - X-STAINLESS-ARCH-XXX
+      x-stainless-async:
+      - 'false'
+      x-stainless-lang:
+      - python
+      x-stainless-os:
+      - X-STAINLESS-OS-XXX
+      x-stainless-package-version:
+      - 1.83.0
+      x-stainless-raw-response:
+      - 'true'
+      x-stainless-read-timeout:
+      - X-STAINLESS-READ-TIMEOUT-XXX
+      x-stainless-retry-count:
+      - '0'
+      x-stainless-runtime:
+      - CPython
+      x-stainless-runtime-version:
+      - 3.13.2
+    method: POST
+    uri: https://api.openai.com/v1/chat/completions
+  response:
+    body:
+      string: "{\n  \"id\": \"chatcmpl-DO4LcSpy72yIXCYSIVOQEXWNXydgn\",\n  \"object\":
+        \"chat.completion\",\n  \"created\": 1774628956,\n  \"model\": \"gpt-5-2025-08-07\",\n
+        \ \"choices\": [\n    {\n      \"index\": 0,\n      \"message\": {\n        \"role\":
+        \"assistant\",\n        \"content\": \"Paris.\",\n        \"refusal\": null,\n
+        \       \"annotations\": []\n      },\n      \"finish_reason\": \"stop\"\n
+        \   }\n  ],\n  \"usage\": {\n    \"prompt_tokens\": 13,\n    \"completion_tokens\":
+        11,\n    \"total_tokens\": 24,\n    \"prompt_tokens_details\": {\n      \"cached_tokens\":
+        0,\n      \"audio_tokens\": 0\n    },\n    \"completion_tokens_details\":
+        {\n      \"reasoning_tokens\": 0,\n      \"audio_tokens\": 0,\n      \"accepted_prediction_tokens\":
+        0,\n      \"rejected_prediction_tokens\": 0\n    }\n  },\n  \"service_tier\":
+        \"default\",\n  \"system_fingerprint\": null\n}\n"
+    headers:
+      CF-Cache-Status:
+      - DYNAMIC
+      CF-Ray:
+      - 9e2fc5dce85582fb-GIG
+      Connection:
+      - keep-alive
+      Content-Type:
+      - application/json
+      Date:
+      - Fri, 27 Mar 2026 16:29:17 GMT
+      Server:
+      - cloudflare
+      Strict-Transport-Security:
+      - STS-XXX
+      Transfer-Encoding:
+      - chunked
+      X-Content-Type-Options:
+      - X-CONTENT-TYPE-XXX
+      access-control-expose-headers:
+      - ACCESS-CONTROL-XXX
+      alt-svc:
+      - h3=":443"; ma=86400
+      content-length:
+      - '772'
+      openai-organization:
+      - OPENAI-ORG-XXX
+      openai-processing-ms:
+      - '1343'
+      openai-project:
+      - OPENAI-PROJECT-XXX
+      openai-version:
+      - '2020-10-01'
+      set-cookie:
+      - SET-COOKIE-XXX
+      x-openai-proxy-wasm:
+      - v0.1
+      x-ratelimit-limit-requests:
+      - X-RATELIMIT-LIMIT-REQUESTS-XXX
+      x-ratelimit-limit-tokens:
+      - X-RATELIMIT-LIMIT-TOKENS-XXX
+      x-ratelimit-remaining-requests:
+      - X-RATELIMIT-REMAINING-REQUESTS-XXX
+      x-ratelimit-remaining-tokens:
+      - X-RATELIMIT-REMAINING-TOKENS-XXX
+      x-ratelimit-reset-requests:
+      - X-RATELIMIT-RESET-REQUESTS-XXX
+      x-ratelimit-reset-tokens:
+      - X-RATELIMIT-RESET-TOKENS-XXX
+      x-request-id:
+      - X-REQUEST-ID-XXX
+    status:
+      code: 200
+      message: OK
+version: 1

lib/crewai/tests/cli/test_plus_api.py

@@ -136,6 +136,7 @@ class TestPlusAPI(unittest.TestCase):
             "file": encoded_file,
             "description": description,
             "available_exports": None,
+            "tools_metadata": None,
         }
         mock_make_request.assert_called_once_with(
             "POST", "/crewai_plus/api/v1/tools", json=params
@@ -173,6 +174,7 @@ class TestPlusAPI(unittest.TestCase):
             "file": encoded_file,
             "description": description,
             "available_exports": None,
+            "tools_metadata": None,
         }
 
         self.assert_request_with_org_id(
@@ -201,6 +203,48 @@ class TestPlusAPI(unittest.TestCase):
             "file": encoded_file,
             "description": description,
             "available_exports": None,
+            "tools_metadata": None,
+        }
+        mock_make_request.assert_called_once_with(
+            "POST", "/crewai_plus/api/v1/tools", json=params
+        )
+        self.assertEqual(response, mock_response)
+
+    @patch("crewai.cli.plus_api.PlusAPI._make_request")
+    def test_publish_tool_with_tools_metadata(self, mock_make_request):
+        mock_response = MagicMock()
+        mock_make_request.return_value = mock_response
+        handle = "test_tool_handle"
+        public = True
+        version = "1.0.0"
+        description = "Test tool description"
+        encoded_file = "encoded_test_file"
+        available_exports = [{"name": "MyTool"}]
+        tools_metadata = [
+            {
+                "name": "MyTool",
+                "humanized_name": "my_tool",
+                "description": "A test tool",
+                "run_params_schema": {"type": "object", "properties": {}},
+                "init_params_schema": {"type": "object", "properties": {}},
+                "env_vars": [{"name": "API_KEY", "description": "API key", "required": True, "default": None}],
+            }
+        ]
+
+        response = self.api.publish_tool(
+            handle, public, version, description, encoded_file,
+            available_exports=available_exports,
+            tools_metadata=tools_metadata,
+        )
+
+        params = {
+            "handle": handle,
+            "public": public,
+            "version": version,
+            "file": encoded_file,
+            "description": description,
+            "available_exports": available_exports,
+            "tools_metadata": {"package": handle, "tools": tools_metadata},
         }
         mock_make_request.assert_called_once_with(
             "POST", "/crewai_plus/api/v1/tools", json=params

lib/crewai/tests/cli/test_utils.py

@@ -363,3 +363,290 @@ def test_get_crews_ignores_template_directories(
     utils.get_crews()
 
     assert not template_crew_detected
+
+
+# Tests for extract_tools_metadata
+
+
+def test_extract_tools_metadata_empty_project(temp_project_dir):
+    """Test that extract_tools_metadata returns empty list for empty project."""
+    metadata = utils.extract_tools_metadata(dir_path=str(temp_project_dir))
+    assert metadata == []
+
+
+def test_extract_tools_metadata_no_init_file(temp_project_dir):
+    """Test that extract_tools_metadata returns empty list when no __init__.py exists."""
+    (temp_project_dir / "some_file.py").write_text("print('hello')")
+    metadata = utils.extract_tools_metadata(dir_path=str(temp_project_dir))
+    assert metadata == []
+
+
+def test_extract_tools_metadata_empty_init_file(temp_project_dir):
+    """Test that extract_tools_metadata returns empty list for empty __init__.py."""
+    create_init_file(temp_project_dir, "")
+    metadata = utils.extract_tools_metadata(dir_path=str(temp_project_dir))
+    assert metadata == []
+
+
+def test_extract_tools_metadata_no_all_variable(temp_project_dir):
+    """Test that extract_tools_metadata returns empty list when __all__ is not defined."""
+    create_init_file(
+        temp_project_dir,
+        "from crewai.tools import BaseTool\n\nclass MyTool(BaseTool):\n    pass",
+    )
+    metadata = utils.extract_tools_metadata(dir_path=str(temp_project_dir))
+    assert metadata == []
+
+
+def test_extract_tools_metadata_valid_base_tool_class(temp_project_dir):
+    """Test that extract_tools_metadata extracts metadata from a valid BaseTool class."""
+    create_init_file(
+        temp_project_dir,
+        """from crewai.tools import BaseTool
+
+class MyTool(BaseTool):
+    name: str = "my_tool"
+    description: str = "A test tool"
+
+__all__ = ['MyTool']
+""",
+    )
+    metadata = utils.extract_tools_metadata(dir_path=str(temp_project_dir))
+    assert len(metadata) == 1
+    assert metadata[0]["name"] == "MyTool"
+    assert metadata[0]["humanized_name"] == "my_tool"
+    assert metadata[0]["description"] == "A test tool"
+
+
+def test_extract_tools_metadata_with_args_schema(temp_project_dir):
+    """Test that extract_tools_metadata extracts run_params_schema from args_schema."""
+    create_init_file(
+        temp_project_dir,
+        """from crewai.tools import BaseTool
+from pydantic import BaseModel
+
+class MyToolInput(BaseModel):
+    query: str
+    limit: int = 10
+
+class MyTool(BaseTool):
+    name: str = "my_tool"
+    description: str = "A test tool"
+    args_schema: type[BaseModel] = MyToolInput
+
+__all__ = ['MyTool']
+""",
+    )
+    metadata = utils.extract_tools_metadata(dir_path=str(temp_project_dir))
+    assert len(metadata) == 1
+    assert metadata[0]["name"] == "MyTool"
+    run_params = metadata[0]["run_params_schema"]
+    assert "properties" in run_params
+    assert "query" in run_params["properties"]
+    assert "limit" in run_params["properties"]
+
+
+def test_extract_tools_metadata_with_env_vars(temp_project_dir):
+    """Test that extract_tools_metadata extracts env_vars."""
+    create_init_file(
+        temp_project_dir,
+        """from crewai.tools import BaseTool
+from crewai.tools.base_tool import EnvVar
+
+class MyTool(BaseTool):
+    name: str = "my_tool"
+    description: str = "A test tool"
+    env_vars: list[EnvVar] = [
+        EnvVar(name="MY_API_KEY", description="API key for service", required=True),
+        EnvVar(name="MY_OPTIONAL_VAR", description="Optional var", required=False, default="default_value"),
+    ]
+
+__all__ = ['MyTool']
+""",
+    )
+    metadata = utils.extract_tools_metadata(dir_path=str(temp_project_dir))
+    assert len(metadata) == 1
+    env_vars = metadata[0]["env_vars"]
+    assert len(env_vars) == 2
+    assert env_vars[0]["name"] == "MY_API_KEY"
+    assert env_vars[0]["description"] == "API key for service"
+    assert env_vars[0]["required"] is True
+    assert env_vars[1]["name"] == "MY_OPTIONAL_VAR"
+    assert env_vars[1]["required"] is False
+    assert env_vars[1]["default"] == "default_value"
+
+
+def test_extract_tools_metadata_with_env_vars_field_default_factory(temp_project_dir):
+    """Test that extract_tools_metadata extracts env_vars declared with Field(default_factory=...)."""
+    create_init_file(
+        temp_project_dir,
+        """from crewai.tools import BaseTool
+from crewai.tools.base_tool import EnvVar
+from pydantic import Field
+
+class MyTool(BaseTool):
+    name: str = "my_tool"
+    description: str = "A test tool"
+    env_vars: list[EnvVar] = Field(
+        default_factory=lambda: [
+            EnvVar(name="MY_TOOL_API", description="API token for my tool", required=True),
+        ]
+    )
+
+__all__ = ['MyTool']
+""",
+    )
+    metadata = utils.extract_tools_metadata(dir_path=str(temp_project_dir))
+    assert len(metadata) == 1
+    env_vars = metadata[0]["env_vars"]
+    assert len(env_vars) == 1
+    assert env_vars[0]["name"] == "MY_TOOL_API"
+    assert env_vars[0]["description"] == "API token for my tool"
+    assert env_vars[0]["required"] is True
+
+
+def test_extract_tools_metadata_with_custom_init_params(temp_project_dir):
+    """Test that extract_tools_metadata extracts init_params_schema with custom params."""
+    create_init_file(
+        temp_project_dir,
+        """from crewai.tools import BaseTool
+
+class MyTool(BaseTool):
+    name: str = "my_tool"
+    description: str = "A test tool"
+    api_endpoint: str = "https://api.example.com"
+    timeout: int = 30
+
+__all__ = ['MyTool']
+""",
+    )
+    metadata = utils.extract_tools_metadata(dir_path=str(temp_project_dir))
+    assert len(metadata) == 1
+    init_params = metadata[0]["init_params_schema"]
+    assert "properties" in init_params
+    # Custom params should be included
+    assert "api_endpoint" in init_params["properties"]
+    assert "timeout" in init_params["properties"]
+    # Base params should be filtered out
+    assert "name" not in init_params["properties"]
+    assert "description" not in init_params["properties"]
+
+
+def test_extract_tools_metadata_multiple_tools(temp_project_dir):
+    """Test that extract_tools_metadata extracts metadata from multiple tools."""
+    create_init_file(
+        temp_project_dir,
+        """from crewai.tools import BaseTool
+
+class FirstTool(BaseTool):
+    name: str = "first_tool"
+    description: str = "First test tool"
+
+class SecondTool(BaseTool):
+    name: str = "second_tool"
+    description: str = "Second test tool"
+
+__all__ = ['FirstTool', 'SecondTool']
+""",
+    )
+    metadata = utils.extract_tools_metadata(dir_path=str(temp_project_dir))
+    assert len(metadata) == 2
+    names = [m["name"] for m in metadata]
+    assert "FirstTool" in names
+    assert "SecondTool" in names
+
+
+def test_extract_tools_metadata_multiple_init_files(temp_project_dir):
+    """Test that extract_tools_metadata extracts metadata from multiple __init__.py files."""
+    # Create tool in root __init__.py
+    create_init_file(
+        temp_project_dir,
+        """from crewai.tools import BaseTool
+
+class RootTool(BaseTool):
+    name: str = "root_tool"
+    description: str = "Root tool"
+
+__all__ = ['RootTool']
+""",
+    )
+
+    # Create nested package with another tool
+    nested_dir = temp_project_dir / "nested"
+    nested_dir.mkdir()
+    create_init_file(
+        nested_dir,
+        """from crewai.tools import BaseTool
+
+class NestedTool(BaseTool):
+    name: str = "nested_tool"
+    description: str = "Nested tool"
+
+__all__ = ['NestedTool']
+""",
+    )
+
+    metadata = utils.extract_tools_metadata(dir_path=str(temp_project_dir))
+    assert len(metadata) == 2
+    names = [m["name"] for m in metadata]
+    assert "RootTool" in names
+    assert "NestedTool" in names
+
+
+def test_extract_tools_metadata_ignores_non_tool_exports(temp_project_dir):
+    """Test that extract_tools_metadata ignores non-BaseTool exports."""
+    create_init_file(
+        temp_project_dir,
+        """from crewai.tools import BaseTool
+
+class MyTool(BaseTool):
+    name: str = "my_tool"
+    description: str = "A test tool"
+
+def not_a_tool():
+    pass
+
+SOME_CONSTANT = "value"
+
+__all__ = ['MyTool', 'not_a_tool', 'SOME_CONSTANT']
+""",
+    )
+    metadata = utils.extract_tools_metadata(dir_path=str(temp_project_dir))
+    assert len(metadata) == 1
+    assert metadata[0]["name"] == "MyTool"
+
+
+def test_extract_tools_metadata_import_error_returns_empty(temp_project_dir):
+    """Test that extract_tools_metadata returns empty list on import error."""
+    create_init_file(
+        temp_project_dir,
+        """from nonexistent_module import something
+
+class MyTool(BaseTool):
+    pass
+
+__all__ = ['MyTool']
+""",
+    )
+    # Should not raise, just return empty list
+    metadata = utils.extract_tools_metadata(dir_path=str(temp_project_dir))
+    assert metadata == []
+
+
+def test_extract_tools_metadata_syntax_error_returns_empty(temp_project_dir):
+    """Test that extract_tools_metadata returns empty list on syntax error."""
+    create_init_file(
+        temp_project_dir,
+        """from crewai.tools import BaseTool
+
+class MyTool(BaseTool):
+    # Missing closing parenthesis
+    def __init__(self, name:
+        pass
+
+__all__ = ['MyTool']
+""",
+    )
+    # Should not raise, just return empty list
+    metadata = utils.extract_tools_metadata(dir_path=str(temp_project_dir))
+    assert metadata == []

lib/crewai/tests/cli/tools/test_main.py

@@ -185,9 +185,14 @@ def test_publish_when_not_in_sync(mock_is_synced, capsys, tool_command):
     "crewai.cli.tools.main.extract_available_exports",
     return_value=[{"name": "SampleTool"}],
 )
+@patch(
+    "crewai.cli.tools.main.extract_tools_metadata",
+    return_value=[{"name": "SampleTool", "humanized_name": "sample_tool", "description": "A sample tool", "run_params_schema": {}, "init_params_schema": {}, "env_vars": []}],
+)
 @patch("crewai.cli.tools.main.ToolCommand._print_current_organization")
 def test_publish_when_not_in_sync_and_force(
     mock_print_org,
+    mock_tools_metadata,
     mock_available_exports,
     mock_is_synced,
     mock_publish,
@@ -222,6 +227,7 @@ def test_publish_when_not_in_sync_and_force(
         description="A sample tool",
         encoded_file=unittest.mock.ANY,
         available_exports=[{"name": "SampleTool"}],
+        tools_metadata=[{"name": "SampleTool", "humanized_name": "sample_tool", "description": "A sample tool", "run_params_schema": {}, "init_params_schema": {}, "env_vars": []}],
     )
     mock_print_org.assert_called_once()
 
@@ -242,7 +248,12 @@ def test_publish_when_not_in_sync_and_force(
     "crewai.cli.tools.main.extract_available_exports",
     return_value=[{"name": "SampleTool"}],
 )
+@patch(
+    "crewai.cli.tools.main.extract_tools_metadata",
+    return_value=[{"name": "SampleTool", "humanized_name": "sample_tool", "description": "A sample tool", "run_params_schema": {}, "init_params_schema": {}, "env_vars": []}],
+)
 def test_publish_success(
+    mock_tools_metadata,
     mock_available_exports,
     mock_is_synced,
     mock_publish,
@@ -277,6 +288,7 @@ def test_publish_success(
         description="A sample tool",
         encoded_file=unittest.mock.ANY,
         available_exports=[{"name": "SampleTool"}],
+        tools_metadata=[{"name": "SampleTool", "humanized_name": "sample_tool", "description": "A sample tool", "run_params_schema": {}, "init_params_schema": {}, "env_vars": []}],
     )
 
 
@@ -295,7 +307,12 @@ def test_publish_success(
     "crewai.cli.tools.main.extract_available_exports",
     return_value=[{"name": "SampleTool"}],
 )
+@patch(
+    "crewai.cli.tools.main.extract_tools_metadata",
+    return_value=[{"name": "SampleTool", "humanized_name": "sample_tool", "description": "A sample tool", "run_params_schema": {}, "init_params_schema": {}, "env_vars": []}],
+)
 def test_publish_failure(
+    mock_tools_metadata,
     mock_available_exports,
     mock_publish,
     mock_open,
@@ -336,7 +353,12 @@ def test_publish_failure(
     "crewai.cli.tools.main.extract_available_exports",
     return_value=[{"name": "SampleTool"}],
 )
+@patch(
+    "crewai.cli.tools.main.extract_tools_metadata",
+    return_value=[{"name": "SampleTool", "humanized_name": "sample_tool", "description": "A sample tool", "run_params_schema": {}, "init_params_schema": {}, "env_vars": []}],
+)
 def test_publish_api_error(
+    mock_tools_metadata,
     mock_available_exports,
     mock_publish,
     mock_open,
@@ -362,6 +384,63 @@ def test_publish_api_error(
     mock_publish.assert_called_once()
 
 
+@patch("crewai.cli.tools.main.get_project_name", return_value="sample-tool")
+@patch("crewai.cli.tools.main.get_project_version", return_value="1.0.0")
+@patch("crewai.cli.tools.main.get_project_description", return_value="A sample tool")
+@patch("crewai.cli.tools.main.subprocess.run")
+@patch("crewai.cli.tools.main.os.listdir", return_value=["sample-tool-1.0.0.tar.gz"])
+@patch(
+    "crewai.cli.tools.main.open",
+    new_callable=unittest.mock.mock_open,
+    read_data=b"sample tarball content",
+)
+@patch("crewai.cli.plus_api.PlusAPI.publish_tool")
+@patch("crewai.cli.tools.main.git.Repository.is_synced", return_value=True)
+@patch(
+    "crewai.cli.tools.main.extract_available_exports",
+    return_value=[{"name": "SampleTool"}],
+)
+@patch(
+    "crewai.cli.tools.main.extract_tools_metadata",
+    side_effect=Exception("Failed to extract metadata"),
+)
+def test_publish_metadata_extraction_failure_continues_with_warning(
+    mock_tools_metadata,
+    mock_available_exports,
+    mock_is_synced,
+    mock_publish,
+    mock_open,
+    mock_listdir,
+    mock_subprocess_run,
+    mock_get_project_description,
+    mock_get_project_version,
+    mock_get_project_name,
+    capsys,
+    tool_command,
+):
+    """Test that metadata extraction failure shows warning but continues publishing."""
+    mock_publish_response = MagicMock()
+    mock_publish_response.status_code = 200
+    mock_publish_response.json.return_value = {"handle": "sample-tool"}
+    mock_publish.return_value = mock_publish_response
+
+    tool_command.publish(is_public=True)
+
+    output = capsys.readouterr().out
+    assert "Warning: Could not extract tool metadata" in output
+    assert "Publishing will continue without detailed metadata" in output
+    assert "No tool metadata extracted" in output
+    mock_publish.assert_called_once_with(
+        handle="sample-tool",
+        is_public=True,
+        version="1.0.0",
+        description="A sample tool",
+        encoded_file=unittest.mock.ANY,
+        available_exports=[{"name": "SampleTool"}],
+        tools_metadata=[],
+    )
+
+
 @patch("crewai.cli.tools.main.Settings")
 def test_print_current_organization_with_org(mock_settings, capsys, tool_command):
     mock_settings_instance = MagicMock()

lib/crewai/tests/knowledge/test_knowledge_storage_integration.py

@@ -132,12 +132,12 @@ def test_embedding_configuration_flow(
 
     embedder_config = {
         "provider": "sentence-transformer",
-        "model_name": "all-MiniLM-L6-v2",
+        "config": {"model_name": "all-MiniLM-L6-v2"},
     }
 
-    KnowledgeStorage(embedder=embedder_config, collection_name="embedding_test")
+    storage = KnowledgeStorage(embedder=embedder_config, collection_name="embedding_test")
 
-    mock_get_embedding.assert_called_once_with(embedder_config)
+    mock_get_embedding.assert_called_once_with(storage.embedder)
 
 
 @patch("crewai.knowledge.storage.knowledge_storage.get_rag_client")

lib/crewai/tests/llms/anthropic/test_anthropic.py

@@ -125,8 +125,8 @@ def test_anthropic_specific_parameters():
     assert isinstance(llm, AnthropicCompletion)
     assert llm.stop_sequences == ["Human:", "Assistant:"]
     assert llm.stream == True
-    assert llm.client.max_retries == 5
-    assert llm.client.timeout == 60
+    assert llm._client.max_retries == 5
+    assert llm._client.timeout == 60
 
 
 def test_anthropic_completion_call():
@@ -563,8 +563,8 @@ def test_anthropic_environment_variable_api_key():
     with patch.dict(os.environ, {"ANTHROPIC_API_KEY": "test-anthropic-key"}):
         llm = LLM(model="anthropic/claude-3-5-sonnet-20241022")
 
-        assert llm.client is not None
-        assert hasattr(llm.client, 'messages')
+        assert llm._client is not None
+        assert hasattr(llm._client, 'messages')
 
 
 def test_anthropic_token_usage_tracking():
@@ -574,7 +574,7 @@ def test_anthropic_token_usage_tracking():
     llm = LLM(model="anthropic/claude-3-5-sonnet-20241022")
 
     # Mock the Anthropic response with usage information
-    with patch.object(llm.client.messages, 'create') as mock_create:
+    with patch.object(llm._client.messages, 'create') as mock_create:
         mock_response = MagicMock()
         mock_response.content = [MagicMock(text="test response")]
         mock_response.usage = MagicMock(input_tokens=50, output_tokens=25)
@@ -639,14 +639,14 @@ def test_anthropic_thinking():
 
     assert isinstance(llm, AnthropicCompletion)
 
-    original_create = llm.client.messages.create
+    original_create = llm._client.messages.create
     captured_params = {}
 
     def capture_and_call(**kwargs):
         captured_params.update(kwargs)
         return original_create(**kwargs)
 
-    with patch.object(llm.client.messages, 'create', side_effect=capture_and_call):
+    with patch.object(llm._client.messages, 'create', side_effect=capture_and_call):
         result = llm.call("What is the weather in Tokyo?")
 
         assert result is not None
@@ -677,14 +677,14 @@ def test_anthropic_thinking_blocks_preserved_across_turns():
     assert isinstance(llm, AnthropicCompletion)
 
     # Capture all messages.create calls to verify thinking blocks are included
-    original_create = llm.client.messages.create
+    original_create = llm._client.messages.create
     captured_calls = []
 
     def capture_and_call(**kwargs):
         captured_calls.append(kwargs)
         return original_create(**kwargs)
 
-    with patch.object(llm.client.messages, 'create', side_effect=capture_and_call):
+    with patch.object(llm._client.messages, 'create', side_effect=capture_and_call):
         # First call - establishes context and generates thinking blocks
         messages = [{"role": "user", "content": "What is 2+2?"}]
         first_result = llm.call(messages)
@@ -695,8 +695,8 @@ def test_anthropic_thinking_blocks_preserved_across_turns():
         assert len(first_result) > 0
 
         # Verify thinking blocks were stored after first response
-        assert len(llm.previous_thinking_blocks) > 0, "No thinking blocks stored after first call"
-        first_thinking = llm.previous_thinking_blocks[0]
+        assert len(llm._previous_thinking_blocks) > 0, "No thinking blocks stored after first call"
+        first_thinking = llm._previous_thinking_blocks[0]
         assert first_thinking["type"] == "thinking"
         assert "thinking" in first_thinking
         assert "signature" in first_thinking

lib/crewai/tests/llms/azure/test_azure.py

@@ -66,7 +66,7 @@ def test_azure_tool_use_conversation_flow():
     available_functions = {"get_weather": mock_weather_tool}
 
     # Mock the Azure client responses
-    with patch.object(completion.client, 'complete') as mock_complete:
+    with patch.object(completion._client, 'complete') as mock_complete:
         # Mock tool call in response with proper type
         mock_tool_call = MagicMock(spec=ChatCompletionsToolCall)
         mock_tool_call.function.name = "get_weather"
@@ -698,7 +698,7 @@ def test_azure_environment_variable_endpoint():
     }):
         llm = LLM(model="azure/gpt-4")
 
-        assert llm.client is not None
+        assert llm._client is not None
         assert llm.endpoint == "https://test.openai.azure.com/openai/deployments/gpt-4"
 
 
@@ -709,7 +709,7 @@ def test_azure_token_usage_tracking():
     llm = LLM(model="azure/gpt-4")
 
     # Mock the Azure response with usage information
-    with patch.object(llm.client, 'complete') as mock_complete:
+    with patch.object(llm._client, 'complete') as mock_complete:
         mock_message = MagicMock()
         mock_message.content = "test response"
         mock_message.tool_calls = None
@@ -747,7 +747,7 @@ def test_azure_http_error_handling():
     llm = LLM(model="azure/gpt-4")
 
     # Mock an HTTP error
-    with patch.object(llm.client, 'complete') as mock_complete:
+    with patch.object(llm._client, 'complete') as mock_complete:
         mock_complete.side_effect = HttpResponseError(message="Rate limit exceeded", response=MagicMock(status_code=429))
 
         with pytest.raises(HttpResponseError):
@@ -966,7 +966,7 @@ def test_azure_improved_error_messages():
 
     llm = LLM(model="azure/gpt-4")
 
-    with patch.object(llm.client, 'complete') as mock_complete:
+    with patch.object(llm._client, 'complete') as mock_complete:
         error_401 = HttpResponseError(message="Unauthorized")
         error_401.status_code = 401
         mock_complete.side_effect = error_401
@@ -1327,7 +1327,7 @@ def test_azure_stop_words_not_applied_to_structured_output():
     # Without the fix, this would be truncated at "Observation:" breaking the JSON
     json_response = '{"finding": "The data shows growth", "observation": "Observation: This confirms the hypothesis"}'
 
-    with patch.object(llm.client, 'complete') as mock_complete:
+    with patch.object(llm._client, 'complete') as mock_complete:
         mock_message = MagicMock()
         mock_message.content = json_response
         mock_message.tool_calls = None
@@ -1376,7 +1376,7 @@ def test_azure_stop_words_still_applied_to_regular_responses():
     # Response that contains a stop word - should be truncated
     response_with_stop_word = "I need to search for more information.\n\nAction: search\nObservation: Found results"
 
-    with patch.object(llm.client, 'complete') as mock_complete:
+    with patch.object(llm._client, 'complete') as mock_complete:
         mock_message = MagicMock()
         mock_message.content = response_with_stop_word
         mock_message.tool_calls = None

lib/crewai/tests/llms/bedrock/test_bedrock.py

@@ -674,7 +674,7 @@ def test_bedrock_token_usage_tracking():
     llm = LLM(model="bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0")
 
     # Mock the Bedrock response with usage information
-    with patch.object(llm.client, 'converse') as mock_converse:
+    with patch.object(llm._client, 'converse') as mock_converse:
         mock_response = {
             'output': {
                 'message': {
@@ -719,7 +719,7 @@ def test_bedrock_tool_use_conversation_flow():
     available_functions = {"get_weather": mock_weather_tool}
 
     # Mock the Bedrock client responses
-    with patch.object(llm.client, 'converse') as mock_converse:
+    with patch.object(llm._client, 'converse') as mock_converse:
         # First response: tool use request
         tool_use_response = {
             'output': {
@@ -805,7 +805,7 @@ def test_bedrock_client_error_handling():
     llm = LLM(model="bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0")
 
     # Test ValidationException
-    with patch.object(llm.client, 'converse') as mock_converse:
+    with patch.object(llm._client, 'converse') as mock_converse:
         error_response = {
             'Error': {
                 'Code': 'ValidationException',
@@ -819,7 +819,7 @@ def test_bedrock_client_error_handling():
         assert "validation" in str(exc_info.value).lower()
 
     # Test ThrottlingException
-    with patch.object(llm.client, 'converse') as mock_converse:
+    with patch.object(llm._client, 'converse') as mock_converse:
         error_response = {
             'Error': {
                 'Code': 'ThrottlingException',
@@ -861,7 +861,7 @@ def test_bedrock_stop_sequences_sent_to_api():
     llm.stop = ["\nObservation:", "\nThought:"]
 
     # Patch the API call to capture parameters without making real call
-    with patch.object(llm.client, 'converse') as mock_converse:
+    with patch.object(llm._client, 'converse') as mock_converse:
         mock_response = {
             'output': {
                 'message': {

lib/crewai/tests/llms/google/test_google.py

@@ -556,8 +556,8 @@ def test_gemini_environment_variable_api_key():
     with patch.dict(os.environ, {"GOOGLE_API_KEY": "test-google-key"}):
         llm = LLM(model="google/gemini-2.0-flash-001")
 
-        assert llm.client is not None
-        assert hasattr(llm.client, 'models')
+        assert llm._client is not None
+        assert hasattr(llm._client, 'models')
         assert llm.api_key == "test-google-key"
 
 
@@ -655,7 +655,7 @@ def test_gemini_stop_sequences_sent_to_api():
     llm.stop = ["\nObservation:", "\nThought:"]
 
     # Patch the API call to capture parameters without making real call
-    with patch.object(llm.client.models, 'generate_content') as mock_generate:
+    with patch.object(llm._client.models, 'generate_content') as mock_generate:
         mock_response = MagicMock()
         mock_response.text = "Hello"
         mock_response.candidates = []

lib/crewai/tests/llms/openai/test_openai.py

@@ -371,11 +371,11 @@ def test_openai_client_setup_with_extra_arguments():
     assert llm.top_p == 0.5
 
     # Check that client parameters are properly configured
-    assert llm.client.max_retries == 3
-    assert llm.client.timeout == 30
+    assert llm._client.max_retries == 3
+    assert llm._client.timeout == 30
 
     # Test that parameters are properly used in API calls
-    with patch.object(llm.client.chat.completions, 'create') as mock_create:
+    with patch.object(llm._client.chat.completions, 'create') as mock_create:
         mock_create.return_value = MagicMock(
             choices=[MagicMock(message=MagicMock(content="test response", tool_calls=None))],
             usage=MagicMock(prompt_tokens=10, completion_tokens=20, total_tokens=30)
@@ -396,7 +396,7 @@ def test_extra_arguments_are_passed_to_openai_completion():
     """
     llm = LLM(model="gpt-4o", temperature=0.7, max_tokens=1000, top_p=0.5, max_retries=3)
 
-    with patch.object(llm.client.chat.completions, 'create') as mock_create:
+    with patch.object(llm._client.chat.completions, 'create') as mock_create:
         mock_create.return_value = MagicMock(
             choices=[MagicMock(message=MagicMock(content="test response", tool_calls=None))],
             usage=MagicMock(prompt_tokens=10, completion_tokens=20, total_tokens=30)
@@ -507,7 +507,7 @@ def test_openai_streaming_with_response_model():
 
     llm = LLM(model="openai/gpt-4o", stream=True)
 
-    with patch.object(llm.client.beta.chat.completions, "stream") as mock_stream:
+    with patch.object(llm._client.beta.chat.completions, "stream") as mock_stream:
         # Create mock chunks with content.delta event structure
         mock_chunk1 = MagicMock()
         mock_chunk1.type = "content.delta"
@@ -1523,6 +1523,69 @@ def test_openai_stop_words_not_applied_to_structured_output():
     assert "Observation:" in result.observation
 
 
+def test_openai_gpt5_models_do_not_support_stop_words():
+    """
+    Test that GPT-5 family models do not support stop words via the API.
+    GPT-5 models reject the 'stop' parameter, so stop words must be
+    applied client-side only.
+    """
+    gpt5_models = [
+        "gpt-5",
+        "gpt-5-mini",
+        "gpt-5-nano",
+        "gpt-5-pro",
+        "gpt-5.1",
+        "gpt-5.1-chat",
+        "gpt-5.2",
+        "gpt-5.2-chat",
+    ]
+
+    for model_name in gpt5_models:
+        llm = OpenAICompletion(model=model_name)
+        assert llm.supports_stop_words() == False, (
+            f"Expected {model_name} to NOT support stop words"
+        )
+
+
+def test_openai_non_gpt5_models_support_stop_words():
+    """
+    Test that non-GPT-5 models still support stop words normally.
+    """
+    supported_models = [
+        "gpt-4o",
+        "gpt-4o-mini",
+        "gpt-4.1",
+        "gpt-4.1-mini",
+        "gpt-4-turbo",
+    ]
+
+    for model_name in supported_models:
+        llm = OpenAICompletion(model=model_name)
+        assert llm.supports_stop_words() == True, (
+            f"Expected {model_name} to support stop words"
+        )
+
+
+def test_openai_gpt5_still_applies_stop_words_client_side():
+    """
+    Test that GPT-5 models still truncate responses at stop words client-side
+    via _apply_stop_words(), even though they don't send 'stop' to the API.
+    """
+    llm = OpenAICompletion(
+        model="gpt-5.2",
+        stop=["Observation:", "Final Answer:"],
+    )
+
+    assert llm.supports_stop_words() == False
+
+    response = "I need to search.\n\nAction: search\nObservation: Found results"
+    result = llm._apply_stop_words(response)
+
+    assert "Observation:" not in result
+    assert "Found results" not in result
+    assert "I need to search" in result
+
+
 def test_openai_stop_words_still_applied_to_regular_responses():
     """
     Test that stop words ARE still applied for regular (non-structured) responses.
@@ -1767,7 +1830,7 @@ def test_openai_responses_api_cached_prompt_tokens_with_tools():
         }
     ]
 
-    llm = OpenAICompletion(model="gpt-4.1", api='response')
+    llm = OpenAICompletion(model="gpt-4.1", api='responses')
 
     # First call with tool
     llm.call(
@@ -1843,7 +1906,7 @@ def test_openai_streaming_returns_tool_calls_without_available_functions():
     mock_chunk_3.id = "chatcmpl-1"
 
     with patch.object(
-        llm.client.chat.completions, "create", return_value=iter([mock_chunk_1, mock_chunk_2, mock_chunk_3])
+        llm._client.chat.completions, "create", return_value=iter([mock_chunk_1, mock_chunk_2, mock_chunk_3])
     ):
         result = llm.call(
             messages=[{"role": "user", "content": "Calculate 1+1"}],
@@ -1934,7 +1997,7 @@ async def test_openai_async_streaming_returns_tool_calls_without_available_funct
         return MockAsyncStream([mock_chunk_1, mock_chunk_2, mock_chunk_3])
 
     with patch.object(
-        llm.async_client.chat.completions, "create", side_effect=mock_create
+        llm._async_client.chat.completions, "create", side_effect=mock_create
     ):
         result = await llm.acall(
             messages=[{"role": "user", "content": "Calculate 1+1"}],

lib/crewai/tests/llms/openai_compatible/test_openai_compatible.py

@@ -1,7 +1,7 @@
 """Tests for OpenAI-compatible providers."""
 
 import os
-from unittest.mock import MagicMock, patch
+from unittest.mock import patch
 
 import pytest
 
@@ -133,7 +133,7 @@ class TestOpenAICompatibleCompletion:
             with pytest.raises(ValueError, match="API key required"):
                 OpenAICompatibleCompletion(model="deepseek-chat", provider="deepseek")
         finally:
-            if original:
+            if original is not None:
                 os.environ[env_key] = original
 
     def test_api_key_from_env(self):

lib/crewai/tests/rag/test_error_handling.py

@@ -3,6 +3,8 @@
 from unittest.mock import MagicMock, patch
 
 import pytest
+from pydantic import ValidationError
+
 from crewai.knowledge.storage.knowledge_storage import (  # type: ignore[import-untyped]
     KnowledgeStorage,
 )
@@ -59,7 +61,7 @@ def test_knowledge_storage_invalid_embedding_config(mock_get_client: MagicMock)
             "Unsupported provider: invalid_provider"
         )
 
-        with pytest.raises(ValueError, match="Unsupported provider: invalid_provider"):
+        with pytest.raises(ValidationError):
             KnowledgeStorage(
                 embedder={"provider": "invalid_provider"},
                 collection_name="invalid_embedding_test",

lib/crewai/tests/test_human_feedback_decorator.py

@@ -246,7 +246,7 @@ class TestHumanFeedbackExecution:
     @patch("builtins.input", return_value="")
     @patch("builtins.print")
     def test_empty_feedback_with_default_outcome(self, mock_print, mock_input):
-        """Test empty feedback uses default_outcome."""
+        """Test empty feedback uses default_outcome for routing, but flow returns method output."""
 
         class TestFlow(Flow):
             @start()
@@ -264,14 +264,16 @@ class TestHumanFeedbackExecution:
         with patch.object(flow, "_request_human_feedback", return_value=""):
             result = flow.kickoff()
 
-        assert result == "needs_work"
+        # Flow result is the method's return value, NOT the collapsed outcome
+        assert result == "Content"
         assert flow.last_human_feedback is not None
+        # But the outcome is still correctly set for routing purposes
         assert flow.last_human_feedback.outcome == "needs_work"
 
     @patch("builtins.input", return_value="Approved!")
     @patch("builtins.print")
     def test_feedback_collapsing(self, mock_print, mock_input):
-        """Test that feedback is collapsed to an outcome."""
+        """Test that feedback is collapsed to an outcome for routing, but flow returns method output."""
 
         class TestFlow(Flow):
             @start()
@@ -291,8 +293,10 @@ class TestHumanFeedbackExecution:
         ):
             result = flow.kickoff()
 
-        assert result == "approved"
+        # Flow result is the method's return value, NOT the collapsed outcome
+        assert result == "Content"
         assert flow.last_human_feedback is not None
+        # But the outcome is still correctly set for routing purposes
         assert flow.last_human_feedback.outcome == "approved"
 
 
@@ -591,3 +595,162 @@ class TestHumanFeedbackLearn:
         assert config.learn is True
         # llm defaults to "gpt-4o-mini" at the function level
         assert config.llm == "gpt-4o-mini"
+
+
+class TestHumanFeedbackFinalOutputPreservation:
+    """Tests for preserving method return value as flow's final output when @human_feedback with emit is terminal.
+
+    This addresses the bug where the flow's final output was the collapsed outcome string (e.g., 'approved')
+    instead of the method's actual return value when a @human_feedback method with emit is the final method.
+    """
+
+    @patch("builtins.input", return_value="Looks good!")
+    @patch("builtins.print")
+    def test_final_output_is_method_return_not_collapsed_outcome(
+        self, mock_print, mock_input
+    ):
+        """When @human_feedback with emit is the final method, flow output is the method's return value."""
+
+        class FinalHumanFeedbackFlow(Flow):
+            @start()
+            @human_feedback(
+                message="Review this content:",
+                emit=["approved", "rejected"],
+                llm="gpt-4o-mini",
+            )
+            def generate_and_review(self):
+                # This dict should be the final output, NOT the string 'approved'
+                return {"title": "My Article", "content": "Article content here", "status": "ready"}
+
+        flow = FinalHumanFeedbackFlow()
+
+        with (
+            patch.object(flow, "_request_human_feedback", return_value="Looks great, approved!"),
+            patch.object(flow, "_collapse_to_outcome", return_value="approved"),
+        ):
+            result = flow.kickoff()
+
+        # The final output should be the actual method return value, not the collapsed outcome
+        assert isinstance(result, dict), f"Expected dict, got {type(result).__name__}: {result}"
+        assert result == {"title": "My Article", "content": "Article content here", "status": "ready"}
+        # But the outcome should still be tracked in last_human_feedback
+        assert flow.last_human_feedback is not None
+        assert flow.last_human_feedback.outcome == "approved"
+
+    @patch("builtins.input", return_value="approved")
+    @patch("builtins.print")
+    def test_routing_still_works_with_downstream_listener(self, mock_print, mock_input):
+        """When @human_feedback has a downstream listener, routing still triggers the listener."""
+        publish_called = []
+
+        class RoutingFlow(Flow):
+            @start()
+            @human_feedback(
+                message="Review:",
+                emit=["approved", "rejected"],
+                llm="gpt-4o-mini",
+            )
+            def review(self):
+                return {"content": "original content"}
+
+            @listen("approved")
+            def publish(self):
+                publish_called.append(True)
+                return {"published": True, "timestamp": "2024-01-01"}
+
+        flow = RoutingFlow()
+
+        with (
+            patch.object(flow, "_request_human_feedback", return_value="LGTM"),
+            patch.object(flow, "_collapse_to_outcome", return_value="approved"),
+        ):
+            result = flow.kickoff()
+
+        # The downstream listener should have been triggered
+        assert len(publish_called) == 1, "publish() should have been called"
+        # The final output should be from the listener, not the human_feedback method
+        assert result == {"published": True, "timestamp": "2024-01-01"}
+
+    @patch("builtins.input", return_value="")
+    @patch("builtins.print")
+    @pytest.mark.asyncio
+    async def test_async_human_feedback_final_output_preserved(self, mock_print, mock_input):
+        """Async @human_feedback methods also preserve the real return value."""
+
+        class AsyncFinalFlow(Flow):
+            @start()
+            @human_feedback(
+                message="Review async content:",
+                emit=["approved", "rejected"],
+                llm="gpt-4o-mini",
+                default_outcome="approved",
+            )
+            async def async_generate(self):
+                return {"async_data": "value", "computed": 42}
+
+        flow = AsyncFinalFlow()
+
+        with (
+            patch.object(flow, "_request_human_feedback", return_value=""),
+        ):
+            result = await flow.kickoff_async()
+
+        # The final output should be the dict, not "approved"
+        assert isinstance(result, dict), f"Expected dict, got {type(result).__name__}: {result}"
+        assert result == {"async_data": "value", "computed": 42}
+        assert flow.last_human_feedback.outcome == "approved"
+
+    @patch("builtins.input", return_value="feedback")
+    @patch("builtins.print")
+    def test_method_outputs_contains_real_output(self, mock_print, mock_input):
+        """The _method_outputs list should contain the real method output, not the collapsed outcome."""
+
+        class OutputTrackingFlow(Flow):
+            @start()
+            @human_feedback(
+                message="Review:",
+                emit=["approved", "rejected"],
+                llm="gpt-4o-mini",
+            )
+            def generate(self):
+                return {"data": "real output"}
+
+        flow = OutputTrackingFlow()
+
+        with (
+            patch.object(flow, "_request_human_feedback", return_value="approved"),
+            patch.object(flow, "_collapse_to_outcome", return_value="approved"),
+        ):
+            flow.kickoff()
+
+        # _method_outputs should contain the real output
+        assert len(flow._method_outputs) == 1
+        assert flow._method_outputs[0] == {"data": "real output"}
+
+    @patch("builtins.input", return_value="looks good")
+    @patch("builtins.print")
+    def test_none_return_value_is_preserved(self, mock_print, mock_input):
+        """A method returning None should preserve None as flow output, not the outcome string."""
+
+        class NoneReturnFlow(Flow):
+            @start()
+            @human_feedback(
+                message="Review:",
+                emit=["approved", "rejected"],
+                llm="gpt-4o-mini",
+            )
+            def process(self):
+                # Method does work but returns None (implicit)
+                pass
+
+        flow = NoneReturnFlow()
+
+        with (
+            patch.object(flow, "_request_human_feedback", return_value=""),
+            patch.object(flow, "_collapse_to_outcome", return_value="approved"),
+        ):
+            result = flow.kickoff()
+
+        # Final output should be None (the method's real return), not "approved"
+        assert result is None, f"Expected None, got {result!r}"
+        assert flow.last_human_feedback.outcome == "approved"

lib/crewai/tests/test_human_feedback_integration.py

@@ -708,7 +708,7 @@ class TestEdgeCases:
     @patch("builtins.input", return_value="")
     @patch("builtins.print")
     def test_empty_feedback_first_outcome_fallback(self, mock_print, mock_input):
-        """Test that empty feedback without default uses first outcome."""
+        """Test that empty feedback without default uses first outcome for routing, but returns method output."""
 
         class FallbackFlow(Flow):
             @start()
@@ -726,12 +726,15 @@ class TestEdgeCases:
         with patch.object(flow, "_request_human_feedback", return_value=""):
             result = flow.kickoff()
 
-        assert result == "first"  # Falls back to first outcome
+        # Flow result is the method's return value, NOT the collapsed outcome
+        assert result == "content"
+        # But outcome is still set to first for routing purposes
+        assert flow.last_human_feedback.outcome == "first"
 
     @patch("builtins.input", return_value="whitespace only   ")
     @patch("builtins.print")
     def test_whitespace_only_feedback_treated_as_empty(self, mock_print, mock_input):
-        """Test that whitespace-only feedback is treated as empty."""
+        """Test that whitespace-only feedback is treated as empty for routing, but returns method output."""
 
         class WhitespaceFlow(Flow):
             @start()
@@ -749,7 +752,10 @@ class TestEdgeCases:
         with patch.object(flow, "_request_human_feedback", return_value="   "):
             result = flow.kickoff()
 
-        assert result == "reject"  # Uses default because feedback is empty after strip
+        # Flow result is the method's return value, NOT the collapsed outcome
+        assert result == "content"
+        # But outcome is set to default because feedback is empty after strip
+        assert flow.last_human_feedback.outcome == "reject"
 
     @patch("builtins.input", return_value="feedback")
     @patch("builtins.print")

lib/crewai/tests/test_llm.py

@@ -682,6 +682,126 @@ def test_llm_call_when_stop_is_unsupported_when_additional_drop_params_is_provid
     assert "Paris" in result
 
 
+@pytest.mark.vcr()
+def test_litellm_gpt5_call_succeeds_without_stop_error():
+    """
+    Integration test: GPT-5 call succeeds when stop words are configured,
+    because stop is omitted from API params and applied client-side.
+    """
+    llm = LLM(model="gpt-5", stop=["Observation:"], is_litellm=True)
+    result = llm.call("What is the capital of France?")
+    assert isinstance(result, str)
+    assert len(result) > 0
+
+
+def test_litellm_gpt5_does_not_send_stop_in_params():
+    """
+    Test that the LiteLLM fallback path does not include 'stop' in API params
+    for GPT-5.x models, since they reject it at the API level.
+    """
+    llm = LLM(model="openai/gpt-5.2", stop=["Observation:"], is_litellm=True)
+
+    params = llm._prepare_completion_params(
+        messages=[{"role": "user", "content": "Hello"}]
+    )
+
+    assert params.get("stop") is None, (
+        "GPT-5.x models should not have 'stop' in API params"
+    )
+
+
+def test_litellm_non_gpt5_sends_stop_in_params():
+    """
+    Test that the LiteLLM fallback path still includes 'stop' in API params
+    for models that support it.
+    """
+    llm = LLM(model="gpt-4o", stop=["Observation:"], is_litellm=True)
+
+    params = llm._prepare_completion_params(
+        messages=[{"role": "user", "content": "Hello"}]
+    )
+
+    assert params.get("stop") == ["Observation:"], (
+        "Non-GPT-5 models should have 'stop' in API params"
+    )
+
+
+def test_litellm_retry_catches_litellm_unsupported_params_error(caplog):
+    """
+    Test that the retry logic catches LiteLLM's UnsupportedParamsError format
+    ("does not support parameters") in addition to the OpenAI API format.
+    """
+    llm = LLM(model="openai/gpt-5.2", stop=["Observation:"], is_litellm=True)
+
+    litellm_error = Exception(
+        "litellm.UnsupportedParamsError: openai does not support parameters: "
+        "['stop'], for model=openai/gpt-5.2."
+    )
+
+    call_count = 0
+
+    try:
+        import litellm
+    except ImportError:
+        pytest.skip("litellm is not installed; skipping LiteLLM retry test")
+
+    def mock_completion(*args, **kwargs):
+        nonlocal call_count
+        call_count += 1
+        if call_count == 1:
+            raise litellm_error
+        return MagicMock(
+            choices=[MagicMock(message=MagicMock(content="Paris", tool_calls=None))],
+            usage=MagicMock(
+                prompt_tokens=10,
+                completion_tokens=5,
+                total_tokens=15,
+            ),
+        )
+
+    with patch("litellm.completion", side_effect=mock_completion):
+        with caplog.at_level(logging.INFO):
+            result = llm.call("What is the capital of France?")
+
+    assert "Retrying LLM call without the unsupported 'stop'" in caplog.text
+    assert "stop" in llm.additional_params.get("additional_drop_params", [])
+
+
+def test_litellm_retry_catches_openai_api_stop_error(caplog):
+    """
+    Test that the retry logic still catches the OpenAI API error format
+    ("Unsupported parameter: 'stop'").
+    """
+    llm = LLM(model="openai/gpt-5.2", stop=["Observation:"], is_litellm=True)
+
+    api_error = Exception(
+        "Unsupported parameter: 'stop' is not supported with this model."
+    )
+
+    call_count = 0
+
+    def mock_completion(*args, **kwargs):
+        nonlocal call_count
+        call_count += 1
+        if call_count == 1:
+            raise api_error
+        return MagicMock(
+            choices=[MagicMock(message=MagicMock(content="Paris", tool_calls=None))],
+            usage=MagicMock(
+                prompt_tokens=10,
+                completion_tokens=5,
+                total_tokens=15,
+            ),
+        )
+
+    with patch("litellm.completion", side_effect=mock_completion):
+        with caplog.at_level(logging.INFO):
+            llm.call("What is the capital of France?")
+
+    assert "Retrying LLM call without the unsupported 'stop'" in caplog.text
+    assert "stop" in llm.additional_params.get("additional_drop_params", [])
+
+
 @pytest.fixture
 def ollama_llm():
     return LLM(model="ollama/llama3.2:3b", is_litellm=True)

lib/crewai/tests/test_project.py

@@ -1,5 +1,5 @@
 from typing import Any, ClassVar
-from unittest.mock import Mock, patch
+from unittest.mock import Mock, create_autospec, patch
 
 import pytest
 from crewai.agent import Agent
@@ -372,8 +372,11 @@ def test_internal_crew_with_mcp():
     mock_adapter = Mock()
     mock_adapter.tools = ToolCollection([simple_tool, another_simple_tool])
 
-    mock_llm = Mock()
-    mock_llm.__class__ = BaseLLM
+    class _StubLLM(BaseLLM):
+        def call(self, *a: Any, **kw: Any) -> str:
+            return ""
+
+    mock_llm = create_autospec(_StubLLM(model="stub"), instance=True)
 
     with (
         patch("crewai_tools.MCPServerAdapter", return_value=mock_adapter) as adapter_mock,

lib/devtools/README.md

@@ -8,18 +8,22 @@ Installed automatically via the workspace (`uv sync`). Requires:
 
 - [GitHub CLI](https://cli.github.com/) (`gh`) — authenticated
 - `OPENAI_API_KEY` env var — for release note generation and translation
+- `ENTERPRISE_REPO` env var — GitHub repo for enterprise releases
+- `ENTERPRISE_VERSION_DIRS` env var — comma-separated directories to bump in the enterprise repo
+- `ENTERPRISE_CREWAI_DEP_PATH` env var — path to the pyproject.toml with the `crewai[tools]` pin in the enterprise repo
 
 ## Commands
 
 ### `devtools release <version>`
 
-Full end-to-end release. Bumps versions, creates PRs, tags, and publishes a GitHub release.
+Full end-to-end release. Bumps versions, creates PRs, tags, publishes a GitHub release, and releases the enterprise repo.
 
 ```
 devtools release 1.10.3
-devtools release 1.10.3a1      # pre-release
-devtools release 1.10.3 --no-edit   # skip editing release notes
-devtools release 1.10.3 --dry-run   # preview without changes
+devtools release 1.10.3a1                # pre-release
+devtools release 1.10.3 --no-edit        # skip editing release notes
+devtools release 1.10.3 --dry-run        # preview without changes
+devtools release 1.10.3 --skip-enterprise  # skip enterprise release phase
 ```
 
 **Flow:**
@@ -31,6 +35,10 @@ devtools release 1.10.3 --dry-run   # preview without changes
 5. Updates changelogs (en, pt-BR, ko) and docs version switcher
 6. Creates docs PR against main, polls until merged
 7. Tags main and creates GitHub release
+8. Triggers PyPI publish workflow
+9. Clones enterprise repo, bumps versions and `crewai[tools]` dep, runs `uv sync`
+10. Creates enterprise bump PR, polls until merged
+11. Tags and creates GitHub release on enterprise repo
 
 ### `devtools bump <version>`
 

lib/devtools/src/crewai_devtools/__init__.py

@@ -1,3 +1,3 @@
 """CrewAI development tools."""
 
-__version__ = "1.12.0a3"
+__version__ = "1.13.0rc1"

lib/devtools/src/crewai_devtools/cli.py

@@ -2,10 +2,13 @@
 
 import os
 from pathlib import Path
+import re
 import subprocess
 import sys
+import tempfile
 import time
 from typing import Final, Literal
+from urllib.request import urlopen
 
 import click
 from dotenv import load_dotenv
@@ -153,12 +156,51 @@ def update_version_in_file(file_path: Path, new_version: str) -> bool:
     return False
 
 
-def update_pyproject_dependencies(file_path: Path, new_version: str) -> bool:
+def update_pyproject_version(file_path: Path, new_version: str) -> bool:
+    """Update the [project] version field in a pyproject.toml file.
+
+    Args:
+        file_path: Path to pyproject.toml file.
+        new_version: New version string.
+
+    Returns:
+        True if version was updated, False otherwise.
+    """
+    if not file_path.exists():
+        return False
+
+    content = file_path.read_text()
+    new_content = re.sub(
+        r'^(version\s*=\s*")[^"]+(")',
+        rf"\g<1>{new_version}\2",
+        content,
+        count=1,
+        flags=re.MULTILINE,
+    )
+    if new_content != content:
+        file_path.write_text(new_content)
+        return True
+    return False
+
+
+_DEFAULT_WORKSPACE_PACKAGES: Final[list[str]] = [
+    "crewai",
+    "crewai-tools",
+    "crewai-devtools",
+]
+
+
+def update_pyproject_dependencies(
+    file_path: Path,
+    new_version: str,
+    extra_packages: list[str] | None = None,
+) -> bool:
     """Update workspace dependency versions in pyproject.toml.
 
     Args:
         file_path: Path to pyproject.toml file.
         new_version: New version string.
+        extra_packages: Additional package names to update beyond the defaults.
 
     Returns:
         True if any dependencies were updated, False otherwise.
@@ -170,7 +212,7 @@ def update_pyproject_dependencies(file_path: Path, new_version: str) -> bool:
     lines = content.splitlines()
     updated = False
 
-    workspace_packages = ["crewai", "crewai-tools", "crewai-devtools"]
+    workspace_packages = _DEFAULT_WORKSPACE_PACKAGES + (extra_packages or [])
 
     for i, line in enumerate(lines):
         for pkg in workspace_packages:
@@ -431,12 +473,29 @@ def update_changelog(
     return True
 
 
-def update_template_dependencies(templates_dir: Path, new_version: str) -> list[Path]:
-    """Update crewai dependency versions in CLI template pyproject.toml files.
+def _pin_crewai_deps(content: str, version: str) -> str:
+    """Replace crewai dependency version pins in a pyproject.toml string.
 
     Handles both pinned (==) and minimum (>=) version specifiers,
     as well as extras like [tools].
 
+    Args:
+        content: File content to transform.
+        version: New version string.
+
+    Returns:
+        Transformed content.
+    """
+    return re.sub(
+        r'"crewai(\[tools\])?(==|>=)[^"]*"',
+        lambda m: f'"crewai{(m.group(1) or "")!s}=={version}"',
+        content,
+    )
+
+
+def update_template_dependencies(templates_dir: Path, new_version: str) -> list[Path]:
+    """Update crewai dependency versions in CLI template pyproject.toml files.
+
     Args:
         templates_dir: Path to the CLI templates directory.
         new_version: New version string.
@@ -444,16 +503,10 @@ def update_template_dependencies(templates_dir: Path, new_version: str) -> list[
     Returns:
         List of paths that were updated.
     """
-    import re
-
     updated = []
     for pyproject in templates_dir.rglob("pyproject.toml"):
         content = pyproject.read_text()
-        new_content = re.sub(
-            r'"crewai(\[tools\])?(==|>=)[^"]*"',
-            lambda m: f'"crewai{(m.group(1) or "")!s}=={new_version}"',
-            content,
-        )
+        new_content = _pin_crewai_deps(content, new_version)
         if new_content != content:
             pyproject.write_text(new_content)
             updated.append(pyproject)
@@ -607,24 +660,26 @@ def get_github_contributors(commit_range: str) -> list[str]:
 # ---------------------------------------------------------------------------
 
 
-def _poll_pr_until_merged(branch_name: str, label: str) -> None:
-    """Poll a GitHub PR until it is merged. Exit if closed without merging."""
+def _poll_pr_until_merged(
+    branch_name: str, label: str, repo: str | None = None
+) -> None:
+    """Poll a GitHub PR until it is merged. Exit if closed without merging.
+
+    Args:
+        branch_name: Branch name to look up the PR.
+        label: Human-readable label for status messages.
+        repo: Optional GitHub repo (owner/name) for cross-repo PRs.
+    """
     console.print(f"[cyan]Waiting for {label} to be merged...[/cyan]")
+    cmd = ["gh", "pr", "view", branch_name]
+    if repo:
+        cmd.extend(["--repo", repo])
+    cmd.extend(["--json", "state", "--jq", ".state"])
+
     while True:
         time.sleep(10)
         try:
-            state = run_command(
-                [
-                    "gh",
-                    "pr",
-                    "view",
-                    branch_name,
-                    "--json",
-                    "state",
-                    "--jq",
-                    ".state",
-                ]
-            )
+            state = run_command(cmd)
         except subprocess.CalledProcessError:
             state = ""
 
@@ -984,8 +1039,360 @@ def _create_tag_and_release(
     console.print(f"[green]✓[/green] Created GitHub {release_type} for {tag_name}")
 
 
-def _trigger_pypi_publish(tag_name: str) -> None:
-    """Trigger the PyPI publish GitHub Actions workflow."""
+_ENTERPRISE_REPO: Final[str | None] = os.getenv("ENTERPRISE_REPO")
+_ENTERPRISE_VERSION_DIRS: Final[tuple[str, ...]] = tuple(
+    d.strip() for d in os.getenv("ENTERPRISE_VERSION_DIRS", "").split(",") if d.strip()
+)
+_ENTERPRISE_CREWAI_DEP_PATH: Final[str | None] = os.getenv("ENTERPRISE_CREWAI_DEP_PATH")
+_ENTERPRISE_EXTRA_PACKAGES: Final[tuple[str, ...]] = tuple(
+    p.strip()
+    for p in os.getenv("ENTERPRISE_EXTRA_PACKAGES", "").split(",")
+    if p.strip()
+)
+
+
+def _update_enterprise_crewai_dep(pyproject_path: Path, version: str) -> bool:
+    """Update the crewai[tools] pin in an enterprise pyproject.toml.
+
+    Args:
+        pyproject_path: Path to the pyproject.toml file.
+        version: New crewai version string.
+
+    Returns:
+        True if the file was modified.
+    """
+    if not pyproject_path.exists():
+        return False
+
+    content = pyproject_path.read_text()
+    new_content = _pin_crewai_deps(content, version)
+    if new_content != content:
+        pyproject_path.write_text(new_content)
+        return True
+    return False
+
+
+_DEPLOYMENT_TEST_REPO: Final[str] = "crewAIInc/crew_deployment_test"
+
+_PYPI_POLL_INTERVAL: Final[int] = 15
+_PYPI_POLL_TIMEOUT: Final[int] = 600
+
+
+def _update_deployment_test_repo(version: str, is_prerelease: bool) -> None:
+    """Update the deployment test repo to pin the new crewai version.
+
+    Clones the repo, updates the crewai[tools] pin in pyproject.toml,
+    regenerates the lockfile, commits, and pushes directly to main.
+
+    Args:
+        version: New crewai version string.
+        is_prerelease: Whether this is a pre-release version.
+    """
+    console.print(
+        f"\n[bold cyan]Updating {_DEPLOYMENT_TEST_REPO} to {version}[/bold cyan]"
+    )
+
+    with tempfile.TemporaryDirectory() as tmp:
+        repo_dir = Path(tmp) / "crew_deployment_test"
+        run_command(["gh", "repo", "clone", _DEPLOYMENT_TEST_REPO, str(repo_dir)])
+        console.print(f"[green]✓[/green] Cloned {_DEPLOYMENT_TEST_REPO}")
+
+        pyproject = repo_dir / "pyproject.toml"
+        content = pyproject.read_text()
+        new_content = re.sub(
+            r'"crewai\[tools\]==[^"]+"',
+            f'"crewai[tools]=={version}"',
+            content,
+        )
+        if new_content == content:
+            console.print(
+                "[yellow]Warning:[/yellow] No crewai[tools] pin found to update"
+            )
+            return
+        pyproject.write_text(new_content)
+        console.print(f"[green]✓[/green] Updated crewai[tools] pin to {version}")
+
+        lock_cmd = [
+            "uv",
+            "lock",
+            "--refresh-package",
+            "crewai",
+            "--refresh-package",
+            "crewai-tools",
+        ]
+        if is_prerelease:
+            lock_cmd.append("--prerelease=allow")
+
+        max_retries = 10
+        for attempt in range(1, max_retries + 1):
+            try:
+                run_command(lock_cmd, cwd=repo_dir)
+                break
+            except subprocess.CalledProcessError:
+                if attempt == max_retries:
+                    console.print(
+                        f"[red]Error:[/red] uv lock failed after {max_retries} attempts"
+                    )
+                    raise
+                console.print(
+                    f"[yellow]uv lock failed (attempt {attempt}/{max_retries}),"
+                    f" retrying in {_PYPI_POLL_INTERVAL}s...[/yellow]"
+                )
+                time.sleep(_PYPI_POLL_INTERVAL)
+        console.print("[green]✓[/green] Lockfile updated")
+
+        run_command(["git", "add", "pyproject.toml", "uv.lock"], cwd=repo_dir)
+        run_command(
+            ["git", "commit", "-m", f"chore: bump crewai to {version}"],
+            cwd=repo_dir,
+        )
+        run_command(["git", "push"], cwd=repo_dir)
+        console.print(f"[green]✓[/green] Pushed to {_DEPLOYMENT_TEST_REPO}")
+
+
+def _wait_for_pypi(package: str, version: str) -> None:
+    """Poll PyPI until a specific package version is available.
+
+    Args:
+        package: PyPI package name.
+        version: Version string to wait for.
+    """
+    url = f"https://pypi.org/pypi/{package}/{version}/json"
+    deadline = time.monotonic() + _PYPI_POLL_TIMEOUT
+
+    console.print(f"[cyan]Waiting for {package}=={version} to appear on PyPI...[/cyan]")
+    while time.monotonic() < deadline:
+        try:
+            with urlopen(url) as resp:  # noqa: S310
+                if resp.status == 200:
+                    console.print(
+                        f"[green]✓[/green] {package}=={version} is available on PyPI"
+                    )
+                    return
+        except Exception:  # noqa: S110
+            pass
+        time.sleep(_PYPI_POLL_INTERVAL)
+
+    console.print(
+        f"[red]Error:[/red] Timed out waiting for {package}=={version} on PyPI"
+    )
+    sys.exit(1)
+
+
+def _release_enterprise(version: str, is_prerelease: bool, dry_run: bool) -> None:
+    """Clone the enterprise repo, bump versions, and create a release PR.
+
+    Expects ENTERPRISE_REPO, ENTERPRISE_VERSION_DIRS, and
+    ENTERPRISE_CREWAI_DEP_PATH to be validated before calling.
+
+    Args:
+        version: New version string.
+        is_prerelease: Whether this is a pre-release version.
+        dry_run: Show what would be done without making changes.
+    """
+    if (
+        not _ENTERPRISE_REPO
+        or not _ENTERPRISE_VERSION_DIRS
+        or not _ENTERPRISE_CREWAI_DEP_PATH
+    ):
+        console.print("[red]Error:[/red] Enterprise env vars not configured")
+        sys.exit(1)
+
+    enterprise_repo: str = _ENTERPRISE_REPO
+    enterprise_dep_path: str = _ENTERPRISE_CREWAI_DEP_PATH
+
+    console.print(
+        f"\n[bold cyan]Phase 3: Releasing {enterprise_repo} {version}[/bold cyan]"
+    )
+
+    if dry_run:
+        console.print(f"[dim][DRY RUN][/dim] Would clone {enterprise_repo}")
+        for d in _ENTERPRISE_VERSION_DIRS:
+            console.print(f"[dim][DRY RUN][/dim] Would update versions in {d}")
+        console.print(
+            f"[dim][DRY RUN][/dim] Would update crewai[tools] dep in "
+            f"{enterprise_dep_path}"
+        )
+        console.print(
+            "[dim][DRY RUN][/dim] Would create bump PR, wait for merge, "
+            "then tag and release"
+        )
+        return
+
+    with tempfile.TemporaryDirectory() as tmp:
+        repo_dir = Path(tmp) / enterprise_repo.split("/")[-1]
+        console.print(f"Cloning {enterprise_repo}...")
+        run_command(["gh", "repo", "clone", enterprise_repo, str(repo_dir)])
+        console.print(f"[green]✓[/green] Cloned {enterprise_repo}")
+
+        # --- bump versions ---
+        for rel_dir in _ENTERPRISE_VERSION_DIRS:
+            pkg_dir = repo_dir / rel_dir
+            if not pkg_dir.exists():
+                console.print(
+                    f"[yellow]Warning:[/yellow] {rel_dir} not found, skipping"
+                )
+                continue
+
+            for vfile in find_version_files(pkg_dir):
+                if update_version_in_file(vfile, version):
+                    console.print(
+                        f"[green]✓[/green] Updated: {vfile.relative_to(repo_dir)}"
+                    )
+
+            pyproject = pkg_dir / "pyproject.toml"
+            if pyproject.exists():
+                if update_pyproject_version(pyproject, version):
+                    console.print(
+                        f"[green]✓[/green] Updated version in: "
+                        f"{pyproject.relative_to(repo_dir)}"
+                    )
+                if update_pyproject_dependencies(
+                    pyproject, version, extra_packages=list(_ENTERPRISE_EXTRA_PACKAGES)
+                ):
+                    console.print(
+                        f"[green]✓[/green] Updated deps in: "
+                        f"{pyproject.relative_to(repo_dir)}"
+                    )
+
+        # --- update crewai[tools] pin ---
+        enterprise_pyproject = repo_dir / enterprise_dep_path
+        if _update_enterprise_crewai_dep(enterprise_pyproject, version):
+            console.print(
+                f"[green]✓[/green] Updated crewai[tools] dep in {enterprise_dep_path}"
+            )
+
+        _wait_for_pypi("crewai", version)
+
+        console.print("\nSyncing workspace...")
+        sync_cmd = [
+            "uv",
+            "sync",
+            "--refresh-package",
+            "crewai",
+            "--refresh-package",
+            "crewai-tools",
+            "--refresh-package",
+            "crewai-files",
+        ]
+        if is_prerelease:
+            sync_cmd.append("--prerelease=allow")
+
+        max_retries = 10
+        for attempt in range(1, max_retries + 1):
+            try:
+                run_command(sync_cmd, cwd=repo_dir)
+                break
+            except subprocess.CalledProcessError:
+                if attempt == max_retries:
+                    console.print(
+                        f"[red]Error:[/red] uv sync failed after {max_retries} attempts"
+                    )
+                    raise
+                console.print(
+                    f"[yellow]uv sync failed (attempt {attempt}/{max_retries}),"
+                    f" retrying in {_PYPI_POLL_INTERVAL}s...[/yellow]"
+                )
+                time.sleep(_PYPI_POLL_INTERVAL)
+        console.print("[green]✓[/green] Workspace synced")
+
+        # --- branch, commit, push, PR ---
+        branch_name = f"feat/bump-version-{version}"
+        run_command(["git", "checkout", "-b", branch_name], cwd=repo_dir)
+        run_command(["git", "add", "."], cwd=repo_dir)
+        run_command(
+            ["git", "commit", "-m", f"feat: bump versions to {version}"],
+            cwd=repo_dir,
+        )
+        console.print("[green]✓[/green] Changes committed")
+
+        run_command(["git", "push", "-u", "origin", branch_name], cwd=repo_dir)
+        console.print("[green]✓[/green] Branch pushed")
+
+        pr_url = run_command(
+            [
+                "gh",
+                "pr",
+                "create",
+                "--repo",
+                enterprise_repo,
+                "--base",
+                "main",
+                "--title",
+                f"feat: bump versions to {version}",
+                "--body",
+                "",
+            ],
+            cwd=repo_dir,
+        )
+        console.print("[green]✓[/green] Enterprise bump PR created")
+        console.print(f"[cyan]PR URL:[/cyan] {pr_url}")
+
+        _poll_pr_until_merged(branch_name, "enterprise bump PR", repo=enterprise_repo)
+
+        # --- tag and release ---
+        run_command(["git", "checkout", "main"], cwd=repo_dir)
+        run_command(["git", "pull"], cwd=repo_dir)
+
+        tag_name = version
+        run_command(
+            ["git", "tag", "-a", tag_name, "-m", f"Release {version}"],
+            cwd=repo_dir,
+        )
+        run_command(["git", "push", "origin", tag_name], cwd=repo_dir)
+        console.print(f"[green]✓[/green] Pushed tag {tag_name}")
+
+        gh_cmd = [
+            "gh",
+            "release",
+            "create",
+            tag_name,
+            "--repo",
+            enterprise_repo,
+            "--title",
+            tag_name,
+            "--notes",
+            f"Release {version}",
+        ]
+        if is_prerelease:
+            gh_cmd.append("--prerelease")
+
+        run_command(gh_cmd)
+        release_type = "prerelease" if is_prerelease else "release"
+        console.print(
+            f"[green]✓[/green] Created GitHub {release_type} for "
+            f"{enterprise_repo} {tag_name}"
+        )
+
+
+def _trigger_pypi_publish(tag_name: str, wait: bool = False) -> None:
+    """Trigger the PyPI publish GitHub Actions workflow.
+
+    Args:
+        tag_name: The release tag to publish.
+        wait: Block until the workflow run completes.
+    """
+    # Capture the latest run ID before triggering so we can detect the new one
+    prev_run_id = ""
+    if wait:
+        try:
+            prev_run_id = run_command(
+                [
+                    "gh",
+                    "run",
+                    "list",
+                    "--workflow=publish.yml",
+                    "--limit=1",
+                    "--json=databaseId",
+                    "--jq=.[0].databaseId",
+                ]
+            )
+        except subprocess.CalledProcessError:
+            console.print(
+                "[yellow]Note:[/yellow] Could not determine previous workflow run; "
+                "continuing without previous run ID"
+            )
+
     with console.status("[cyan]Triggering PyPI publish workflow..."):
         try:
             run_command(
@@ -1003,6 +1410,42 @@ def _trigger_pypi_publish(tag_name: str) -> None:
             sys.exit(1)
     console.print("[green]✓[/green] Triggered PyPI publish workflow")
 
+    if wait:
+        console.print("[cyan]Waiting for PyPI publish workflow to complete...[/cyan]")
+        run_id = ""
+        deadline = time.monotonic() + 120
+        while time.monotonic() < deadline:
+            time.sleep(5)
+            try:
+                run_id = run_command(
+                    [
+                        "gh",
+                        "run",
+                        "list",
+                        "--workflow=publish.yml",
+                        "--limit=1",
+                        "--json=databaseId",
+                        "--jq=.[0].databaseId",
+                    ]
+                )
+            except subprocess.CalledProcessError:
+                continue
+            if run_id and run_id != prev_run_id:
+                break
+
+        if not run_id or run_id == prev_run_id:
+            console.print(
+                "[red]Error:[/red] Could not find the PyPI publish workflow run"
+            )
+            sys.exit(1)
+
+        try:
+            run_command(["gh", "run", "watch", run_id, "--exit-status"])
+        except subprocess.CalledProcessError as e:
+            console.print(f"[red]✗[/red] PyPI publish workflow failed: {e}")
+            sys.exit(1)
+        console.print("[green]✓[/green] PyPI publish workflow completed")
+
 
 # ---------------------------------------------------------------------------
 # CLI commands
@@ -1032,6 +1475,15 @@ def bump(version: str, dry_run: bool, no_push: bool, no_commit: bool) -> None:
         no_push: Don't push changes to remote.
         no_commit: Don't commit changes (just update files).
     """
+    console.print(
+        f"\n[yellow]Note:[/yellow] [bold]devtools bump[/bold] only bumps versions "
+        f"in this repo. It will not tag, publish to PyPI, or release enterprise.\n"
+        f"If you want a full end-to-end release, run "
+        f"[bold]devtools release {version}[/bold] instead."
+    )
+    if not Confirm.ask("Continue with bump only?", default=True):
+        sys.exit(0)
+
     try:
         check_gh_installed()
 
@@ -1136,6 +1588,16 @@ def tag(dry_run: bool, no_edit: bool) -> None:
         dry_run: Show what would be done without making changes.
         no_edit: Skip editing release notes.
     """
+    console.print(
+        "\n[yellow]Note:[/yellow] [bold]devtools tag[/bold] only tags and creates "
+        "a GitHub release for this repo. It will not bump versions, publish to "
+        "PyPI, or release enterprise.\n"
+        "If you want a full end-to-end release, run "
+        "[bold]devtools release <version>[/bold] instead."
+    )
+    if not Confirm.ask("Continue with tag only?", default=True):
+        sys.exit(0)
+
     try:
         cwd = Path.cwd()
         lib_dir = cwd / "lib"
@@ -1226,24 +1688,75 @@ def tag(dry_run: bool, no_edit: bool) -> None:
     "--dry-run", is_flag=True, help="Show what would be done without making changes"
 )
 @click.option("--no-edit", is_flag=True, help="Skip editing release notes")
-def release(version: str, dry_run: bool, no_edit: bool) -> None:
+@click.option(
+    "--skip-enterprise",
+    is_flag=True,
+    help="Skip the enterprise release phase",
+)
+@click.option(
+    "--skip-to-enterprise",
+    is_flag=True,
+    help="Skip phases 1 & 2, run only the enterprise release phase",
+)
+def release(
+    version: str,
+    dry_run: bool,
+    no_edit: bool,
+    skip_enterprise: bool,
+    skip_to_enterprise: bool,
+) -> None:
     """Full release: bump versions, tag, and publish a GitHub release.
 
     Combines bump and tag into a single workflow. Creates a version bump PR,
     waits for it to be merged, then generates release notes, updates docs,
-    creates the tag, and publishes a GitHub release.
+    creates the tag, and publishes a GitHub release. Then bumps versions and
+    releases the enterprise repo.
 
     Args:
         version: New version to set (e.g., 1.0.0, 1.0.0a1).
         dry_run: Show what would be done without making changes.
         no_edit: Skip editing release notes.
+        skip_enterprise: Skip the enterprise release phase.
+        skip_to_enterprise: Skip phases 1 & 2, run only the enterprise release phase.
     """
     try:
         check_gh_installed()
 
+        if skip_enterprise and skip_to_enterprise:
+            console.print(
+                "[red]Error:[/red] Cannot use both --skip-enterprise "
+                "and --skip-to-enterprise"
+            )
+            sys.exit(1)
+
+        if not skip_enterprise or skip_to_enterprise:
+            missing: list[str] = []
+            if not _ENTERPRISE_REPO:
+                missing.append("ENTERPRISE_REPO")
+            if not _ENTERPRISE_VERSION_DIRS:
+                missing.append("ENTERPRISE_VERSION_DIRS")
+            if not _ENTERPRISE_CREWAI_DEP_PATH:
+                missing.append("ENTERPRISE_CREWAI_DEP_PATH")
+            if missing:
+                console.print(
+                    f"[red]Error:[/red] Missing required environment variable(s): "
+                    f"{', '.join(missing)}\n"
+                    f"Set them or pass --skip-enterprise to skip the enterprise release."
+                )
+                sys.exit(1)
+
         cwd = Path.cwd()
         lib_dir = cwd / "lib"
 
+        is_prerelease = _is_prerelease(version)
+
+        if skip_to_enterprise:
+            _release_enterprise(version, is_prerelease, dry_run)
+            console.print(
+                f"\n[green]✓[/green] Enterprise release [bold]{version}[/bold] complete!"
+            )
+            return
+
         if not dry_run:
             console.print("Checking git status...")
             check_git_clean()
@@ -1337,7 +1850,11 @@ def release(version: str, dry_run: bool, no_edit: bool) -> None:
 
         if not dry_run:
             _create_tag_and_release(tag_name, release_notes, is_prerelease)
-            _trigger_pypi_publish(tag_name)
+            _trigger_pypi_publish(tag_name, wait=True)
+            _update_deployment_test_repo(version, is_prerelease)
+
+        if not skip_enterprise:
+            _release_enterprise(version, is_prerelease, dry_run)
 
         console.print(f"\n[green]✓[/green] Release [bold]{version}[/bold] complete!")
 

uv.lock

@@ -1243,7 +1243,7 @@ requires-dist = [
     { name = "json-repair", specifier = "~=0.25.2" },
     { name = "json5", specifier = "~=0.10.0" },
     { name = "jsonref", specifier = "~=1.1.0" },
-    { name = "lancedb", specifier = ">=0.29.2" },
+    { name = "lancedb", specifier = ">=0.29.2,<0.30.1" },
     { name = "litellm", marker = "extra == 'litellm'", specifier = ">=1.74.9,<=1.82.6" },
     { name = "mcp", specifier = "~=1.26.0" },
     { name = "mem0ai", marker = "extra == 'mem0'", specifier = "~=0.1.94" },