Merge branch 'main' into fix/trace-serialization-pydantic-context

Forwarding strict and sanitizing tool schemas for strict mode causes
Bedrock Converse requests to hang until timeout. Drop strict forwarding
and schema sanitization from the Bedrock provider.

.pre-commit-config.yaml

@@ -24,6 +24,14 @@ repos:
     rev: 0.11.3
     hooks:
       - id: uv-lock
+  - repo: local
+    hooks:
+      - id: pip-audit
+        name: pip-audit
+        entry: bash -c 'source .venv/bin/activate && uv run pip-audit --skip-editable --ignore-vuln CVE-2025-69872 --ignore-vuln CVE-2026-25645 --ignore-vuln CVE-2026-27448 --ignore-vuln CVE-2026-27459 --ignore-vuln PYSEC-2023-235' --
+        language: system
+        pass_filenames: false
+        stages: [pre-push, manual]
   - repo: https://github.com/commitizen-tools/commitizen
     rev: v4.10.1
     hooks:

docs/ar/changelog.mdx

@@ -4,6 +4,87 @@ description: "تحديثات المنتج والتحسينات وإصلاحات
 icon: "clock"
 mode: "wide"
 ---
+<Update label="15 أبريل 2026">
+  ## v1.14.2a4
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.2a4)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - إضافة تلميحات استئناف إلى إصدار أدوات المطورين عند الفشل
+
+  ### إصلاحات الأخطاء
+  - إصلاح توجيه وضع الصرامة إلى واجهة برمجة تطبيقات Bedrock Converse
+  - إصلاح إصدار pytest إلى 9.0.3 لثغرة الأمان GHSA-6w46-j5rx-g56g
+  - رفع الحد الأدنى لـ OpenAI إلى >=2.0.0
+
+  ### الوثائق
+  - تحديث سجل التغييرات والإصدار لـ v1.14.2a3
+
+  ## المساهمون
+
+  @greysonlalonde
+
+</Update>
+
+<Update label="13 أبريل 2026">
+  ## v1.14.2a3
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.2a3)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - إضافة واجهة سطر الأوامر للتحقق من النشر
+  - تحسين سهولة استخدام تهيئة LLM
+
+  ### إصلاحات الأخطاء
+  - تجاوز pypdf و uv إلى إصدارات مصححة لـ CVE-2026-40260 و GHSA-pjjw-68hj-v9mw
+  - ترقية requests إلى >=2.33.0 لمعالجة ثغرة ملف مؤقت CVE
+  - الحفاظ على معلمات استدعاء أداة Bedrock من خلال إزالة القيمة الافتراضية الصحيحة
+  - تنظيف مخططات الأدوات لوضع صارم
+  - إصلاح اختبار تسلسل تضمين MemoryRecord
+
+  ### الوثائق
+  - تنظيف لغة A2A الخاصة بالمؤسسات
+  - إضافة وثائق ميزات A2A الخاصة بالمؤسسات
+  - تحديث وثائق A2A الخاصة بالمصادر المفتوحة
+  - تحديث سجل التغييرات والإصدار لـ v1.14.2a2
+
+  ## المساهمون
+
+  @Yanhu007, @greysonlalonde
+
+</Update>
+
+<Update label="10 أبريل 2026">
+  ## v1.14.2a2
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.2a2)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - إضافة واجهة مستخدم نصية لنقطة التحقق مع عرض شجري، ودعم التفرع، ومدخلات/مخرجات قابلة للتعديل
+  - إثراء تتبع رموز LLM مع رموز الاستدلال ورموز إنشاء التخزين المؤقت
+  - إضافة معلمة `from_checkpoint` إلى طرق الانطلاق
+  - تضمين `crewai_version` في نقاط التحقق مع إطار عمل الهجرة
+  - إضافة تفرع نقاط التحقق مع تتبع السلالة
+
+  ### إصلاحات الأخطاء
+  - إصلاح توجيه الوضع الصارم إلى مزودي Anthropic وBedrock
+  - تعزيز NL2SQLTool مع وضع القراءة فقط الافتراضي، والتحقق من الاستعلامات، والاستعلامات المعلمة
+
+  ### الوثائق
+  - تحديث سجل التغييرات والإصدار لـ v1.14.2a1
+
+  ## المساهمون
+
+  @alex-clawd, @github-actions[bot], @greysonlalonde, @lucasgomide
+
+</Update>
+
 <Update label="9 أبريل 2026">
   ## v1.14.2a1
 

docs/ar/tools/database-data/nl2sqltool.mdx

@@ -11,7 +11,7 @@ mode: "wide"
 
 يتيح ذلك سير عمل متعددة مثل أن يقوم وكيل بالوصول إلى قاعدة البيانات واسترجاع المعلومات بناءً على الهدف ثم استخدام تلك المعلومات لتوليد استجابة أو تقرير أو أي مخرجات أخرى. بالإضافة إلى ذلك، يوفر القدرة للوكيل على تحديث قاعدة البيانات بناءً على هدفه.
 
-**تنبيه**: تأكد من أن الوكيل لديه وصول إلى نسخة قراءة فقط أو أنه من المقبول أن يقوم الوكيل بتنفيذ استعلامات إدراج/تحديث على قاعدة البيانات.
+**تنبيه**: الأداة للقراءة فقط بشكل افتراضي (SELECT/SHOW/DESCRIBE/EXPLAIN فقط). تتطلب عمليات الكتابة تمرير `allow_dml=True` أو ضبط متغير البيئة `CREWAI_NL2SQL_ALLOW_DML=true`. عند تفعيل الكتابة، تأكد من أن الوكيل يستخدم مستخدم قاعدة بيانات محدود الصلاحيات أو نسخة قراءة كلما أمكن.
 
 ## نموذج الأمان
 
@@ -36,6 +36,74 @@ mode: "wide"
 - أضف خطافات `before_tool_call` لفرض أنماط الاستعلام المسموح بها
 - فعّل تسجيل الاستعلامات والتنبيهات للعبارات التدميرية
 
+## وضع القراءة فقط وتهيئة DML
+
+تعمل `NL2SQLTool` في **وضع القراءة فقط بشكل افتراضي**. لا يُسمح إلا بأنواع العبارات التالية دون تهيئة إضافية:
+
+- `SELECT`
+- `SHOW`
+- `DESCRIBE`
+- `EXPLAIN`
+
+أي محاولة لتنفيذ عملية كتابة (`INSERT`، `UPDATE`، `DELETE`، `DROP`، `CREATE`، `ALTER`، `TRUNCATE`، إلخ) ستُسبب خطأً ما لم يتم تفعيل DML صراحةً.
+
+كما تُحظر الاستعلامات متعددة العبارات التي تحتوي على فاصلة منقوطة (مثل `SELECT 1; DROP TABLE users`) في وضع القراءة فقط لمنع هجمات الحقن.
+
+### تفعيل عمليات الكتابة
+
+يمكنك تفعيل DML (لغة معالجة البيانات) بطريقتين:
+
+**الخيار الأول — معامل المُنشئ:**
+
+```python
+from crewai_tools import NL2SQLTool
+
+nl2sql = NL2SQLTool(
+    db_uri="postgresql://example@localhost:5432/test_db",
+    allow_dml=True,
+)
+```
+
+**الخيار الثاني — متغير البيئة:**
+
+```bash
+CREWAI_NL2SQL_ALLOW_DML=true
+```
+
+```python
+from crewai_tools import NL2SQLTool
+
+# DML مفعّل عبر متغير البيئة
+nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db")
+```
+
+### أمثلة الاستخدام
+
+**القراءة فقط (الافتراضي) — آمن للتحليلات والتقارير:**
+
+```python
+from crewai_tools import NL2SQLTool
+
+# يُسمح فقط بـ SELECT/SHOW/DESCRIBE/EXPLAIN
+nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db")
+```
+
+**مع تفعيل DML — مطلوب لأعباء عمل الكتابة:**
+
+```python
+from crewai_tools import NL2SQLTool
+
+# يُسمح بـ INSERT وUPDATE وDELETE وDROP وغيرها
+nl2sql = NL2SQLTool(
+    db_uri="postgresql://example@localhost:5432/test_db",
+    allow_dml=True,
+)
+```
+
+<Warning>
+يمنح تفعيل DML للوكيل القدرة على تعديل البيانات أو حذفها. لا تفعّله إلا عندما يتطلب حالة الاستخدام صراحةً وصولاً للكتابة، وتأكد من أن بيانات اعتماد قاعدة البيانات محدودة بالحد الأدنى من الصلاحيات المطلوبة.
+</Warning>
+
 ## المتطلبات
 
 - SqlAlchemy

docs/docs.json

@@ -392,7 +392,8 @@
                       "en/enterprise/features/marketplace",
                       "en/enterprise/features/agent-repositories",
                       "en/enterprise/features/tools-and-integrations",
-                      "en/enterprise/features/pii-trace-redactions"
+                      "en/enterprise/features/pii-trace-redactions",
+                      "en/enterprise/features/a2a"
                     ]
                   },
                   {
@@ -865,7 +866,8 @@
                       "en/enterprise/features/marketplace",
                       "en/enterprise/features/agent-repositories",
                       "en/enterprise/features/tools-and-integrations",
-                      "en/enterprise/features/pii-trace-redactions"
+                      "en/enterprise/features/pii-trace-redactions",
+                      "en/enterprise/features/a2a"
                     ]
                   },
                   {
@@ -1338,7 +1340,8 @@
                       "en/enterprise/features/marketplace",
                       "en/enterprise/features/agent-repositories",
                       "en/enterprise/features/tools-and-integrations",
-                      "en/enterprise/features/pii-trace-redactions"
+                      "en/enterprise/features/pii-trace-redactions",
+                      "en/enterprise/features/a2a"
                     ]
                   },
                   {
@@ -1811,7 +1814,8 @@
                       "en/enterprise/features/marketplace",
                       "en/enterprise/features/agent-repositories",
                       "en/enterprise/features/tools-and-integrations",
-                      "en/enterprise/features/pii-trace-redactions"
+                      "en/enterprise/features/pii-trace-redactions",
+                      "en/enterprise/features/a2a"
                     ]
                   },
                   {
@@ -2283,7 +2287,8 @@
                       "en/enterprise/features/marketplace",
                       "en/enterprise/features/agent-repositories",
                       "en/enterprise/features/tools-and-integrations",
-                      "en/enterprise/features/pii-trace-redactions"
+                      "en/enterprise/features/pii-trace-redactions",
+                      "en/enterprise/features/a2a"
                     ]
                   },
                   {
@@ -2754,7 +2759,8 @@
                       "en/enterprise/features/marketplace",
                       "en/enterprise/features/agent-repositories",
                       "en/enterprise/features/tools-and-integrations",
-                      "en/enterprise/features/pii-trace-redactions"
+                      "en/enterprise/features/pii-trace-redactions",
+                      "en/enterprise/features/a2a"
                     ]
                   },
                   {
@@ -3225,7 +3231,8 @@
                       "en/enterprise/features/marketplace",
                       "en/enterprise/features/agent-repositories",
                       "en/enterprise/features/tools-and-integrations",
-                      "en/enterprise/features/pii-trace-redactions"
+                      "en/enterprise/features/pii-trace-redactions",
+                      "en/enterprise/features/a2a"
                     ]
                   },
                   {
@@ -3698,7 +3705,8 @@
                       "en/enterprise/features/marketplace",
                       "en/enterprise/features/agent-repositories",
                       "en/enterprise/features/tools-and-integrations",
-                      "en/enterprise/features/pii-trace-redactions"
+                      "en/enterprise/features/pii-trace-redactions",
+                      "en/enterprise/features/a2a"
                     ]
                   },
                   {
@@ -4169,7 +4177,8 @@
                       "en/enterprise/features/marketplace",
                       "en/enterprise/features/agent-repositories",
                       "en/enterprise/features/tools-and-integrations",
-                      "en/enterprise/features/pii-trace-redactions"
+                      "en/enterprise/features/pii-trace-redactions",
+                      "en/enterprise/features/a2a"
                     ]
                   },
                   {
@@ -4643,7 +4652,8 @@
                       "en/enterprise/features/marketplace",
                       "en/enterprise/features/agent-repositories",
                       "en/enterprise/features/tools-and-integrations",
-                      "en/enterprise/features/pii-trace-redactions"
+                      "en/enterprise/features/pii-trace-redactions",
+                      "en/enterprise/features/a2a"
                     ]
                   },
                   {

docs/en/changelog.mdx

@@ -4,6 +4,87 @@ description: "Product updates, improvements, and bug fixes for CrewAI"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="Apr 15, 2026">
+  ## v1.14.2a4
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.2a4)
+
+  ## What's Changed
+
+  ### Features
+  - Add resume hints to devtools release on failure
+
+  ### Bug Fixes
+  - Fix strict mode forwarding to Bedrock Converse API
+  - Fix pytest version to 9.0.3 for security vulnerability GHSA-6w46-j5rx-g56g
+  - Bump OpenAI lower bound to >=2.0.0
+
+  ### Documentation
+  - Update changelog and version for v1.14.2a3
+
+  ## Contributors
+
+  @greysonlalonde
+
+</Update>
+
+<Update label="Apr 13, 2026">
+  ## v1.14.2a3
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.2a3)
+
+  ## What's Changed
+
+  ### Features
+  - Add deploy validation CLI
+  - Improve LLM initialization ergonomics
+
+  ### Bug Fixes
+  - Override pypdf and uv to patched versions for CVE-2026-40260 and GHSA-pjjw-68hj-v9mw
+  - Upgrade requests to >=2.33.0 for CVE temp file vulnerability
+  - Preserve Bedrock tool call arguments by removing truthy default
+  - Sanitize tool schemas for strict mode
+  - Deflake MemoryRecord embedding serialization test
+
+  ### Documentation
+  - Clean up enterprise A2A language
+  - Add enterprise A2A feature documentation
+  - Update OSS A2A documentation
+  - Update changelog and version for v1.14.2a2
+
+  ## Contributors
+
+  @Yanhu007, @greysonlalonde
+
+</Update>
+
+<Update label="Apr 10, 2026">
+  ## v1.14.2a2
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.2a2)
+
+  ## What's Changed
+
+  ### Features
+  - Add checkpoint TUI with tree view, fork support, and editable inputs/outputs
+  - Enrich LLM token tracking with reasoning tokens and cache creation tokens
+  - Add `from_checkpoint` parameter to kickoff methods
+  - Embed `crewai_version` in checkpoints with migration framework
+  - Add checkpoint forking with lineage tracking
+
+  ### Bug Fixes
+  - Fix strict mode forwarding to Anthropic and Bedrock providers
+  - Harden NL2SQLTool with read-only default, query validation, and parameterized queries
+
+  ### Documentation
+  - Update changelog and version for v1.14.2a1
+
+  ## Contributors
+
+  @alex-clawd, @github-actions[bot], @greysonlalonde, @lucasgomide
+
+</Update>
+
 <Update label="Apr 09, 2026">
   ## v1.14.2a1
 

docs/en/concepts/checkpointing.mdx

@@ -54,6 +54,7 @@ crew = Crew(
 | `on_events` | `list[str]` | `["task_completed"]` | Event types that trigger a checkpoint |
 | `provider` | `BaseProvider` | `JsonProvider()` | Storage backend |
 | `max_checkpoints` | `int \| None` | `None` | Max checkpoints to keep. Oldest are pruned after each write. Pruning is handled by the provider. |
+| `restore_from` | `Path \| str \| None` | `None` | Path to a checkpoint to restore from. Used when passing config via a kickoff method's `from_checkpoint` parameter. |
 
 ### Inheritance and Opt-Out
 
@@ -79,13 +80,42 @@ crew = Crew(
 
 ## Resuming from a Checkpoint
 
+Pass a `CheckpointConfig` with `restore_from` to any kickoff method. The crew restores from that checkpoint, skips completed tasks, and resumes.
+
 ```python
-# Restore and resume
-crew = Crew.from_checkpoint("./my_checkpoints/20260407T120000_abc123.json")
-result = crew.kickoff()  # picks up from last completed task
+from crewai import Crew, CheckpointConfig
+
+crew = Crew(agents=[...], tasks=[...])
+result = crew.kickoff(
+    from_checkpoint=CheckpointConfig(
+        restore_from="./my_checkpoints/20260407T120000_abc123.json",
+    ),
+)
 ```
 
-The restored crew skips already-completed tasks and resumes from the first incomplete one.
+Remaining `CheckpointConfig` fields apply to the new run, so checkpointing continues after the restore.
+
+You can also use the classmethod directly:
+
+```python
+config = CheckpointConfig(restore_from="./my_checkpoints/20260407T120000_abc123.json")
+crew = Crew.from_checkpoint(config)
+result = crew.kickoff()
+```
+
+## Forking from a Checkpoint
+
+`fork()` restores a checkpoint and starts a new execution branch. Useful for exploring alternative paths from the same point.
+
+```python
+from crewai import Crew, CheckpointConfig
+
+config = CheckpointConfig(restore_from="./my_checkpoints/20260407T120000_abc123.json")
+crew = Crew.fork(config, branch="experiment-a")
+result = crew.kickoff(inputs={"strategy": "aggressive"})
+```
+
+Each fork gets a unique lineage ID so checkpoints from different branches don't collide. The `branch` label is optional and auto-generated if omitted.
 
 ## Works on Crew, Flow, and Agent
 
@@ -125,7 +155,8 @@ flow = MyFlow(
 result = flow.kickoff()
 
 # Resume
-flow = MyFlow.from_checkpoint("./flow_cp/20260407T120000_abc123.json")
+config = CheckpointConfig(restore_from="./flow_cp/20260407T120000_abc123.json")
+flow = MyFlow.from_checkpoint(config)
 result = flow.kickoff()
 ```
 
@@ -231,3 +262,44 @@ async def on_llm_done_async(source, event, state):
 The `state` argument is the `RuntimeState` passed automatically by the event bus when your handler accepts 3 parameters. You can register handlers on any event type listed in the [Event Listeners](/en/concepts/event-listener) documentation.
 
 Checkpointing is best-effort: if a checkpoint write fails, the error is logged but execution continues uninterrupted.
+
+## CLI
+
+The `crewai checkpoint` command gives you a TUI for browsing, inspecting, resuming, and forking checkpoints. It auto-detects whether your checkpoints are JSON files or a SQLite database.
+
+```bash
+# Launch the TUI — auto-detects .checkpoints/ or .checkpoints.db
+crewai checkpoint
+
+# Point at a specific location
+crewai checkpoint --location ./my_checkpoints
+crewai checkpoint --location ./.checkpoints.db
+```
+
+<Frame>
+  <img src="/images/checkpointing.png" alt="Checkpoint TUI" />
+</Frame>
+
+The left panel is a tree view. Checkpoints are grouped by branch, and forks nest under the checkpoint they diverged from. Select a checkpoint to see its metadata, entity state, and task progress in the detail panel. Hit **Resume** to pick up where it left off, or **Fork** to start a new branch from that point.
+
+### Editing inputs and task outputs
+
+When a checkpoint is selected, the detail panel shows:
+
+- **Inputs** — if the original kickoff had inputs (e.g. `{topic}`), they appear as editable fields pre-filled with the original values. Change them before resuming or forking.
+- **Task outputs** — completed tasks show their output in editable text areas. Edit a task's output to change the context that downstream tasks receive. When you modify a task output and hit Fork, all subsequent tasks are invalidated and re-run with the new context.
+
+This is useful for "what if" exploration — fork from a checkpoint, tweak a task's result, and see how it changes downstream behavior.
+
+### Subcommands
+
+```bash
+# List all checkpoints
+crewai checkpoint list ./my_checkpoints
+
+# Inspect a specific checkpoint
+crewai checkpoint info ./my_checkpoints/20260407T120000_abc123.json
+
+# Inspect latest in a SQLite database
+crewai checkpoint info ./.checkpoints.db
+```

docs/en/enterprise/features/a2a.mdx

@@ -0,0 +1,227 @@
+---
+title: A2A on AMP
+description: Production-grade Agent-to-Agent communication with distributed state and multi-scheme authentication
+icon: "network-wired"
+mode: "wide"
+---
+
+<Warning>
+A2A server agents on AMP are in early release. APIs may change in future versions.
+</Warning>
+
+## Overview
+
+CrewAI AMP extends the open-source [A2A protocol implementation](/en/learn/a2a-agent-delegation) with production infrastructure for deploying distributed agents at scale. AMP supports A2A protocol versions 0.2 and 0.3. When you deploy a crew or agent with A2A server configuration to AMP, the platform automatically provisions distributed state management, authentication, multi-transport endpoints, and lifecycle management.
+
+<Note>
+  For A2A protocol fundamentals, client/server configuration, and authentication schemes, see the [A2A Agent Delegation](/en/learn/a2a-agent-delegation) documentation. This page covers what AMP adds on top of the open-source implementation.
+</Note>
+
+### Usage
+
+Add `A2AServerConfig` to any agent in your crew and deploy to AMP. The platform detects agents with server configuration and automatically registers A2A endpoints, generates agent cards, and provisions the infrastructure described below.
+
+```python
+from crewai import Agent, Crew, Task
+from crewai.a2a import A2AServerConfig
+from crewai.a2a.auth import EnterpriseTokenAuth
+
+agent = Agent(
+    role="Data Analyst",
+    goal="Analyze datasets and provide insights",
+    backstory="Expert data scientist with statistical analysis skills",
+    llm="gpt-4o",
+    a2a=A2AServerConfig(
+        auth=EnterpriseTokenAuth()
+    )
+)
+
+task = Task(
+    description="Analyze the provided dataset",
+    expected_output="Statistical summary with key insights",
+    agent=agent
+)
+
+crew = Crew(agents=[agent], tasks=[task])
+```
+
+After [deploying to AMP](/en/enterprise/guides/deploy-to-amp), the platform registers two levels of A2A endpoints:
+
+- **Crew-level**: an aggregate agent card at `/.well-known/agent-card.json` where each agent with `A2AServerConfig` is listed as a skill, with a JSON-RPC endpoint at `/a2a`
+- **Per-agent**: isolated agent cards and JSON-RPC endpoints mounted at `/a2a/agents/{role}/`, each with its own tenancy
+
+Clients can interact with the crew as a whole or target a specific agent directly. To route a request to a specific agent through the crew-level endpoint, include `"target_agent"` in the message metadata with the agent's slugified role name (e.g., `"data-analyst"` for an agent with role `"Data Analyst"`). If no `target_agent` is provided, the request is handled by the first agent in the crew.
+
+See [A2A Agent Delegation](/en/learn/a2a-agent-delegation#server-configuration-options) for the full list of `A2AServerConfig` options.
+
+<Warning>
+  Per the A2A protocol, agent cards are publicly accessible to enable discovery. This includes both the crew-level card at `/.well-known/agent-card.json` and per-agent cards at `/a2a/agents/{role}/.well-known/agent-card.json`. Do not include sensitive information in agent names, descriptions, or skill definitions.
+</Warning>
+
+### File Inputs and Structured Output
+
+A2A on AMP supports passing files and requesting structured output in both directions. Clients can send files as `FilePart`s and request structured responses by embedding a JSON schema in the message. Server agents receive files as `input_files` on the task, and return structured data as `DataPart`s when a schema is provided. See [File Inputs and Structured Output](/en/learn/a2a-agent-delegation#file-inputs-and-structured-output) for details.
+
+### What AMP Adds
+
+<CardGroup cols={2}>
+  <Card title="Distributed State" icon="database">
+    Persistent task, context, and result storage
+  </Card>
+  <Card title="Enterprise Authentication" icon="shield-halved">
+    OIDC, OAuth2, mTLS, and Enterprise token validation beyond simple bearer tokens
+  </Card>
+  <Card title="gRPC Transport" icon="bolt">
+    Full gRPC server with TLS and authentication
+  </Card>
+  <Card title="Context Lifecycle" icon="clock-rotate-left">
+    Automatic idle detection, expiration, and cleanup of long-running conversations
+  </Card>
+  <Card title="Signed Webhooks" icon="signature">
+    HMAC-SHA256 signed push notifications with replay protection
+  </Card>
+  <Card title="Multi-Transport" icon="arrows-split-up-and-left">
+    REST, JSON-RPC, and gRPC endpoints served simultaneously from a single deployment
+  </Card>
+</CardGroup>
+
+---
+
+## Distributed State Management
+
+In the open-source implementation, task and context state lives in memory on a single process. AMP replaces this with persistent, distributed stores.
+
+### Storage Layers
+
+| Store | Purpose |
+|---|---|
+| **Task Store** | Persists A2A task state and metadata |
+| **Context Store** | Tracks conversation context, creation time, last activity, and associated tasks |
+| **Result Store** | Caches task results for retrieval |
+| **Push Config Store** | Manages webhook subscriptions per task |
+
+Multiple A2A deployments are automatically isolated from each other, preventing data collisions when sharing infrastructure.
+
+---
+
+## Enterprise Authentication
+
+AMP supports six authentication schemes for incoming A2A requests, configurable per deployment. Authentication works across both HTTP and gRPC transports.
+
+| Scheme | Description | Use Case |
+|---|---|---|
+| **SimpleTokenAuth** | Static bearer token from `AUTH_TOKEN` env var | Development, simple deployments |
+| **EnterpriseTokenAuth** | Token verification via CrewAI PlusAPI with integration token claims | AMP-to-AMP agent communication |
+| **OIDCAuth** | OpenID Connect JWT validation with JWKS endpoint caching | Enterprise SSO integration |
+| **OAuth2ServerAuth** | OAuth2 with configurable scopes | Fine-grained access control |
+| **APIKeyServerAuth** | API key validation via header or query parameter | Third-party integrations |
+| **MTLSServerAuth** | Mutual TLS certificate-based authentication | Zero-trust environments |
+
+The configured auth scheme automatically populates the agent card's `securitySchemes` and `security` fields. Clients discover authentication requirements by fetching the agent card before making requests.
+
+---
+
+## Extended Agent Cards
+
+AMP supports role-based skill visibility through extended agent cards. Unauthenticated users see the standard agent card with public skills. Authenticated users receive an extended card with additional capabilities.
+
+This enables patterns like:
+- Public agents that expose basic skills to anyone, with advanced skills available to authenticated clients
+- Internal agents that advertise different capabilities based on the caller's identity
+
+---
+
+## gRPC Transport
+
+If enabled, AMP provides full gRPC support alongside the default JSON-RPC transport.
+
+- **TLS termination** with configurable certificate and key paths
+- **gRPC reflection** for debugging with tools like `grpcurl`
+- **Authentication** using the same schemes available for HTTP
+- **Extension validation** ensuring clients support required protocol extensions
+- **Version negotiation** across A2A protocol versions 0.2 and 0.3
+
+For deployments exposing multiple agents, AMP automatically allocates per-agent gRPC ports and coordinates TLS, startup, and shutdown across all servers.
+
+---
+
+## Context Lifecycle Management
+
+AMP tracks the lifecycle of A2A conversation contexts and automatically manages cleanup.
+
+### Lifecycle States
+
+| State | Condition | Action |
+|---|---|---|
+| **Active** | Context has recent activity | None |
+| **Idle** | No activity for a configured period | Marked idle, event emitted |
+| **Expired** | Context exceeds its maximum lifetime | Marked expired, associated tasks cleaned up, event emitted |
+
+A background cleanup task runs hourly to scan for idle and expired contexts. All state transitions emit CrewAI events that integrate with the platform's observability features.
+
+---
+
+## Signed Push Notifications
+
+When an A2A agent sends push notifications to a client webhook, AMP signs each request with HMAC-SHA256 to ensure integrity and prevent tampering.
+
+### Signature Headers
+
+| Header | Purpose |
+|---|---|
+| `X-A2A-Signature` | HMAC-SHA256 signature in `sha256={hex_digest}` format |
+| `X-A2A-Signature-Timestamp` | Unix timestamp bound to the signature |
+| `X-A2A-Notification-Token` | Optional notification auth token |
+
+### Security Properties
+
+- **Integrity**: payload cannot be modified without invalidating the signature
+- **Replay protection**: signatures are timestamp-bound with a configurable tolerance window
+- **Retry with backoff**: failed deliveries retry with exponential backoff
+
+---
+
+## Distributed Event Streaming
+
+In the open-source implementation, SSE streaming works within a single process. AMP propagates SSE events across instances so that clients receive updates even when the instance holding the streaming connection differs from the instance executing the task.
+
+---
+
+## Multi-Transport Endpoints
+
+AMP serves REST and JSON-RPC by default. gRPC is available as an additional transport if enabled.
+
+| Transport | Path Convention | Description |
+|---|---|---|
+| **REST** | `/v1/message:send`, `/v1/message:stream`, `/v1/tasks` | Google API conventions |
+| **JSON-RPC** | Standard A2A JSON-RPC endpoint | Default A2A protocol transport |
+| **gRPC** | Per-agent port allocation | Optional, high-performance binary protocol |
+
+All active transports share the same authentication, version negotiation, and extension validation. Agent cards are generated from agent and crew metadata — roles, goals, and tools become skills and descriptions — and automatically include interfaces for each active transport. They can also be manually configured via `A2AServerConfig`.
+
+---
+
+## Version and Extension Negotiation
+
+AMP validates A2A protocol versions and extensions at the transport layer.
+
+### Version Negotiation
+
+- Clients send the `A2A-Version` header with their preferred version
+- AMP validates against supported versions (0.2, 0.3) and falls back to 0.3 if unspecified
+- The negotiated version is returned in the response headers
+
+### Extension Validation
+
+- Clients declare supported extensions via the `X-A2A-Extensions` header
+- AMP validates that clients support all extensions the agent requires
+- Requests from clients missing required extensions receive an `UnsupportedExtensionError`
+
+---
+
+## Next Steps
+
+- [A2A Agent Delegation](/en/learn/a2a-agent-delegation) — A2A protocol fundamentals and configuration
+- [A2UI](/en/learn/a2ui) — Interactive UI rendering over A2A
+- [Deploy to AMP](/en/enterprise/guides/deploy-to-amp) — General deployment guide
+- [Webhook Streaming](/en/enterprise/features/webhook-streaming) — Event streaming for deployed automations

docs/en/learn/a2a-agent-delegation.mdx

@@ -7,6 +7,10 @@ mode: "wide"
 
 ## A2A Agent Delegation
 
+<Info>
+  Deploying A2A agents to production? See [A2A on AMP](/en/enterprise/features/a2a) for distributed state, enterprise authentication, gRPC transport, and horizontal scaling.
+</Info>
+
 CrewAI treats [A2A protocol](https://a2a-protocol.org/latest/) as a first-class delegation primitive, enabling agents to delegate tasks, request information, and collaborate with remote agents, as well as act as A2A-compliant server agents.
 In client mode, agents autonomously choose between local execution and remote delegation based on task requirements.
 
@@ -96,24 +100,28 @@ The `A2AClientConfig` class accepts the following parameters:
   Update mechanism for receiving task status. Options: `StreamingConfig`, `PollingConfig`, or `PushNotificationConfig`.
 </ParamField>
 
-<ParamField path="transport_protocol" type="Literal['JSONRPC', 'GRPC', 'HTTP+JSON']" default="JSONRPC">
-  Transport protocol for A2A communication. Options: `JSONRPC` (default), `GRPC`, or `HTTP+JSON`.
-</ParamField>
-
 <ParamField path="accepted_output_modes" type="list[str]" default='["application/json"]'>
   Media types the client can accept in responses.
 </ParamField>
 
-<ParamField path="supported_transports" type="list[str]" default='["JSONRPC"]'>
-  Ordered list of transport protocols the client supports.
-</ParamField>
-
-<ParamField path="use_client_preference" type="bool" default="False">
-  Whether to prioritize client transport preferences over server.
-</ParamField>
-
 <ParamField path="extensions" type="list[str]" default="[]">
-  Extension URIs the client supports.
+  A2A protocol extension URIs the client supports.
+</ParamField>
+
+<ParamField path="client_extensions" type="list[A2AExtension]" default="[]">
+  Client-side processing hooks for tool injection, prompt augmentation, and response modification.
+</ParamField>
+
+<ParamField path="transport" type="ClientTransportConfig" default="ClientTransportConfig()">
+  Transport configuration including preferred transport, supported transports for negotiation, and protocol-specific settings (gRPC message sizes, keepalive, etc.).
+</ParamField>
+
+<ParamField path="transport_protocol" type="Literal['JSONRPC', 'GRPC', 'HTTP+JSON']" default="None">
+  **Deprecated**: Use `transport=ClientTransportConfig(preferred=...)` instead.
+</ParamField>
+
+<ParamField path="supported_transports" type="list[str]" default="None">
+  **Deprecated**: Use `transport=ClientTransportConfig(supported=...)` instead.
 </ParamField>
 
 ## Authentication
@@ -405,11 +413,7 @@ agent = Agent(
   Preferred endpoint URL. If set, overrides the URL passed to `to_agent_card()`.
 </ParamField>
 
-<ParamField path="preferred_transport" type="Literal['JSONRPC', 'GRPC', 'HTTP+JSON']" default="JSONRPC">
-  Transport protocol for the preferred endpoint.
-</ParamField>
-
-<ParamField path="protocol_version" type="str" default="0.3">
+<ParamField path="protocol_version" type="str" default="0.3.0">
   A2A protocol version this agent supports.
 </ParamField>
 
@@ -441,8 +445,36 @@ agent = Agent(
   Whether agent provides extended card to authenticated users.
 </ParamField>
 
-<ParamField path="signatures" type="list[AgentCardSignature]" default="[]">
-  JSON Web Signatures for the AgentCard.
+<ParamField path="extended_skills" type="list[AgentSkill]" default="[]">
+  Additional skills visible only to authenticated users in the extended agent card.
+</ParamField>
+
+<ParamField path="signing_config" type="AgentCardSigningConfig" default="None">
+  Configuration for signing the AgentCard with JWS. Supports RS256, ES256, PS256, and related algorithms.
+</ParamField>
+
+<ParamField path="server_extensions" type="list[ServerExtension]" default="[]">
+  Server-side A2A protocol extensions with `on_request`/`on_response` hooks that modify agent behavior.
+</ParamField>
+
+<ParamField path="push_notifications" type="ServerPushNotificationConfig" default="None">
+  Configuration for outgoing push notifications, including HMAC-SHA256 signing secret.
+</ParamField>
+
+<ParamField path="transport" type="ServerTransportConfig" default="ServerTransportConfig()">
+  Transport configuration including preferred transport, gRPC server settings, JSON-RPC paths, and HTTP+JSON settings.
+</ParamField>
+
+<ParamField path="auth" type="ServerAuthScheme" default="None">
+  Authentication scheme for incoming A2A requests. Defaults to `SimpleTokenAuth` using the `AUTH_TOKEN` environment variable.
+</ParamField>
+
+<ParamField path="preferred_transport" type="Literal['JSONRPC', 'GRPC', 'HTTP+JSON']" default="None">
+  **Deprecated**: Use `transport=ServerTransportConfig(preferred=...)` instead.
+</ParamField>
+
+<ParamField path="signatures" type="list[AgentCardSignature]" default="None">
+  **Deprecated**: Use `signing_config=AgentCardSigningConfig(...)` instead.
 </ParamField>
 
 ### Combined Client and Server
@@ -468,6 +500,14 @@ agent = Agent(
 )
 ```
 
+### File Inputs and Structured Output
+
+A2A supports passing files and requesting structured output in both directions.
+
+**Client side**: When delegating to a remote A2A agent, files from the task's `input_files` are sent as `FilePart`s in the outgoing message. If `response_model` is set on the `A2AClientConfig`, the Pydantic model's JSON schema is embedded in the message metadata, requesting structured output from the remote agent.
+
+**Server side**: Incoming `FilePart`s are extracted and passed to the agent's task as `input_files`. If the client included a JSON schema, the server creates a response model from it and applies it to the task. When the agent returns structured data, the response is sent back as a `DataPart` rather than plain text.
+
 ## Best Practices
 
 <CardGroup cols={2}>

docs/en/tools/database-data/nl2sqltool.mdx

@@ -13,7 +13,7 @@ This tool is used to convert natural language to SQL queries. When passed to the
 This enables multiple workflows like having an Agent to access the database fetch information based on the goal and then use the information to generate a response, report or any other output. 
 Along with that provides the ability for the Agent to update the database based on its goal.
 
-**Attention**: Make sure that the Agent has access to a Read-Replica or that is okay for the Agent to run insert/update queries on the database.
+**Attention**: By default the tool is read-only (SELECT/SHOW/DESCRIBE/EXPLAIN only). Write operations require `allow_dml=True` or the `CREWAI_NL2SQL_ALLOW_DML=true` environment variable. When write access is enabled, make sure the Agent uses a scoped database user or a read replica where possible.
 
 ## Security Model
 
@@ -38,6 +38,74 @@ Use all of the following in production:
 - Add `before_tool_call` hooks to enforce allowed query patterns
 - Enable query logging and alerting for destructive statements
 
+## Read-Only Mode & DML Configuration
+
+`NL2SQLTool` operates in **read-only mode by default**. Only the following statement types are permitted without additional configuration:
+
+- `SELECT`
+- `SHOW`
+- `DESCRIBE`
+- `EXPLAIN`
+
+Any attempt to execute a write operation (`INSERT`, `UPDATE`, `DELETE`, `DROP`, `CREATE`, `ALTER`, `TRUNCATE`, etc.) will raise an error unless DML is explicitly enabled.
+
+Multi-statement queries containing semicolons (e.g. `SELECT 1; DROP TABLE users`) are also blocked in read-only mode to prevent injection attacks.
+
+### Enabling Write Operations
+
+You can enable DML (Data Manipulation Language) in two ways:
+
+**Option 1 — constructor parameter:**
+
+```python
+from crewai_tools import NL2SQLTool
+
+nl2sql = NL2SQLTool(
+    db_uri="postgresql://example@localhost:5432/test_db",
+    allow_dml=True,
+)
+```
+
+**Option 2 — environment variable:**
+
+```bash
+CREWAI_NL2SQL_ALLOW_DML=true
+```
+
+```python
+from crewai_tools import NL2SQLTool
+
+# DML enabled via environment variable
+nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db")
+```
+
+### Usage Examples
+
+**Read-only (default) — safe for analytics and reporting:**
+
+```python
+from crewai_tools import NL2SQLTool
+
+# Only SELECT/SHOW/DESCRIBE/EXPLAIN are permitted
+nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db")
+```
+
+**DML enabled — required for write workloads:**
+
+```python
+from crewai_tools import NL2SQLTool
+
+# INSERT, UPDATE, DELETE, DROP, etc. are permitted
+nl2sql = NL2SQLTool(
+    db_uri="postgresql://example@localhost:5432/test_db",
+    allow_dml=True,
+)
+```
+
+<Warning>
+Enabling DML gives the agent the ability to modify or destroy data. Only enable this when your use case explicitly requires write access, and ensure the database credentials are scoped to the minimum required privileges.
+</Warning>
+
 ## Requirements
 
 - SqlAlchemy

docs/ko/changelog.mdx

@@ -4,6 +4,87 @@ description: "CrewAI의 제품 업데이트, 개선 사항 및 버그 수정"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="2026년 4월 15일">
+  ## v1.14.2a4
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.14.2a4)
+
+  ## 변경 사항
+
+  ### 기능
+  - 실패 시 devtools 릴리스에 이력서 힌트 추가
+
+  ### 버그 수정
+  - Bedrock Converse API로의 엄격 모드 포워딩 수정
+  - 보안 취약점 GHSA-6w46-j5rx-g56g에 대해 pytest 버전을 9.0.3으로 수정
+  - OpenAI 하한을 >=2.0.0으로 상향 조정
+
+  ### 문서
+  - v1.14.2a3에 대한 변경 로그 및 버전 업데이트
+
+  ## 기여자
+
+  @greysonlalonde
+
+</Update>
+
+<Update label="2026년 4월 13일">
+  ## v1.14.2a3
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.14.2a3)
+
+  ## 변경 사항
+
+  ### 기능
+  - 배포 검증 CLI 추가
+  - LLM 초기화 사용성 개선
+
+  ### 버그 수정
+  - CVE-2026-40260 및 GHSA-pjjw-68hj-v9mw에 대한 패치된 버전으로 pypdf 및 uv 재정의
+  - CVE 임시 파일 취약점에 대해 requests를 >=2.33.0으로 업그레이드
+  - 진리값 기본값을 제거하여 Bedrock 도구 호출 인수 보존
+  - 엄격 모드를 위한 도구 스키마 정리
+  - MemoryRecord 임베딩 직렬화 테스트의 불안정성 제거
+
+  ### 문서
+  - 기업 A2A 언어 정리
+  - 기업 A2A 기능 문서 추가
+  - OSS A2A 문서 업데이트
+  - v1.14.2a2에 대한 변경 로그 및 버전 업데이트
+
+  ## 기여자
+
+  @Yanhu007, @greysonlalonde
+
+</Update>
+
+<Update label="2026년 4월 10일">
+  ## v1.14.2a2
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.14.2a2)
+
+  ## 변경 사항
+
+  ### 기능
+  - 트리 뷰, 포크 지원 및 편집 가능한 입력/출력을 갖춘 체크포인트 TUI 추가
+  - 추론 토큰 및 캐시 생성 토큰으로 LLM 토큰 추적 강화
+  - 킥오프 메서드에 `from_checkpoint` 매개변수 추가
+  - 마이그레이션 프레임워크와 함께 체크포인트에 `crewai_version` 포함
+  - 계보 추적이 가능한 체크포인트 포킹 추가
+
+  ### 버그 수정
+  - Anthropic 및 Bedrock 공급자로의 엄격 모드 포워딩 수정
+  - 읽기 전용 기본값, 쿼리 검증 및 매개변수화된 쿼리로 NL2SQLTool 강화
+
+  ### 문서
+  - v1.14.2a1에 대한 변경 로그 및 버전 업데이트
+
+  ## 기여자
+
+  @alex-clawd, @github-actions[bot], @greysonlalonde, @lucasgomide
+
+</Update>
+
 <Update label="2026년 4월 9일">
   ## v1.14.2a1
 

docs/ko/tools/database-data/nl2sqltool.mdx

@@ -11,7 +11,75 @@ mode: "wide"
 
 이를 통해 에이전트가 데이터베이스에 접근하여 목표에 따라 정보를 가져오고, 해당 정보를 사용해 응답, 보고서 또는 기타 출력물을 생성하는 다양한 워크플로우가 가능해집니다. 또한 에이전트가 자신의 목표에 맞춰 데이터베이스를 업데이트할 수 있는 기능도 제공합니다.
 
-**주의**: 에이전트가 Read-Replica에 접근할 수 있거나, 에이전트가 데이터베이스에 insert/update 쿼리를 실행해도 괜찮은지 반드시 확인하십시오.
+**주의**: 도구는 기본적으로 읽기 전용(SELECT/SHOW/DESCRIBE/EXPLAIN만 허용)으로 동작합니다. 쓰기 작업을 수행하려면 `allow_dml=True` 매개변수 또는 `CREWAI_NL2SQL_ALLOW_DML=true` 환경 변수가 필요합니다. 쓰기 접근이 활성화된 경우, 가능하면 권한이 제한된 데이터베이스 사용자나 읽기 복제본을 사용하십시오.
+
+## 읽기 전용 모드 및 DML 구성
+
+`NL2SQLTool`은 기본적으로 **읽기 전용 모드**로 동작합니다. 추가 구성 없이 허용되는 구문 유형은 다음과 같습니다:
+
+- `SELECT`
+- `SHOW`
+- `DESCRIBE`
+- `EXPLAIN`
+
+DML을 명시적으로 활성화하지 않으면 쓰기 작업(`INSERT`, `UPDATE`, `DELETE`, `DROP`, `CREATE`, `ALTER`, `TRUNCATE` 등)을 실행하려고 할 때 오류가 발생합니다.
+
+읽기 전용 모드에서는 세미콜론이 포함된 다중 구문 쿼리(예: `SELECT 1; DROP TABLE users`)도 인젝션 공격을 방지하기 위해 차단됩니다.
+
+### 쓰기 작업 활성화
+
+DML(데이터 조작 언어)을 활성화하는 방법은 두 가지입니다:
+
+**옵션 1 — 생성자 매개변수:**
+
+```python
+from crewai_tools import NL2SQLTool
+
+nl2sql = NL2SQLTool(
+    db_uri="postgresql://example@localhost:5432/test_db",
+    allow_dml=True,
+)
+```
+
+**옵션 2 — 환경 변수:**
+
+```bash
+CREWAI_NL2SQL_ALLOW_DML=true
+```
+
+```python
+from crewai_tools import NL2SQLTool
+
+# 환경 변수를 통해 DML 활성화
+nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db")
+```
+
+### 사용 예시
+
+**읽기 전용(기본값) — 분석 및 보고 워크로드에 안전:**
+
+```python
+from crewai_tools import NL2SQLTool
+
+# SELECT/SHOW/DESCRIBE/EXPLAIN만 허용
+nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db")
+```
+
+**DML 활성화 — 쓰기 워크로드에 필요:**
+
+```python
+from crewai_tools import NL2SQLTool
+
+# INSERT, UPDATE, DELETE, DROP 등이 허용됨
+nl2sql = NL2SQLTool(
+    db_uri="postgresql://example@localhost:5432/test_db",
+    allow_dml=True,
+)
+```
+
+<Warning>
+DML을 활성화하면 에이전트가 데이터를 수정하거나 삭제할 수 있습니다. 사용 사례에서 명시적으로 쓰기 접근이 필요한 경우에만 활성화하고, 데이터베이스 자격 증명이 최소 필요 권한으로 제한되어 있는지 확인하십시오.
+</Warning>
 
 ## 요구 사항
 

docs/pt-BR/changelog.mdx

@@ -4,6 +4,87 @@ description: "Atualizações de produto, melhorias e correções do CrewAI"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="15 abr 2026">
+  ## v1.14.2a4
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.2a4)
+
+  ## O que Mudou
+
+  ### Recursos
+  - Adicionar dicas de retomar ao release do devtools em caso de falha
+
+  ### Correções de Bugs
+  - Corrigir o encaminhamento do modo estrito para a API Bedrock Converse
+  - Corrigir a versão do pytest para 9.0.3 devido à vulnerabilidade de segurança GHSA-6w46-j5rx-g56g
+  - Aumentar o limite inferior do OpenAI para >=2.0.0
+
+  ### Documentação
+  - Atualizar o changelog e a versão para v1.14.2a3
+
+  ## Contribuidores
+
+  @greysonlalonde
+
+</Update>
+
+<Update label="13 abr 2026">
+  ## v1.14.2a3
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.2a3)
+
+  ## O que Mudou
+
+  ### Recursos
+  - Adicionar CLI de validação de deploy
+  - Melhorar a ergonomia de inicialização do LLM
+
+  ### Correções de Bugs
+  - Substituir pypdf e uv por versões corrigidas para CVE-2026-40260 e GHSA-pjjw-68hj-v9mw
+  - Atualizar requests para >=2.33.0 devido à vulnerabilidade de arquivo temporário CVE
+  - Preservar os argumentos de chamada da ferramenta Bedrock removendo o padrão truthy
+  - Sanitizar esquemas de ferramentas para modo estrito
+  - Remover flakiness do teste de serialização de embedding MemoryRecord
+
+  ### Documentação
+  - Limpar a linguagem do A2A empresarial
+  - Adicionar documentação de recursos do A2A empresarial
+  - Atualizar documentação do A2A OSS
+  - Atualizar changelog e versão para v1.14.2a2
+
+  ## Contribuidores
+
+  @Yanhu007, @greysonlalonde
+
+</Update>
+
+<Update label="10 abr 2026">
+  ## v1.14.2a2
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.2a2)
+
+  ## O que Mudou
+
+  ### Funcionalidades
+  - Adicionar TUI de ponto de verificação com visualização em árvore, suporte a bifurcações e entradas/saídas editáveis
+  - Enriquecer o rastreamento de tokens LLM com tokens de raciocínio e tokens de criação de cache
+  - Adicionar parâmetro `from_checkpoint` aos métodos de inicialização
+  - Incorporar `crewai_version` em pontos de verificação com o framework de migração
+  - Adicionar bifurcação de ponto de verificação com rastreamento de linhagem
+
+  ### Correções de Bugs
+  - Corrigir o encaminhamento em modo estrito para os provedores Anthropic e Bedrock
+  - Fortalecer NL2SQLTool com padrão somente leitura, validação de consultas e consultas parametrizadas
+
+  ### Documentação
+  - Atualizar changelog e versão para v1.14.2a1
+
+  ## Contributors
+
+  @alex-clawd, @github-actions[bot], @greysonlalonde, @lucasgomide
+
+</Update>
+
 <Update label="09 abr 2026">
   ## v1.14.2a1
 

docs/pt-BR/tools/database-data/nl2sqltool.mdx

@@ -11,7 +11,75 @@ Esta ferramenta é utilizada para converter linguagem natural em consultas SQL.
 
 Isso possibilita múltiplos fluxos de trabalho, como por exemplo ter um Agente acessando o banco de dados para buscar informações com base em um objetivo e, então, usar essas informações para gerar uma resposta, relatório ou qualquer outro tipo de saída. Além disso, permite que o Agente atualize o banco de dados de acordo com seu objetivo.
 
-**Atenção**: Certifique-se de que o Agente tenha acesso a um Read-Replica ou que seja permitido que o Agente execute consultas de inserção/atualização no banco de dados.
+**Atenção**: Por padrão, a ferramenta opera em modo somente leitura (apenas SELECT/SHOW/DESCRIBE/EXPLAIN). Operações de escrita exigem `allow_dml=True` ou a variável de ambiente `CREWAI_NL2SQL_ALLOW_DML=true`. Quando o acesso de escrita estiver habilitado, certifique-se de que o Agente use um usuário de banco de dados com privilégios mínimos ou um Read-Replica sempre que possível.
+
+## Modo Somente Leitura e Configuração de DML
+
+O `NL2SQLTool` opera em **modo somente leitura por padrão**. Apenas os seguintes tipos de instrução são permitidos sem configuração adicional:
+
+- `SELECT`
+- `SHOW`
+- `DESCRIBE`
+- `EXPLAIN`
+
+Qualquer tentativa de executar uma operação de escrita (`INSERT`, `UPDATE`, `DELETE`, `DROP`, `CREATE`, `ALTER`, `TRUNCATE`, etc.) resultará em erro, a menos que o DML seja habilitado explicitamente.
+
+Consultas com múltiplas instruções contendo ponto e vírgula (ex.: `SELECT 1; DROP TABLE users`) também são bloqueadas no modo somente leitura para prevenir ataques de injeção.
+
+### Habilitando Operações de Escrita
+
+Você pode habilitar DML (Linguagem de Manipulação de Dados) de duas formas:
+
+**Opção 1 — parâmetro do construtor:**
+
+```python
+from crewai_tools import NL2SQLTool
+
+nl2sql = NL2SQLTool(
+    db_uri="postgresql://example@localhost:5432/test_db",
+    allow_dml=True,
+)
+```
+
+**Opção 2 — variável de ambiente:**
+
+```bash
+CREWAI_NL2SQL_ALLOW_DML=true
+```
+
+```python
+from crewai_tools import NL2SQLTool
+
+# DML habilitado via variável de ambiente
+nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db")
+```
+
+### Exemplos de Uso
+
+**Somente leitura (padrão) — seguro para análise e relatórios:**
+
+```python
+from crewai_tools import NL2SQLTool
+
+# Apenas SELECT/SHOW/DESCRIBE/EXPLAIN são permitidos
+nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db")
+```
+
+**Com DML habilitado — necessário para workloads de escrita:**
+
+```python
+from crewai_tools import NL2SQLTool
+
+# INSERT, UPDATE, DELETE, DROP, etc. são permitidos
+nl2sql = NL2SQLTool(
+    db_uri="postgresql://example@localhost:5432/test_db",
+    allow_dml=True,
+)
+```
+
+<Warning>
+Habilitar DML concede ao agente a capacidade de modificar ou destruir dados. Ative apenas quando o seu caso de uso exigir explicitamente acesso de escrita e certifique-se de que as credenciais do banco de dados estejam limitadas aos privilégios mínimos necessários.
+</Warning>
 
 ## Requisitos
 

lib/crewai-files/pyproject.toml

@@ -9,7 +9,7 @@ authors = [
 requires-python = ">=3.10, <3.14"
 dependencies = [
     "Pillow~=12.1.1",
-    "pypdf~=6.9.1",
+    "pypdf~=6.10.0",
     "python-magic>=0.4.27",
     "aiocache~=0.12.3",
     "aiofiles~=24.1.0",

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

@@ -152,4 +152,4 @@ __all__ = [
     "wrap_file_source",
 ]
 
-__version__ = "1.14.2a1"
+__version__ = "1.14.2a4"

lib/crewai-tools/pyproject.toml

@@ -9,8 +9,8 @@ authors = [
 requires-python = ">=3.10, <3.14"
 dependencies = [
     "pytube~=15.0.0",
-    "requests~=2.32.5",
-    "crewai==1.14.2a1",
+    "requests>=2.33.0,<3",
+    "crewai==1.14.2a4",
     "tiktoken~=0.8.0",
     "beautifulsoup4~=4.13.4",
     "python-docx~=1.2.0",

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

@@ -305,4 +305,4 @@ __all__ = [
     "ZapierActionTools",
 ]
 
-__version__ = "1.14.2a1"
+__version__ = "1.14.2a4"

lib/crewai-tools/src/crewai_tools/tools/nl2sql/nl2sql_tool.py

@@ -1,7 +1,17 @@
+from collections.abc import Iterator
+import logging
+import os
+import re
 from typing import Any
 
+
+try:
+    from typing import Self
+except ImportError:
+    from typing_extensions import Self
+
 from crewai.tools import BaseTool
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_validator
 
 
 try:
@@ -12,6 +22,186 @@ try:
 except ImportError:
     SQLALCHEMY_AVAILABLE = False
 
+logger = logging.getLogger(__name__)
+
+# Commands allowed in read-only mode
+# NOTE: WITH is intentionally excluded — writable CTEs start with WITH, so the
+# CTE body must be inspected separately (see _validate_statement).
+_READ_ONLY_COMMANDS = {"SELECT", "SHOW", "DESCRIBE", "DESC", "EXPLAIN"}
+
+# Commands that mutate state and are blocked by default
+_WRITE_COMMANDS = {
+    "INSERT",
+    "UPDATE",
+    "DELETE",
+    "DROP",
+    "ALTER",
+    "CREATE",
+    "TRUNCATE",
+    "GRANT",
+    "REVOKE",
+    "EXEC",
+    "EXECUTE",
+    "CALL",
+    "MERGE",
+    "REPLACE",
+    "UPSERT",
+    "LOAD",
+    "COPY",
+    "VACUUM",
+    "ANALYZE",
+    "ANALYSE",
+    "REINDEX",
+    "CLUSTER",
+    "REFRESH",
+    "COMMENT",
+    "SET",
+    "RESET",
+}
+
+
+# Subset of write commands that can realistically appear *inside* a CTE body.
+# Narrower than _WRITE_COMMANDS to avoid false positives on identifiers like
+# ``comment``, ``set``, or ``reset`` which are common column/table names.
+_CTE_WRITE_INDICATORS = {
+    "INSERT",
+    "UPDATE",
+    "DELETE",
+    "DROP",
+    "ALTER",
+    "CREATE",
+    "TRUNCATE",
+    "MERGE",
+}
+
+
+_AS_PAREN_RE = re.compile(r"\bAS\s*\(", re.IGNORECASE)
+
+
+def _iter_as_paren_matches(stmt: str) -> Iterator[re.Match[str]]:
+    """Yield regex matches for ``AS\\s*(`` outside of string literals."""
+    # Build a set of character positions that are inside string literals.
+    in_string: set[int] = set()
+    i = 0
+    while i < len(stmt):
+        if stmt[i] == "'":
+            start = i
+            end = _skip_string_literal(stmt, i)
+            in_string.update(range(start, end))
+            i = end
+        else:
+            i += 1
+
+    for m in _AS_PAREN_RE.finditer(stmt):
+        if m.start() not in in_string:
+            yield m
+
+
+def _detect_writable_cte(stmt: str) -> str | None:
+    """Return the first write command inside a CTE body, or None.
+
+    Instead of tokenizing the whole statement (which falsely matches column
+    names like ``comment``), this walks through parenthesized CTE bodies and
+    checks only the *first keyword after* an opening ``AS (`` for a write
+    command.  Uses a regex to handle any whitespace (spaces, tabs, newlines)
+    between ``AS`` and ``(``.  Skips matches inside string literals.
+    """
+    for m in _iter_as_paren_matches(stmt):
+        body = stmt[m.end() :].lstrip()
+        first_word = body.split()[0].upper().strip("()") if body.split() else ""
+        if first_word in _CTE_WRITE_INDICATORS:
+            return first_word
+    return None
+
+
+def _skip_string_literal(stmt: str, pos: int) -> int:
+    """Skip past a string literal starting at pos (single-quoted).
+
+    Handles escaped quotes ('') inside the literal.
+    Returns the index after the closing quote.
+    """
+    quote_char = stmt[pos]
+    i = pos + 1
+    while i < len(stmt):
+        if stmt[i] == quote_char:
+            # Check for escaped quote ('')
+            if i + 1 < len(stmt) and stmt[i + 1] == quote_char:
+                i += 2
+                continue
+            return i + 1
+        i += 1
+    return i  # Unterminated literal — return end
+
+
+def _find_matching_close_paren(stmt: str, start: int) -> int:
+    """Find the matching close paren, skipping string literals."""
+    depth = 1
+    i = start
+    while i < len(stmt) and depth > 0:
+        ch = stmt[i]
+        if ch == "'":
+            i = _skip_string_literal(stmt, i)
+            continue
+        if ch == "(":
+            depth += 1
+        elif ch == ")":
+            depth -= 1
+        i += 1
+    return i
+
+
+def _extract_main_query_after_cte(stmt: str) -> str | None:
+    """Extract the main (outer) query that follows all CTE definitions.
+
+    For ``WITH cte AS (SELECT 1) DELETE FROM users``, returns ``DELETE FROM users``.
+    Returns None if no main query is found after the last CTE body.
+    Handles parentheses inside string literals (e.g., ``SELECT '(' FROM t``).
+    """
+    last_cte_end = 0
+    for m in _iter_as_paren_matches(stmt):
+        last_cte_end = _find_matching_close_paren(stmt, m.end())
+
+    if last_cte_end > 0:
+        remainder = stmt[last_cte_end:].strip().lstrip(",").strip()
+        if remainder:
+            return remainder
+    return None
+
+
+def _resolve_explain_command(stmt: str) -> str | None:
+    """Resolve the underlying command from an EXPLAIN [ANALYZE] [VERBOSE] statement.
+
+    Returns the real command (e.g., 'DELETE') if ANALYZE is present, else None.
+    Handles both space-separated and parenthesized syntax.
+    """
+    rest = stmt.strip()[len("EXPLAIN") :].strip()
+    if not rest:
+        return None
+
+    analyze_found = False
+    explain_opts = {"ANALYZE", "ANALYSE", "VERBOSE"}
+
+    if rest.startswith("("):
+        close = rest.find(")")
+        if close != -1:
+            options_str = rest[1:close].upper()
+            analyze_found = any(
+                opt.strip() in ("ANALYZE", "ANALYSE") for opt in options_str.split(",")
+            )
+            rest = rest[close + 1 :].strip()
+    else:
+        while rest:
+            first_opt = rest.split()[0].upper().rstrip(";") if rest.split() else ""
+            if first_opt in ("ANALYZE", "ANALYSE"):
+                analyze_found = True
+            if first_opt not in explain_opts:
+                break
+            rest = rest[len(first_opt) :].strip()
+
+    if analyze_found and rest:
+        return rest.split()[0].upper().rstrip(";")
+    return None
+
 
 class NL2SQLToolInput(BaseModel):
     sql_query: str = Field(
@@ -21,20 +211,70 @@ class NL2SQLToolInput(BaseModel):
 
 
 class NL2SQLTool(BaseTool):
+    """Tool that converts natural language to SQL and executes it against a database.
+
+    By default the tool operates in **read-only mode**: only SELECT, SHOW,
+    DESCRIBE, EXPLAIN, and read-only CTEs (WITH … SELECT) are permitted.  Write
+    operations (INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, TRUNCATE, …) are
+    blocked unless ``allow_dml=True`` is set explicitly or the environment
+    variable ``CREWAI_NL2SQL_ALLOW_DML=true`` is present.
+
+    Writable CTEs (``WITH d AS (DELETE …) SELECT …``) and
+    ``EXPLAIN ANALYZE <write-stmt>`` are treated as write operations and are
+    blocked in read-only mode.
+
+    The ``_fetch_all_available_columns`` helper uses parameterised queries so
+    that table names coming from the database catalogue cannot be used as an
+    injection vector.
+    """
+
     name: str = "NL2SQLTool"
-    description: str = "Converts natural language to SQL queries and executes them."
+    description: str = (
+        "Converts natural language to SQL queries and executes them against a "
+        "database. Read-only by default — only SELECT/SHOW/DESCRIBE/EXPLAIN "
+        "queries (and read-only CTEs) are allowed unless configured with "
+        "allow_dml=True."
+    )
     db_uri: str = Field(
         title="Database URI",
         description="The URI of the database to connect to.",
     )
+    allow_dml: bool = Field(
+        default=False,
+        title="Allow DML",
+        description=(
+            "When False (default) only read statements are permitted. "
+            "Set to True to allow INSERT/UPDATE/DELETE/DROP and other "
+            "write operations."
+        ),
+    )
     tables: list[dict[str, Any]] = Field(default_factory=list)
     columns: dict[str, list[dict[str, Any]] | str] = Field(default_factory=dict)
     args_schema: type[BaseModel] = NL2SQLToolInput
 
+    @model_validator(mode="after")
+    def _apply_env_override(self) -> Self:
+        """Allow CREWAI_NL2SQL_ALLOW_DML=true to override allow_dml at runtime."""
+        if os.environ.get("CREWAI_NL2SQL_ALLOW_DML", "").strip().lower() == "true":
+            if not self.allow_dml:
+                logger.warning(
+                    "NL2SQLTool: CREWAI_NL2SQL_ALLOW_DML env var is set — "
+                    "DML/DDL operations are enabled. Ensure this is intentional."
+                )
+            self.allow_dml = True
+        return self
+
     def model_post_init(self, __context: Any) -> None:
         if not SQLALCHEMY_AVAILABLE:
             raise ImportError(
-                "sqlalchemy is not installed. Please install it with `pip install crewai-tools[sqlalchemy]`"
+                "sqlalchemy is not installed. Please install it with "
+                "`pip install crewai-tools[sqlalchemy]`"
+            )
+
+        if self.allow_dml:
+            logger.warning(
+                "NL2SQLTool: allow_dml=True — write operations (INSERT/UPDATE/"
+                "DELETE/DROP/…) are permitted. Use with caution."
             )
 
         data: dict[str, list[dict[str, Any]] | str] = {}
@@ -50,42 +290,216 @@ class NL2SQLTool(BaseTool):
         self.tables = tables
         self.columns = data
 
+    # ------------------------------------------------------------------
+    # Query validation
+    # ------------------------------------------------------------------
+
+    def _validate_query(self, sql_query: str) -> None:
+        """Raise ValueError if *sql_query* is not permitted under the current config.
+
+        Splits the query on semicolons and validates each statement
+        independently.  When ``allow_dml=False`` (the default), multi-statement
+        queries are rejected outright to prevent ``SELECT 1; DROP TABLE users``
+        style bypasses.  When ``allow_dml=True`` every statement is checked and
+        a warning is emitted for write operations.
+        """
+        statements = [s.strip() for s in sql_query.split(";") if s.strip()]
+
+        if not statements:
+            raise ValueError("NL2SQLTool received an empty SQL query.")
+
+        if not self.allow_dml and len(statements) > 1:
+            raise ValueError(
+                "NL2SQLTool blocked a multi-statement query in read-only mode. "
+                "Semicolons are not permitted when allow_dml=False."
+            )
+
+        for stmt in statements:
+            self._validate_statement(stmt)
+
+    def _validate_statement(self, stmt: str) -> None:
+        """Validate a single SQL statement (no semicolons)."""
+        command = self._extract_command(stmt)
+
+        # EXPLAIN ANALYZE / EXPLAIN ANALYSE actually *executes* the underlying
+        # query.  Resolve the real command so write operations are caught.
+        # Handles both space-separated ("EXPLAIN ANALYZE DELETE …") and
+        # parenthesized ("EXPLAIN (ANALYZE) DELETE …", "EXPLAIN (ANALYZE, VERBOSE) DELETE …").
+        # EXPLAIN ANALYZE actually executes the underlying query — resolve the
+        # real command so write operations are caught.
+        if command == "EXPLAIN":
+            resolved = _resolve_explain_command(stmt)
+            if resolved:
+                command = resolved
+
+        # WITH starts a CTE.  Read-only CTEs are fine; writable CTEs
+        # (e.g. WITH d AS (DELETE …) SELECT …) must be blocked in read-only mode.
+        if command == "WITH":
+            # Check for write commands inside CTE bodies.
+            write_found = _detect_writable_cte(stmt)
+            if write_found:
+                found = write_found
+                if not self.allow_dml:
+                    raise ValueError(
+                        f"NL2SQLTool is configured in read-only mode and blocked a "
+                        f"writable CTE containing a '{found}' statement. To allow "
+                        f"write operations set allow_dml=True or "
+                        f"CREWAI_NL2SQL_ALLOW_DML=true."
+                    )
+                logger.warning(
+                    "NL2SQLTool: executing writable CTE with '%s' because allow_dml=True.",
+                    found,
+                )
+                return
+
+            # Check the main query after the CTE definitions.
+            main_query = _extract_main_query_after_cte(stmt)
+            if main_query:
+                main_cmd = main_query.split()[0].upper().rstrip(";")
+                if main_cmd in _WRITE_COMMANDS:
+                    if not self.allow_dml:
+                        raise ValueError(
+                            f"NL2SQLTool is configured in read-only mode and blocked a "
+                            f"'{main_cmd}' statement after a CTE. To allow write "
+                            f"operations set allow_dml=True or "
+                            f"CREWAI_NL2SQL_ALLOW_DML=true."
+                        )
+                    logger.warning(
+                        "NL2SQLTool: executing '%s' after CTE because allow_dml=True.",
+                        main_cmd,
+                    )
+                elif main_cmd not in _READ_ONLY_COMMANDS:
+                    if not self.allow_dml:
+                        raise ValueError(
+                            f"NL2SQLTool blocked an unrecognised SQL command '{main_cmd}' "
+                            f"after a CTE. Only {sorted(_READ_ONLY_COMMANDS)} are allowed "
+                            f"in read-only mode."
+                        )
+            return
+
+        if command in _WRITE_COMMANDS:
+            if not self.allow_dml:
+                raise ValueError(
+                    f"NL2SQLTool is configured in read-only mode and blocked a "
+                    f"'{command}' statement. To allow write operations set "
+                    f"allow_dml=True or CREWAI_NL2SQL_ALLOW_DML=true."
+                )
+            logger.warning(
+                "NL2SQLTool: executing write statement '%s' because allow_dml=True.",
+                command,
+            )
+        elif command not in _READ_ONLY_COMMANDS:
+            # Unknown command — block by default unless DML is explicitly enabled
+            if not self.allow_dml:
+                raise ValueError(
+                    f"NL2SQLTool blocked an unrecognised SQL command '{command}'. "
+                    f"Only {sorted(_READ_ONLY_COMMANDS)} are allowed in read-only "
+                    f"mode."
+                )
+
+    @staticmethod
+    def _extract_command(sql_query: str) -> str:
+        """Return the uppercased first keyword of *sql_query*."""
+        stripped = sql_query.strip().lstrip("(")
+        first_token = stripped.split()[0] if stripped.split() else ""
+        return first_token.upper().rstrip(";")
+
+    # ------------------------------------------------------------------
+    # Schema introspection helpers
+    # ------------------------------------------------------------------
+
     def _fetch_available_tables(self) -> list[dict[str, Any]] | str:
         return self.execute_sql(
-            "SELECT table_name FROM information_schema.tables WHERE table_schema = 'public';"
+            "SELECT table_name FROM information_schema.tables "
+            "WHERE table_schema = 'public';"
         )
 
     def _fetch_all_available_columns(
         self, table_name: str
     ) -> list[dict[str, Any]] | str:
+        """Fetch columns for *table_name* using a parameterised query.
+
+        The table name is bound via SQLAlchemy's ``:param`` syntax to prevent
+        SQL injection from catalogue values.
+        """
         return self.execute_sql(
-            f"SELECT column_name, data_type FROM information_schema.columns WHERE table_name = '{table_name}';"  # noqa: S608
+            "SELECT column_name, data_type FROM information_schema.columns "
+            "WHERE table_name = :table_name",
+            params={"table_name": table_name},
         )
 
+    # ------------------------------------------------------------------
+    # Core execution
+    # ------------------------------------------------------------------
+
     def _run(self, sql_query: str) -> list[dict[str, Any]] | str:
         try:
+            self._validate_query(sql_query)
             data = self.execute_sql(sql_query)
+        except ValueError:
+            raise
         except Exception as exc:
             data = (
                 f"Based on these tables {self.tables} and columns {self.columns}, "
-                "you can create SQL queries to retrieve data from the database."
-                f"Get the original request {sql_query} and the error {exc} and create the correct SQL query."
+                "you can create SQL queries to retrieve data from the database. "
+                f"Get the original request {sql_query} and the error {exc} and "
+                "create the correct SQL query."
             )
 
         return data
 
-    def execute_sql(self, sql_query: str) -> list[dict[str, Any]] | str:
+    def execute_sql(
+        self,
+        sql_query: str,
+        params: dict[str, Any] | None = None,
+    ) -> list[dict[str, Any]] | str:
+        """Execute *sql_query* and return the results as a list of dicts.
+
+        Parameters
+        ----------
+        sql_query:
+            The SQL statement to run.
+        params:
+            Optional mapping of bind parameters (e.g. ``{"table_name": "users"}``).
+        """
         if not SQLALCHEMY_AVAILABLE:
             raise ImportError(
-                "sqlalchemy is not installed. Please install it with `pip install crewai-tools[sqlalchemy]`"
+                "sqlalchemy is not installed. Please install it with "
+                "`pip install crewai-tools[sqlalchemy]`"
             )
 
+        # Check ALL statements so that e.g. "SELECT 1; DROP TABLE t" triggers a
+        # commit when allow_dml=True, regardless of statement order.
+        _stmts = [s.strip() for s in sql_query.split(";") if s.strip()]
+
+        def _is_write_stmt(s: str) -> bool:
+            cmd = self._extract_command(s)
+            if cmd in _WRITE_COMMANDS:
+                return True
+            if cmd == "EXPLAIN":
+                # Resolve the underlying command for EXPLAIN ANALYZE
+                resolved = _resolve_explain_command(s)
+                if resolved and resolved in _WRITE_COMMANDS:
+                    return True
+            if cmd == "WITH":
+                if _detect_writable_cte(s):
+                    return True
+                main_q = _extract_main_query_after_cte(s)
+                if main_q:
+                    return main_q.split()[0].upper().rstrip(";") in _WRITE_COMMANDS
+            return False
+
+        is_write = any(_is_write_stmt(s) for s in _stmts)
+
         engine = create_engine(self.db_uri)
         Session = sessionmaker(bind=engine)  # noqa: N806
         session = Session()
         try:
-            result = session.execute(text(sql_query))
-            session.commit()
+            result = session.execute(text(sql_query), params or {})
+
+            # Only commit when the operation actually mutates state
+            if self.allow_dml and is_write:
+                session.commit()
 
             if result.returns_rows:  # type: ignore[attr-defined]
                 columns = result.keys()

lib/crewai-tools/tests/tools/test_nl2sql_security.py

@@ -0,0 +1,671 @@
+"""Security tests for NL2SQLTool.
+
+Uses an in-memory SQLite database so no external service is needed.
+SQLite does not have information_schema, so we patch the schema-introspection
+helpers to avoid bootstrap failures and focus purely on the security logic.
+"""
+import os
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+# Skip the entire module if SQLAlchemy is not installed
+pytest.importorskip("sqlalchemy")
+
+from sqlalchemy import create_engine, text  # noqa: E402
+
+from crewai_tools.tools.nl2sql.nl2sql_tool import NL2SQLTool  # noqa: E402
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+SQLITE_URI = "sqlite://"  # in-memory
+
+
+def _make_tool(allow_dml: bool = False, **kwargs) -> NL2SQLTool:
+    """Return a NL2SQLTool wired to an in-memory SQLite DB.
+
+    Schema-introspection is patched out so we can create the tool without a
+    real PostgreSQL information_schema.
+    """
+    with (
+        patch.object(NL2SQLTool, "_fetch_available_tables", return_value=[]),
+        patch.object(NL2SQLTool, "_fetch_all_available_columns", return_value=[]),
+    ):
+        return NL2SQLTool(db_uri=SQLITE_URI, allow_dml=allow_dml, **kwargs)
+
+
+# ---------------------------------------------------------------------------
+# Read-only enforcement (allow_dml=False)
+# ---------------------------------------------------------------------------
+
+
+class TestReadOnlyMode:
+    def test_select_allowed_by_default(self):
+        tool = _make_tool()
+        # SQLite supports SELECT without information_schema
+        result = tool.execute_sql("SELECT 1 AS val")
+        assert result == [{"val": 1}]
+
+    @pytest.mark.parametrize(
+        "stmt",
+        [
+            "INSERT INTO t VALUES (1)",
+            "UPDATE t SET col = 1",
+            "DELETE FROM t",
+            "DROP TABLE t",
+            "ALTER TABLE t ADD col TEXT",
+            "CREATE TABLE t (id INTEGER)",
+            "TRUNCATE TABLE t",
+            "GRANT SELECT ON t TO user1",
+            "REVOKE SELECT ON t FROM user1",
+            "EXEC sp_something",
+            "EXECUTE sp_something",
+            "CALL proc()",
+        ],
+    )
+    def test_write_statements_blocked_by_default(self, stmt: str):
+        tool = _make_tool(allow_dml=False)
+        with pytest.raises(ValueError, match="read-only mode"):
+            tool._validate_query(stmt)
+
+    def test_explain_allowed(self):
+        tool = _make_tool()
+        # Should not raise
+        tool._validate_query("EXPLAIN SELECT 1")
+
+    def test_read_only_cte_allowed(self):
+        tool = _make_tool()
+        tool._validate_query("WITH cte AS (SELECT 1) SELECT * FROM cte")
+
+    def test_show_allowed(self):
+        tool = _make_tool()
+        tool._validate_query("SHOW TABLES")
+
+    def test_describe_allowed(self):
+        tool = _make_tool()
+        tool._validate_query("DESCRIBE users")
+
+
+# ---------------------------------------------------------------------------
+# DML enabled (allow_dml=True)
+# ---------------------------------------------------------------------------
+
+
+class TestDMLEnabled:
+    def test_insert_allowed_when_dml_enabled(self):
+        tool = _make_tool(allow_dml=True)
+        # Should not raise
+        tool._validate_query("INSERT INTO t VALUES (1)")
+
+    def test_delete_allowed_when_dml_enabled(self):
+        tool = _make_tool(allow_dml=True)
+        tool._validate_query("DELETE FROM t WHERE id = 1")
+
+    def test_drop_allowed_when_dml_enabled(self):
+        tool = _make_tool(allow_dml=True)
+        tool._validate_query("DROP TABLE t")
+
+    def test_dml_actually_persists(self):
+        """End-to-end: INSERT commits when allow_dml=True."""
+        # Use a file-based SQLite so we can verify persistence across sessions
+        import tempfile, os
+        with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
+            db_path = f.name
+        uri = f"sqlite:///{db_path}"
+        try:
+            tool = _make_tool(allow_dml=True)
+            tool.db_uri = uri
+
+            engine = create_engine(uri)
+            with engine.connect() as conn:
+                conn.execute(text("CREATE TABLE items (id INTEGER PRIMARY KEY)"))
+                conn.commit()
+
+            tool.execute_sql("INSERT INTO items VALUES (42)")
+
+            with engine.connect() as conn:
+                rows = conn.execute(text("SELECT id FROM items")).fetchall()
+            assert (42,) in rows
+        finally:
+            os.unlink(db_path)
+
+
+# ---------------------------------------------------------------------------
+# Parameterised query — SQL injection prevention
+# ---------------------------------------------------------------------------
+
+
+class TestParameterisedQueries:
+    def test_table_name_is_parameterised(self):
+        """_fetch_all_available_columns must not interpolate table_name into SQL."""
+        tool = _make_tool()
+        captured_calls = []
+
+        def recording_execute_sql(self_inner, sql_query, params=None):
+            captured_calls.append((sql_query, params))
+            return []
+
+        with patch.object(NL2SQLTool, "execute_sql", recording_execute_sql):
+            tool._fetch_all_available_columns("users'; DROP TABLE users; --")
+
+        assert len(captured_calls) == 1
+        sql, params = captured_calls[0]
+        # The raw SQL must NOT contain the injected string
+        assert "DROP" not in sql
+        # The table name must be passed as a parameter
+        assert params is not None
+        assert params.get("table_name") == "users'; DROP TABLE users; --"
+        # The SQL template must use the :param syntax
+        assert ":table_name" in sql
+
+    def test_injection_string_not_in_sql_template(self):
+        """The f-string vulnerability is gone — table name never lands in the SQL."""
+        tool = _make_tool()
+        injection = "'; DROP TABLE users; --"
+        captured = {}
+
+        def spy(self_inner, sql_query, params=None):
+            captured["sql"] = sql_query
+            captured["params"] = params
+            return []
+
+        with patch.object(NL2SQLTool, "execute_sql", spy):
+            tool._fetch_all_available_columns(injection)
+
+        assert injection not in captured["sql"]
+        assert captured["params"]["table_name"] == injection
+
+
+# ---------------------------------------------------------------------------
+# session.commit() not called for read-only queries
+# ---------------------------------------------------------------------------
+
+
+class TestNoCommitForReadOnly:
+    def test_select_does_not_commit(self):
+        tool = _make_tool(allow_dml=False)
+
+        mock_session = MagicMock()
+        mock_result = MagicMock()
+        mock_result.returns_rows = True
+        mock_result.keys.return_value = ["val"]
+        mock_result.fetchall.return_value = [(1,)]
+        mock_session.execute.return_value = mock_result
+
+        mock_session_cls = MagicMock(return_value=mock_session)
+
+        with (
+            patch("crewai_tools.tools.nl2sql.nl2sql_tool.create_engine"),
+            patch(
+                "crewai_tools.tools.nl2sql.nl2sql_tool.sessionmaker",
+                return_value=mock_session_cls,
+            ),
+        ):
+            tool.execute_sql("SELECT 1")
+
+        mock_session.commit.assert_not_called()
+
+    def test_write_with_dml_enabled_does_commit(self):
+        tool = _make_tool(allow_dml=True)
+
+        mock_session = MagicMock()
+        mock_result = MagicMock()
+        mock_result.returns_rows = False
+        mock_session.execute.return_value = mock_result
+
+        mock_session_cls = MagicMock(return_value=mock_session)
+
+        with (
+            patch("crewai_tools.tools.nl2sql.nl2sql_tool.create_engine"),
+            patch(
+                "crewai_tools.tools.nl2sql.nl2sql_tool.sessionmaker",
+                return_value=mock_session_cls,
+            ),
+        ):
+            tool.execute_sql("INSERT INTO t VALUES (1)")
+
+        mock_session.commit.assert_called_once()
+
+
+# ---------------------------------------------------------------------------
+# Environment-variable escape hatch
+# ---------------------------------------------------------------------------
+
+
+class TestEnvVarEscapeHatch:
+    def test_env_var_enables_dml(self):
+        with patch.dict(os.environ, {"CREWAI_NL2SQL_ALLOW_DML": "true"}):
+            tool = _make_tool(allow_dml=False)
+        assert tool.allow_dml is True
+
+    def test_env_var_case_insensitive(self):
+        with patch.dict(os.environ, {"CREWAI_NL2SQL_ALLOW_DML": "TRUE"}):
+            tool = _make_tool(allow_dml=False)
+        assert tool.allow_dml is True
+
+    def test_env_var_absent_keeps_default(self):
+        env = {k: v for k, v in os.environ.items() if k != "CREWAI_NL2SQL_ALLOW_DML"}
+        with patch.dict(os.environ, env, clear=True):
+            tool = _make_tool(allow_dml=False)
+        assert tool.allow_dml is False
+
+    def test_env_var_false_does_not_enable_dml(self):
+        with patch.dict(os.environ, {"CREWAI_NL2SQL_ALLOW_DML": "false"}):
+            tool = _make_tool(allow_dml=False)
+        assert tool.allow_dml is False
+
+    def test_dml_write_blocked_without_env_var(self):
+        env = {k: v for k, v in os.environ.items() if k != "CREWAI_NL2SQL_ALLOW_DML"}
+        with patch.dict(os.environ, env, clear=True):
+            tool = _make_tool(allow_dml=False)
+        with pytest.raises(ValueError, match="read-only mode"):
+            tool._validate_query("DROP TABLE sensitive_data")
+
+
+# ---------------------------------------------------------------------------
+# _run() propagates ValueError from _validate_query
+# ---------------------------------------------------------------------------
+
+
+class TestRunValidation:
+    def test_run_raises_on_blocked_query(self):
+        tool = _make_tool(allow_dml=False)
+        with pytest.raises(ValueError, match="read-only mode"):
+            tool._run("DELETE FROM users")
+
+    def test_run_returns_results_for_select(self):
+        tool = _make_tool(allow_dml=False)
+        result = tool._run("SELECT 1 AS n")
+        assert result == [{"n": 1}]
+
+
+# ---------------------------------------------------------------------------
+# Multi-statement / semicolon injection prevention
+# ---------------------------------------------------------------------------
+
+
+class TestSemicolonInjection:
+    def test_multi_statement_blocked_in_read_only_mode(self):
+        """SELECT 1; DROP TABLE users must be rejected when allow_dml=False."""
+        tool = _make_tool(allow_dml=False)
+        with pytest.raises(ValueError, match="multi-statement"):
+            tool._validate_query("SELECT 1; DROP TABLE users")
+
+    def test_multi_statement_blocked_even_with_only_selects(self):
+        """Two SELECT statements are still rejected in read-only mode."""
+        tool = _make_tool(allow_dml=False)
+        with pytest.raises(ValueError, match="multi-statement"):
+            tool._validate_query("SELECT 1; SELECT 2")
+
+    def test_trailing_semicolon_allowed_single_statement(self):
+        """A single statement with a trailing semicolon should pass."""
+        tool = _make_tool(allow_dml=False)
+        # Should not raise — the part after the semicolon is empty
+        tool._validate_query("SELECT 1;")
+
+    def test_multi_statement_allowed_when_dml_enabled(self):
+        """Multiple statements are permitted when allow_dml=True."""
+        tool = _make_tool(allow_dml=True)
+        # Should not raise
+        tool._validate_query("SELECT 1; INSERT INTO t VALUES (1)")
+
+    def test_multi_statement_write_still_blocked_individually(self):
+        """Even with allow_dml=False, a single write statement is blocked."""
+        tool = _make_tool(allow_dml=False)
+        with pytest.raises(ValueError, match="read-only mode"):
+            tool._validate_query("DROP TABLE users")
+
+
+# ---------------------------------------------------------------------------
+# Writable CTEs (WITH … DELETE/INSERT/UPDATE)
+# ---------------------------------------------------------------------------
+
+
+class TestWritableCTE:
+    def test_writable_cte_delete_blocked_in_read_only(self):
+        """WITH d AS (DELETE FROM users RETURNING *) SELECT * FROM d — blocked."""
+        tool = _make_tool(allow_dml=False)
+        with pytest.raises(ValueError, match="read-only mode"):
+            tool._validate_query(
+                "WITH deleted AS (DELETE FROM users RETURNING *) SELECT * FROM deleted"
+            )
+
+    def test_writable_cte_insert_blocked_in_read_only(self):
+        tool = _make_tool(allow_dml=False)
+        with pytest.raises(ValueError, match="read-only mode"):
+            tool._validate_query(
+                "WITH ins AS (INSERT INTO t VALUES (1) RETURNING id) SELECT * FROM ins"
+            )
+
+    def test_writable_cte_update_blocked_in_read_only(self):
+        tool = _make_tool(allow_dml=False)
+        with pytest.raises(ValueError, match="read-only mode"):
+            tool._validate_query(
+                "WITH upd AS (UPDATE t SET x=1 RETURNING id) SELECT * FROM upd"
+            )
+
+    def test_writable_cte_allowed_when_dml_enabled(self):
+        tool = _make_tool(allow_dml=True)
+        # Should not raise
+        tool._validate_query(
+            "WITH deleted AS (DELETE FROM users RETURNING *) SELECT * FROM deleted"
+        )
+
+    def test_plain_read_only_cte_still_allowed(self):
+        tool = _make_tool(allow_dml=False)
+        # No write commands in the CTE body — must pass
+        tool._validate_query("WITH cte AS (SELECT id FROM users) SELECT * FROM cte")
+
+    def test_cte_with_comment_column_not_false_positive(self):
+        """Column named 'comment' should NOT trigger writable CTE detection."""
+        tool = _make_tool(allow_dml=False)
+        # 'comment' is a column name, not a SQL command
+        tool._validate_query(
+            "WITH cte AS (SELECT comment FROM posts) SELECT * FROM cte"
+        )
+
+    def test_cte_with_set_column_not_false_positive(self):
+        """Column named 'set' should NOT trigger writable CTE detection."""
+        tool = _make_tool(allow_dml=False)
+        tool._validate_query(
+            "WITH cte AS (SELECT set, reset FROM config) SELECT * FROM cte"
+        )
+
+
+# ---------------------------------------------------------------------------
+# EXPLAIN ANALYZE executes the underlying query
+# ---------------------------------------------------------------------------
+
+
+    def test_cte_with_write_main_query_blocked(self):
+        """WITH cte AS (SELECT 1) DELETE FROM users — main query must be caught."""
+        tool = _make_tool(allow_dml=False)
+        with pytest.raises(ValueError, match="read-only mode"):
+            tool._validate_query(
+                "WITH cte AS (SELECT 1) DELETE FROM users"
+            )
+
+    def test_cte_with_write_main_query_allowed_with_dml(self):
+        """Main query write after CTE should pass when allow_dml=True."""
+        tool = _make_tool(allow_dml=True)
+        tool._validate_query(
+            "WITH cte AS (SELECT id FROM users) INSERT INTO archive SELECT * FROM cte"
+        )
+
+    def test_cte_with_newline_before_paren_blocked(self):
+        """AS followed by newline then ( should still detect writable CTE."""
+        tool = _make_tool(allow_dml=False)
+        with pytest.raises(ValueError, match="read-only mode"):
+            tool._validate_query(
+                "WITH cte AS\n(DELETE FROM users RETURNING *) SELECT * FROM cte"
+            )
+
+    def test_cte_with_tab_before_paren_blocked(self):
+        """AS followed by tab then ( should still detect writable CTE."""
+        tool = _make_tool(allow_dml=False)
+        with pytest.raises(ValueError, match="read-only mode"):
+            tool._validate_query(
+                "WITH cte AS\t(DELETE FROM users RETURNING *) SELECT * FROM cte"
+            )
+
+
+class TestExplainAnalyze:
+    def test_explain_analyze_delete_blocked_in_read_only(self):
+        """EXPLAIN ANALYZE DELETE actually runs the delete — block it."""
+        tool = _make_tool(allow_dml=False)
+        with pytest.raises(ValueError, match="read-only mode"):
+            tool._validate_query("EXPLAIN ANALYZE DELETE FROM users")
+
+    def test_explain_analyse_delete_blocked_in_read_only(self):
+        """British spelling ANALYSE is also caught."""
+        tool = _make_tool(allow_dml=False)
+        with pytest.raises(ValueError, match="read-only mode"):
+            tool._validate_query("EXPLAIN ANALYSE DELETE FROM users")
+
+    def test_explain_analyze_drop_blocked_in_read_only(self):
+        tool = _make_tool(allow_dml=False)
+        with pytest.raises(ValueError, match="read-only mode"):
+            tool._validate_query("EXPLAIN ANALYZE DROP TABLE users")
+
+    def test_explain_analyze_select_allowed_in_read_only(self):
+        """EXPLAIN ANALYZE on a SELECT is safe — must be permitted."""
+        tool = _make_tool(allow_dml=False)
+        tool._validate_query("EXPLAIN ANALYZE SELECT * FROM users")
+
+    def test_explain_without_analyze_allowed(self):
+        tool = _make_tool(allow_dml=False)
+        tool._validate_query("EXPLAIN SELECT * FROM users")
+
+    def test_explain_analyze_delete_allowed_when_dml_enabled(self):
+        tool = _make_tool(allow_dml=True)
+        tool._validate_query("EXPLAIN ANALYZE DELETE FROM users")
+
+    def test_explain_paren_analyze_delete_blocked_in_read_only(self):
+        """EXPLAIN (ANALYZE) DELETE actually runs the delete — block it."""
+        tool = _make_tool(allow_dml=False)
+        with pytest.raises(ValueError, match="read-only mode"):
+            tool._validate_query("EXPLAIN (ANALYZE) DELETE FROM users")
+
+    def test_explain_paren_analyze_verbose_delete_blocked_in_read_only(self):
+        """EXPLAIN (ANALYZE, VERBOSE) DELETE actually runs the delete — block it."""
+        tool = _make_tool(allow_dml=False)
+        with pytest.raises(ValueError, match="read-only mode"):
+            tool._validate_query("EXPLAIN (ANALYZE, VERBOSE) DELETE FROM users")
+
+    def test_explain_paren_verbose_select_allowed_in_read_only(self):
+        """EXPLAIN (VERBOSE) SELECT is safe — no ANALYZE means no execution."""
+        tool = _make_tool(allow_dml=False)
+        tool._validate_query("EXPLAIN (VERBOSE) SELECT * FROM users")
+
+
+# ---------------------------------------------------------------------------
+# Multi-statement commit covers ALL statements (not just the first)
+# ---------------------------------------------------------------------------
+
+
+class TestMultiStatementCommit:
+    def test_select_then_insert_triggers_commit(self):
+        """SELECT 1; INSERT … — commit must happen because INSERT is a write."""
+        tool = _make_tool(allow_dml=True)
+
+        mock_session = MagicMock()
+        mock_result = MagicMock()
+        mock_result.returns_rows = False
+        mock_session.execute.return_value = mock_result
+        mock_session_cls = MagicMock(return_value=mock_session)
+
+        with (
+            patch("crewai_tools.tools.nl2sql.nl2sql_tool.create_engine"),
+            patch(
+                "crewai_tools.tools.nl2sql.nl2sql_tool.sessionmaker",
+                return_value=mock_session_cls,
+            ),
+        ):
+            tool.execute_sql("SELECT 1; INSERT INTO t VALUES (1)")
+
+        mock_session.commit.assert_called_once()
+
+    def test_select_only_multi_statement_does_not_commit(self):
+        """Two SELECTs must not trigger a commit even when allow_dml=True."""
+        tool = _make_tool(allow_dml=True)
+
+        mock_session = MagicMock()
+        mock_result = MagicMock()
+        mock_result.returns_rows = True
+        mock_result.keys.return_value = ["v"]
+        mock_result.fetchall.return_value = [(1,)]
+        mock_session.execute.return_value = mock_result
+        mock_session_cls = MagicMock(return_value=mock_session)
+
+        with (
+            patch("crewai_tools.tools.nl2sql.nl2sql_tool.create_engine"),
+            patch(
+                "crewai_tools.tools.nl2sql.nl2sql_tool.sessionmaker",
+                return_value=mock_session_cls,
+            ),
+        ):
+            tool.execute_sql("SELECT 1; SELECT 2")
+
+    def test_writable_cte_triggers_commit(self):
+        """WITH d AS (DELETE ...) must trigger commit when allow_dml=True."""
+        tool = _make_tool(allow_dml=True)
+
+        mock_session = MagicMock()
+        mock_result = MagicMock()
+        mock_result.returns_rows = True
+        mock_result.keys.return_value = ["id"]
+        mock_result.fetchall.return_value = [(1,)]
+        mock_session.execute.return_value = mock_result
+        mock_session_cls = MagicMock(return_value=mock_session)
+
+        with (
+            patch("crewai_tools.tools.nl2sql.nl2sql_tool.create_engine"),
+            patch(
+                "crewai_tools.tools.nl2sql.nl2sql_tool.sessionmaker",
+                return_value=mock_session_cls,
+            ),
+        ):
+            tool.execute_sql(
+                "WITH d AS (DELETE FROM users RETURNING *) SELECT * FROM d"
+            )
+            mock_session.commit.assert_called_once()
+
+
+# ---------------------------------------------------------------------------
+# Extended _WRITE_COMMANDS coverage
+# ---------------------------------------------------------------------------
+
+
+class TestExtendedWriteCommands:
+    @pytest.mark.parametrize(
+        "stmt",
+        [
+            "UPSERT INTO t VALUES (1)",
+            "LOAD DATA INFILE 'f.csv' INTO TABLE t",
+            "COPY t FROM '/tmp/f.csv'",
+            "VACUUM ANALYZE t",
+            "ANALYZE t",
+            "ANALYSE t",
+            "REINDEX TABLE t",
+            "CLUSTER t USING idx",
+            "REFRESH MATERIALIZED VIEW v",
+            "COMMENT ON TABLE t IS 'desc'",
+            "SET search_path = myschema",
+            "RESET search_path",
+        ],
+    )
+    def test_extended_write_commands_blocked_by_default(self, stmt: str):
+        tool = _make_tool(allow_dml=False)
+        with pytest.raises(ValueError, match="read-only mode"):
+            tool._validate_query(stmt)
+
+
+# ---------------------------------------------------------------------------
+# EXPLAIN ANALYZE VERBOSE handling
+# ---------------------------------------------------------------------------
+
+
+class TestExplainAnalyzeVerbose:
+    def test_explain_analyze_verbose_select_allowed(self):
+        """EXPLAIN ANALYZE VERBOSE SELECT should be allowed (read-only)."""
+        tool = _make_tool(allow_dml=False)
+        tool._validate_query("EXPLAIN ANALYZE VERBOSE SELECT * FROM users")
+
+    def test_explain_analyze_verbose_delete_blocked(self):
+        """EXPLAIN ANALYZE VERBOSE DELETE should be blocked."""
+        tool = _make_tool(allow_dml=False)
+        with pytest.raises(ValueError, match="read-only mode"):
+            tool._validate_query("EXPLAIN ANALYZE VERBOSE DELETE FROM users")
+
+    def test_explain_verbose_select_allowed(self):
+        """EXPLAIN VERBOSE SELECT (no ANALYZE) should be allowed."""
+        tool = _make_tool(allow_dml=False)
+        tool._validate_query("EXPLAIN VERBOSE SELECT * FROM users")
+
+
+# ---------------------------------------------------------------------------
+# CTE with string literal parens
+# ---------------------------------------------------------------------------
+
+
+class TestCTEStringLiteralParens:
+    def test_cte_string_paren_does_not_bypass(self):
+        """Parens inside string literals should not confuse the paren walker."""
+        tool = _make_tool(allow_dml=False)
+        with pytest.raises(ValueError, match="read-only mode"):
+            tool._validate_query(
+                "WITH cte AS (SELECT '(' FROM t) DELETE FROM users"
+            )
+
+    def test_cte_string_paren_read_only_allowed(self):
+        """Read-only CTE with string literal parens should be allowed."""
+        tool = _make_tool(allow_dml=False)
+        tool._validate_query(
+            "WITH cte AS (SELECT '(' FROM t) SELECT * FROM cte"
+        )
+
+
+# ---------------------------------------------------------------------------
+# EXPLAIN ANALYZE commit logic
+# ---------------------------------------------------------------------------
+
+
+class TestExplainAnalyzeCommit:
+    def test_explain_analyze_delete_triggers_commit(self):
+        """EXPLAIN ANALYZE DELETE should trigger commit when allow_dml=True."""
+        tool = _make_tool(allow_dml=True)
+
+        mock_session = MagicMock()
+        mock_result = MagicMock()
+        mock_result.returns_rows = True
+        mock_result.keys.return_value = ["QUERY PLAN"]
+        mock_result.fetchall.return_value = [("Delete on users",)]
+        mock_session.execute.return_value = mock_result
+        mock_session_cls = MagicMock(return_value=mock_session)
+
+        with (
+            patch("crewai_tools.tools.nl2sql.nl2sql_tool.create_engine"),
+            patch(
+                "crewai_tools.tools.nl2sql.nl2sql_tool.sessionmaker",
+                return_value=mock_session_cls,
+            ),
+        ):
+            tool.execute_sql("EXPLAIN ANALYZE DELETE FROM users")
+            mock_session.commit.assert_called_once()
+
+
+# ---------------------------------------------------------------------------
+# AS( inside string literals must not confuse CTE detection
+# ---------------------------------------------------------------------------
+
+
+class TestCTEStringLiteralAS:
+    def test_as_paren_inside_string_does_not_bypass(self):
+        """'AS (' inside a string literal must not be treated as a CTE body."""
+        tool = _make_tool(allow_dml=False)
+        with pytest.raises(ValueError, match="read-only mode"):
+            tool._validate_query(
+                "WITH cte AS (SELECT 'AS (' FROM t) DELETE FROM users"
+            )
+
+    def test_as_paren_inside_string_read_only_ok(self):
+        """Read-only CTE with 'AS (' in a string should be allowed."""
+        tool = _make_tool(allow_dml=False)
+        tool._validate_query(
+            "WITH cte AS (SELECT 'AS (' FROM t) SELECT * FROM cte"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Unknown command after CTE should be blocked
+# ---------------------------------------------------------------------------
+
+
+class TestCTEUnknownCommand:
+    def test_unknown_command_after_cte_blocked(self):
+        """WITH cte AS (SELECT 1) FOOBAR should be blocked as unknown."""
+        tool = _make_tool(allow_dml=False)
+        with pytest.raises(ValueError, match="unrecognised"):
+            tool._validate_query("WITH cte AS (SELECT 1) FOOBAR")

lib/crewai-tools/tool.specs.json

@@ -14051,7 +14051,7 @@
       }
     },
     {
-      "description": "Converts natural language to SQL queries and executes them.",
+      "description": "Converts natural language to SQL queries and executes them against a database. Read-only by default \u2014 only SELECT/SHOW/DESCRIBE/EXPLAIN queries (and read-only CTEs) are allowed unless configured with allow_dml=True.",
       "env_vars": [],
       "humanized_name": "NL2SQLTool",
       "init_params_schema": {
@@ -14092,7 +14092,14 @@
             "type": "object"
           }
         },
+        "description": "Tool that converts natural language to SQL and executes it against a database.\n\nBy default the tool operates in **read-only mode**: only SELECT, SHOW,\nDESCRIBE, EXPLAIN, and read-only CTEs (WITH \u2026 SELECT) are permitted.  Write\noperations (INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, TRUNCATE, \u2026) are\nblocked unless ``allow_dml=True`` is set explicitly or the environment\nvariable ``CREWAI_NL2SQL_ALLOW_DML=true`` is present.\n\nWritable CTEs (``WITH d AS (DELETE \u2026) SELECT \u2026``) and\n``EXPLAIN ANALYZE <write-stmt>`` are treated as write operations and are\nblocked in read-only mode.\n\nThe ``_fetch_all_available_columns`` helper uses parameterised queries so\nthat table names coming from the database catalogue cannot be used as an\ninjection vector.",
         "properties": {
+          "allow_dml": {
+            "default": false,
+            "description": "When False (default) only read statements are permitted. Set to True to allow INSERT/UPDATE/DELETE/DROP and other write operations.",
+            "title": "Allow DML",
+            "type": "boolean"
+          },
           "columns": {
             "additionalProperties": {
               "anyOf": [

lib/crewai/pyproject.toml

@@ -10,7 +10,7 @@ requires-python = ">=3.10, <3.14"
 dependencies = [
     # Core Dependencies
     "pydantic~=2.11.9",
-    "openai>=1.83.0,<3",
+    "openai>=2.0.0,<3",
     "instructor>=1.3.3",
     # Text Processing
     "pdfplumber~=0.11.4",
@@ -40,7 +40,7 @@ dependencies = [
     "pydantic-settings~=2.10.1",
     "httpx~=0.28.1",
     "mcp~=1.26.0",
-    "uv~=0.9.13",
+    "uv~=0.11.6",
     "aiosqlite~=0.21.0",
     "pyyaml~=6.0",
     "aiofiles~=24.1.0",
@@ -55,7 +55,7 @@ Repository = "https://github.com/crewAIInc/crewAI"
 
 [project.optional-dependencies]
 tools = [
-    "crewai-tools==1.14.2a1",
+    "crewai-tools==1.14.2a4",
 ]
 embeddings = [
     "tiktoken~=0.8.0"
@@ -74,8 +74,8 @@ qdrant = [
     "qdrant-client[fastembed]~=1.14.3",
 ]
 aws = [
-    "boto3~=1.40.38",
-    "aiobotocore~=2.25.2",
+    "boto3~=1.42.79",
+    "aiobotocore~=3.4.0",
 ]
 watson = [
     "ibm-watsonx-ai~=1.3.39",
@@ -87,7 +87,7 @@ litellm = [
     "litellm~=1.83.0",
 ]
 bedrock = [
-    "boto3~=1.40.45",
+    "boto3~=1.42.79",
 ]
 google-genai = [
     "google-genai~=1.65.0",

lib/crewai/src/crewai/__init__.py

@@ -46,7 +46,7 @@ def _suppress_pydantic_deprecation_warnings() -> None:
 
 _suppress_pydantic_deprecation_warnings()
 
-__version__ = "1.14.2a1"
+__version__ = "1.14.2a4"
 _telemetry_submitted = False
 
 

lib/crewai/src/crewai/a2a/errors.py

@@ -98,7 +98,6 @@ class A2AErrorCode(IntEnum):
     """The specified artifact was not found."""
 
 
-# Error code to default message mapping
 ERROR_MESSAGES: dict[int, str] = {
     A2AErrorCode.JSON_PARSE_ERROR: "Parse error",
     A2AErrorCode.INVALID_REQUEST: "Invalid Request",

lib/crewai/src/crewai/a2a/extensions/base.py

@@ -63,25 +63,21 @@ class A2AExtension(Protocol):
     Example:
         class MyExtension:
             def inject_tools(self, agent: Agent) -> None:
-                # Add custom tools to the agent
                 pass
 
             def extract_state_from_history(
                 self, conversation_history: Sequence[Message]
             ) -> ConversationState | None:
-                # Extract state from conversation
                 return None
 
             def augment_prompt(
                 self, base_prompt: str, conversation_state: ConversationState | None
             ) -> str:
-                # Add custom instructions
                 return base_prompt
 
             def process_response(
                 self, agent_response: Any, conversation_state: ConversationState | None
             ) -> Any:
-                # Modify response if needed
                 return agent_response
     """
 

lib/crewai/src/crewai/a2a/utils/response_model.py

@@ -77,7 +77,6 @@ def extract_a2a_agent_ids_from_config(
     else:
         configs = a2a_config
 
-    # Filter to only client configs (those with endpoint)
     client_configs: list[A2AClientConfigTypes] = [
         config for config in configs if isinstance(config, (A2AConfig, A2AClientConfig))
     ]

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

@@ -1341,7 +1341,6 @@ class Agent(BaseAgent):
 
         raw_tools: list[BaseTool] = self.tools or []
 
-        # Inject memory tools for standalone kickoff (crew path handles its own)
         agent_memory = getattr(self, "memory", None)
         if agent_memory is not None:
             from crewai.tools.memory_tools import create_memory_tools
@@ -1399,7 +1398,6 @@ class Agent(BaseAgent):
         if input_files:
             all_files.update(input_files)
 
-        # Inject memory context for standalone kickoff (recall before execution)
         if agent_memory is not None:
             try:
                 crewai_event_bus.emit(
@@ -1485,8 +1483,6 @@ class Agent(BaseAgent):
         Note:
             For explicit async usage outside of Flow, use kickoff_async() directly.
         """
-        # Magic auto-async: if inside event loop (e.g., inside a Flow),
-        # return coroutine for Flow to await
         if is_inside_event_loop():
             return self.kickoff_async(messages, response_format, input_files)
 
@@ -1637,7 +1633,7 @@ class Agent(BaseAgent):
                 if isinstance(conversion_result, BaseModel):
                     formatted_result = conversion_result
             except ConverterError:
-                pass  # Keep raw output if conversion fails
+                pass
         else:
             raw_output = str(output) if not isinstance(output, str) else output
 
@@ -1719,7 +1715,6 @@ class Agent(BaseAgent):
         elif callable(self.guardrail):
             guardrail_callable = self.guardrail
         else:
-            # Should not happen if called from kickoff with guardrail check
             return output
 
         guardrail_result = process_guardrail(

lib/crewai/src/crewai/agent/planning_config.py

@@ -41,7 +41,6 @@ class PlanningConfig(BaseModel):
         from crewai import Agent
         from crewai.agent.planning_config import PlanningConfig
 
-        # Simple usage — fast, linear execution (default)
         agent = Agent(
             role="Researcher",
             goal="Research topics",
@@ -49,7 +48,6 @@ class PlanningConfig(BaseModel):
             planning_config=PlanningConfig(),
         )
 
-        # Balanced — replan only when steps fail
         agent = Agent(
             role="Researcher",
             goal="Research topics",
@@ -59,7 +57,6 @@ class PlanningConfig(BaseModel):
             ),
         )
 
-        # Full adaptive planning with refinement and replanning
         agent = Agent(
             role="Researcher",
             goal="Research topics",
@@ -69,7 +66,7 @@ class PlanningConfig(BaseModel):
                 max_attempts=3,
                 max_steps=10,
                 plan_prompt="Create a focused plan for: {description}",
-                llm="gpt-4o-mini",  # Use cheaper model for planning
+                llm="gpt-4o-mini",
             ),
         )
         ```

lib/crewai/src/crewai/agent/utils.py

@@ -39,7 +39,6 @@ def handle_reasoning(agent: Agent, task: Task) -> None:
         agent: The agent performing the task.
         task: The task to execute.
     """
-    # Check if planning is enabled using the planning_enabled property
     if not getattr(agent, "planning_enabled", False):
         return
 

lib/crewai/src/crewai/agents/agent_adapters/openai_agents/openai_agent_tool_adapter.py

@@ -99,12 +99,10 @@ class OpenAIAgentToolAdapter(BaseToolAdapter):
                 Returns:
                     Tool execution result.
                 """
-                # Get the parameter name from the schema
                 param_name: str = next(
                     iter(tool.args_schema.model_json_schema()["properties"].keys())
                 )
 
-                # Handle different argument types
                 args_dict: dict[str, Any]
                 if isinstance(arguments, dict):
                     args_dict = arguments
@@ -116,16 +114,13 @@ class OpenAIAgentToolAdapter(BaseToolAdapter):
                 else:
                     args_dict = {param_name: str(arguments)}
 
-                # Run the tool with the processed arguments
                 output: Any | Awaitable[Any] = tool._run(**args_dict)
 
-                # Await if the tool returned a coroutine
                 if inspect.isawaitable(output):
                     result: Any = await output
                 else:
                     result = output
 
-                # Ensure the result is JSON serializable
                 if isinstance(result, (dict, list, str, int, float, bool, type(None))):
                     return result
                 return str(result)

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

@@ -51,7 +51,6 @@ from crewai.utilities.string_utils import interpolate_only
 if TYPE_CHECKING:
     from crewai.context import ExecutionContext
     from crewai.crew import Crew
-    from crewai.state.provider.core import BaseProvider
 
 
 def _validate_crew_ref(value: Any) -> Any:
@@ -338,19 +337,16 @@ class BaseAgent(BaseModel, ABC, metaclass=AgentMeta):
     execution_context: ExecutionContext | None = Field(default=None)
 
     @classmethod
-    def from_checkpoint(
-        cls, path: str, *, provider: BaseProvider | None = None
-    ) -> Self:
-        """Restore an Agent from a checkpoint file."""
+    def from_checkpoint(cls, config: CheckpointConfig) -> Self:
+        """Restore an Agent from a checkpoint.
+
+        Args:
+            config: Checkpoint configuration with ``restore_from`` set.
+        """
         from crewai.context import apply_execution_context
-        from crewai.state.provider.json_provider import JsonProvider
         from crewai.state.runtime import RuntimeState
 
-        state = RuntimeState.from_checkpoint(
-            path,
-            provider=provider or JsonProvider(),
-            context={"from_checkpoint": True},
-        )
+        state = RuntimeState.from_checkpoint(config, context={"from_checkpoint": True})
         for entity in state.root:
             if isinstance(entity, cls):
                 if entity.execution_context is not None:
@@ -359,7 +355,9 @@ class BaseAgent(BaseModel, ABC, metaclass=AgentMeta):
                     entity.agent_executor.agent = entity
                     entity.agent_executor._resuming = True
                 return entity
-        raise ValueError(f"No {cls.__name__} found in checkpoint: {path}")
+        raise ValueError(
+            f"No {cls.__name__} found in checkpoint: {config.restore_from}"
+        )
 
     @model_validator(mode="before")
     @classmethod
@@ -385,7 +383,6 @@ class BaseAgent(BaseModel, ABC, metaclass=AgentMeta):
             if isinstance(tool, BaseTool):
                 processed_tools.append(tool)
             elif all(hasattr(tool, attr) for attr in required_attrs):
-                # Tool has the required attributes, create a Tool instance
                 processed_tools.append(Tool.from_langchain(tool))
             else:
                 raise ValueError(
@@ -450,14 +447,12 @@ class BaseAgent(BaseModel, ABC, metaclass=AgentMeta):
 
     @model_validator(mode="after")
     def validate_and_set_attributes(self) -> Self:
-        # Validate required fields
         for field in ["role", "goal", "backstory"]:
             if getattr(self, field) is None:
                 raise ValueError(
                     f"{field} must be provided either directly or through config"
                 )
 
-        # Set private attributes
         self._logger = Logger(verbose=self.verbose)
         if self.max_rpm and not self._rpm_controller:
             self._rpm_controller = RPMController(
@@ -466,7 +461,6 @@ class BaseAgent(BaseModel, ABC, metaclass=AgentMeta):
         if not self._token_process:
             self._token_process = TokenProcess()
 
-        # Initialize security_config if not provided
         if self.security_config is None:
             self.security_config = SecurityConfig()
 
@@ -568,14 +562,11 @@ class BaseAgent(BaseModel, ABC, metaclass=AgentMeta):
             "actions",
         }
 
-        # Copy llm
         existing_llm = shallow_copy(self.llm)
         copied_knowledge = shallow_copy(self.knowledge)
         copied_knowledge_storage = shallow_copy(self.knowledge_storage)
-        # Properly copy knowledge sources if they exist
         existing_knowledge_sources = None
         if self.knowledge_sources:
-            # Create a shared storage instance for all knowledge sources
             shared_storage = (
                 self.knowledge_sources[0].storage if self.knowledge_sources else None
             )
@@ -587,7 +578,6 @@ class BaseAgent(BaseModel, ABC, metaclass=AgentMeta):
                     if hasattr(source, "model_copy")
                     else shallow_copy(source)
                 )
-                # Ensure all copied sources use the same storage instance
                 copied_source.storage = shared_storage
                 existing_knowledge_sources.append(copied_source)
 

lib/crewai/src/crewai/agents/constants.py

@@ -4,8 +4,6 @@ import re
 from typing import Final
 
 
-# crewai.agents.parser constants
-
 FINAL_ANSWER_ACTION: Final[str] = "Final Answer:"
 MISSING_ACTION_AFTER_THOUGHT_ERROR_MESSAGE: Final[str] = (
     "I did it wrong. Invalid Format: I missed the 'Action:' after 'Thought:'. I will do right next, and don't use a tool I have already used.\n"

lib/crewai/src/crewai/agents/crew_agent_executor.py

@@ -296,7 +296,6 @@ class CrewAgentExecutor(BaseAgentExecutor):
         Returns:
             Final answer from the agent.
         """
-        # Check if model supports native function calling
         use_native_tools = (
             hasattr(self.llm, "supports_function_calling")
             and callable(getattr(self.llm, "supports_function_calling", None))
@@ -307,7 +306,6 @@ class CrewAgentExecutor(BaseAgentExecutor):
         if use_native_tools:
             return self._invoke_loop_native_tools()
 
-        # Fall back to ReAct text-based pattern
         return self._invoke_loop_react()
 
     def _invoke_loop_react(self) -> AgentFinish:
@@ -347,7 +345,6 @@ class CrewAgentExecutor(BaseAgentExecutor):
                     executor_context=self,
                     verbose=self.agent.verbose,
                 )
-                # breakpoint()
                 if self.response_model is not None:
                     try:
                         if isinstance(answer, BaseModel):
@@ -365,7 +362,6 @@ class CrewAgentExecutor(BaseAgentExecutor):
                                 text=answer,
                             )
                     except ValidationError:
-                        # If validation fails, convert BaseModel to JSON string for parsing
                         answer_str = (
                             answer.model_dump_json()
                             if isinstance(answer, BaseModel)
@@ -375,14 +371,12 @@ class CrewAgentExecutor(BaseAgentExecutor):
                             answer_str, self.use_stop_words
                         )  # type: ignore[assignment]
                 else:
-                    # When no response_model, answer should be a string
                     answer_str = str(answer) if not isinstance(answer, str) else answer
                     formatted_answer = process_llm_response(
                         answer_str, self.use_stop_words
                     )  # type: ignore[assignment]
 
                 if isinstance(formatted_answer, AgentAction):
-                    # Extract agent fingerprint if available
                     fingerprint_context = {}
                     if (
                         self.agent
@@ -426,7 +420,6 @@ class CrewAgentExecutor(BaseAgentExecutor):
 
             except Exception as e:
                 if e.__class__.__module__.startswith("litellm"):
-                    # Do not retry on litellm errors
                     raise e
                 if is_context_length_exceeded(e):
                     handle_context_length(
@@ -443,10 +436,6 @@ class CrewAgentExecutor(BaseAgentExecutor):
             finally:
                 self.iterations += 1
 
-        # During the invoke loop, formatted_answer alternates between AgentAction
-        # (when the agent is using tools) and eventually becomes AgentFinish
-        # (when the agent reaches a final answer). This check confirms we've
-        # reached a final answer and helps type checking understand this transition.
         if not isinstance(formatted_answer, AgentFinish):
             raise RuntimeError(
                 "Agent execution ended without reaching a final answer. "
@@ -465,9 +454,7 @@ class CrewAgentExecutor(BaseAgentExecutor):
         Returns:
             Final answer from the agent.
         """
-        # Convert tools to OpenAI schema format
         if not self.original_tools:
-            # No tools available, fall back to simple LLM call
             return self._invoke_loop_native_no_tools()
 
         openai_tools, available_functions, self._tool_name_mapping = (
@@ -490,10 +477,6 @@ class CrewAgentExecutor(BaseAgentExecutor):
 
                 enforce_rpm_limit(self.request_within_rpm_limit)
 
-                # Call LLM with native tools
-                # Pass available_functions=None so the LLM returns tool_calls
-                # without executing them. The executor handles tool execution
-                # via _handle_native_tool_calls to properly manage message history.
                 answer = get_llm_response(
                     llm=cast("BaseLLM", self.llm),
                     messages=self.messages,
@@ -508,32 +491,26 @@ class CrewAgentExecutor(BaseAgentExecutor):
                     verbose=self.agent.verbose,
                 )
 
-                # Check if the response is a list of tool calls
                 if (
                     isinstance(answer, list)
                     and answer
                     and self._is_tool_call_list(answer)
                 ):
-                    # Handle tool calls - execute tools and add results to messages
                     tool_finish = self._handle_native_tool_calls(
                         answer, available_functions
                     )
-                    # If tool has result_as_answer=True, return immediately
                     if tool_finish is not None:
                         return tool_finish
-                    # Continue loop to let LLM analyze results and decide next steps
                     continue
 
-                # Text or other response - handle as potential final answer
                 if isinstance(answer, str):
-                    # Text response - this is the final answer
                     formatted_answer = AgentFinish(
                         thought="",
                         output=answer,
                         text=answer,
                     )
                     self._invoke_step_callback(formatted_answer)
-                    self._append_message(answer)  # Save final answer to messages
+                    self._append_message(answer)
                     self._show_logs(formatted_answer)
                     return formatted_answer
 
@@ -549,14 +526,13 @@ class CrewAgentExecutor(BaseAgentExecutor):
                     self._show_logs(formatted_answer)
                     return formatted_answer
 
-                # Unexpected response type, treat as final answer
                 formatted_answer = AgentFinish(
                     thought="",
                     output=str(answer),
                     text=str(answer),
                 )
                 self._invoke_step_callback(formatted_answer)
-                self._append_message(str(answer))  # Save final answer to messages
+                self._append_message(str(answer))
                 self._show_logs(formatted_answer)
                 return formatted_answer
 
@@ -627,12 +603,10 @@ class CrewAgentExecutor(BaseAgentExecutor):
         if not response:
             return False
         first_item = response[0]
-        # OpenAI-style
         if hasattr(first_item, "function") or (
             isinstance(first_item, dict) and "function" in first_item
         ):
             return True
-        # Anthropic-style (object with attributes)
         if (
             hasattr(first_item, "type")
             and getattr(first_item, "type", None) == "tool_use"
@@ -640,14 +614,12 @@ class CrewAgentExecutor(BaseAgentExecutor):
             return True
         if hasattr(first_item, "name") and hasattr(first_item, "input"):
             return True
-        # Bedrock-style (dict with name and input keys)
         if (
             isinstance(first_item, dict)
             and "name" in first_item
             and "input" in first_item
         ):
             return True
-        # Gemini-style
         if hasattr(first_item, "function_call") and first_item.function_call:
             return True
         return False
@@ -706,8 +678,6 @@ class CrewAgentExecutor(BaseAgentExecutor):
                 for _, func_name, _ in parsed_calls
             )
 
-            # Preserve historical sequential behavior for result_as_answer batches.
-            # Also avoid threading around usage counters for max_usage_count tools.
             if has_result_as_answer_in_batch or has_max_usage_count_in_batch:
                 logger.debug(
                     "Skipping parallel native execution because batch includes result_as_answer or max_usage_count tool"
@@ -773,7 +743,6 @@ class CrewAgentExecutor(BaseAgentExecutor):
                 self.messages.append(reasoning_message)
                 return None
 
-        # Sequential behavior: process only first tool call, then force reflection.
         call_id, func_name, func_args = parsed_calls[0]
         self._append_assistant_tool_calls_message([(call_id, func_name, func_args)])
 
@@ -827,7 +796,7 @@ class CrewAgentExecutor(BaseAgentExecutor):
             func_name = sanitize_tool_name(
                 func_info.get("name", "") or tool_call.get("name", "")
             )
-            func_args = func_info.get("arguments", "{}") or tool_call.get("input", {})
+            func_args = func_info.get("arguments") or tool_call.get("input", {})
             return call_id, func_name, func_args
         return None
 
@@ -1202,7 +1171,6 @@ class CrewAgentExecutor(BaseAgentExecutor):
                                 text=answer,
                             )
                     except ValidationError:
-                        # If validation fails, convert BaseModel to JSON string for parsing
                         answer_str = (
                             answer.model_dump_json()
                             if isinstance(answer, BaseModel)
@@ -1212,7 +1180,6 @@ class CrewAgentExecutor(BaseAgentExecutor):
                             answer_str, self.use_stop_words
                         )  # type: ignore[assignment]
                 else:
-                    # When no response_model, answer should be a string
                     answer_str = str(answer) if not isinstance(answer, str) else answer
                     formatted_answer = process_llm_response(
                         answer_str, self.use_stop_words
@@ -1319,10 +1286,6 @@ class CrewAgentExecutor(BaseAgentExecutor):
 
                 enforce_rpm_limit(self.request_within_rpm_limit)
 
-                # Call LLM with native tools
-                # Pass available_functions=None so the LLM returns tool_calls
-                # without executing them. The executor handles tool execution
-                # via _handle_native_tool_calls to properly manage message history.
                 answer = await aget_llm_response(
                     llm=cast("BaseLLM", self.llm),
                     messages=self.messages,
@@ -1336,32 +1299,26 @@ class CrewAgentExecutor(BaseAgentExecutor):
                     executor_context=self,
                     verbose=self.agent.verbose,
                 )
-                # Check if the response is a list of tool calls
                 if (
                     isinstance(answer, list)
                     and answer
                     and self._is_tool_call_list(answer)
                 ):
-                    # Handle tool calls - execute tools and add results to messages
                     tool_finish = self._handle_native_tool_calls(
                         answer, available_functions
                     )
-                    # If tool has result_as_answer=True, return immediately
                     if tool_finish is not None:
                         return tool_finish
-                    # Continue loop to let LLM analyze results and decide next steps
                     continue
 
-                # Text or other response - handle as potential final answer
                 if isinstance(answer, str):
-                    # Text response - this is the final answer
                     formatted_answer = AgentFinish(
                         thought="",
                         output=answer,
                         text=answer,
                     )
                     await self._ainvoke_step_callback(formatted_answer)
-                    self._append_message(answer)  # Save final answer to messages
+                    self._append_message(answer)
                     self._show_logs(formatted_answer)
                     return formatted_answer
 
@@ -1377,14 +1334,13 @@ class CrewAgentExecutor(BaseAgentExecutor):
                     self._show_logs(formatted_answer)
                     return formatted_answer
 
-                # Unexpected response type, treat as final answer
                 formatted_answer = AgentFinish(
                     thought="",
                     output=str(answer),
                     text=str(answer),
                 )
                 await self._ainvoke_step_callback(formatted_answer)
-                self._append_message(str(answer))  # Save final answer to messages
+                self._append_message(str(answer))
                 self._show_logs(formatted_answer)
                 return formatted_answer
 
@@ -1455,7 +1411,6 @@ class CrewAgentExecutor(BaseAgentExecutor):
         Returns:
             Updated action or final answer.
         """
-        # Special case for add_image_tool
         add_image_tool = I18N_DEFAULT.tools("add_image")
         if (
             isinstance(add_image_tool, dict)
@@ -1575,17 +1530,14 @@ class CrewAgentExecutor(BaseAgentExecutor):
         training_handler = CrewTrainingHandler(TRAINING_DATA_FILE)
         training_data = training_handler.load() or {}
 
-        # Initialize or retrieve agent's training data
         agent_training_data = training_data.get(agent_id, {})
 
         if human_feedback is not None:
-            # Save initial output and human feedback
             agent_training_data[train_iteration] = {
                 "initial_output": result.output,
                 "human_feedback": human_feedback,
             }
         else:
-            # Save improved output
             if train_iteration in agent_training_data:
                 agent_training_data[train_iteration]["improved_output"] = result.output
             else:
@@ -1599,7 +1551,6 @@ class CrewAgentExecutor(BaseAgentExecutor):
                     )
                 return
 
-        # Update the training data and save
         training_data[agent_id] = agent_training_data
         training_handler.save(training_data)
 

lib/crewai/src/crewai/agents/parser.py

@@ -94,11 +94,8 @@ def parse(text: str) -> AgentAction | AgentFinish:
 
     if includes_answer:
         final_answer = text.split(FINAL_ANSWER_ACTION)[-1].strip()
-        # Check whether the final answer ends with triple backticks.
         if final_answer.endswith("```"):
-            # Count occurrences of triple backticks in the final answer.
             count = final_answer.count("```")
-            # If count is odd then it's an unmatched trailing set; remove it.
             if count % 2 != 0:
                 final_answer = final_answer[:-3].rstrip()
         return AgentFinish(thought=thought, output=final_answer, text=text)
@@ -146,7 +143,6 @@ def _extract_thought(text: str) -> str:
     if thought_index == -1:
         return ""
     thought = text[:thought_index].strip()
-    # Remove any triple backticks from the thought string
     return thought.replace("```", "").strip()
 
 
@@ -171,18 +167,9 @@ def _safe_repair_json(tool_input: str) -> str:
     Returns:
         The repaired JSON string or original if repair fails.
     """
-    # Skip repair if the input starts and ends with square brackets
-    # Explanation: The JSON parser has issues handling inputs that are enclosed in square brackets ('[]').
-    # These are typically valid JSON arrays or strings that do not require repair. Attempting to repair such inputs
-    # might lead to unintended alterations, such as wrapping the entire input in additional layers or modifying
-    # the structure in a way that changes its meaning. By skipping the repair for inputs that start and end with
-    # square brackets, we preserve the integrity of these valid JSON structures and avoid unnecessary modifications.
     if tool_input.startswith("[") and tool_input.endswith("]"):
         return tool_input
 
-    # Before repair, handle common LLM issues:
-    # 1. Replace """ with " to avoid JSON parser errors
-
     tool_input = tool_input.replace('"""', '"')
 
     result = repair_json(tool_input)

lib/crewai/src/crewai/agents/planner_observer.py

@@ -83,10 +83,6 @@ class PlannerObserver:
             return create_llm(config.llm)
         return self.agent.llm
 
-    # ------------------------------------------------------------------
-    # Public API
-    # ------------------------------------------------------------------
-
     def observe(
         self,
         completed_step: TodoItem,
@@ -182,9 +178,6 @@ class PlannerObserver:
                 ),
             )
 
-            # Don't force a full replan — the step may have succeeded even if the
-            # observer LLM failed to parse the result. Defaulting to "continue" is
-            # far less disruptive than wiping the entire plan on every observer error.
             return StepObservation(
                 step_completed_successfully=True,
                 key_information_learned="",
@@ -221,10 +214,6 @@ class PlannerObserver:
 
         return remaining_todos
 
-    # ------------------------------------------------------------------
-    # Internal: Message building
-    # ------------------------------------------------------------------
-
     def _build_observation_messages(
         self,
         completed_step: TodoItem,
@@ -239,15 +228,11 @@ class PlannerObserver:
             task_desc = self.task.description or ""
             task_goal = self.task.expected_output or ""
         elif self.kickoff_input:
-            # Standalone kickoff path — no Task object, but we have the raw input.
-            # Extract just the ## Task section so the observer sees the actual goal,
-            # not the full enriched instruction with env/tools/verification noise.
             task_desc = extract_task_section(self.kickoff_input)
             task_goal = "Complete the task successfully"
 
         system_prompt = I18N_DEFAULT.retrieve("planning", "observation_system_prompt")
 
-        # Build context of what's been done
         completed_summary = ""
         if all_completed:
             completed_lines = []
@@ -261,7 +246,6 @@ class PlannerObserver:
                 completed_lines
             )
 
-        # Build remaining plan
         remaining_summary = ""
         if remaining_todos:
             remaining_lines = [
@@ -306,17 +290,14 @@ class PlannerObserver:
         if isinstance(response, StepObservation):
             return response
 
-        # JSON string path — most common miss before this fix
         if isinstance(response, str):
             text = response.strip()
             try:
                 return StepObservation.model_validate_json(text)
             except Exception:  # noqa: S110
                 pass
-            # Some LLMs wrap the JSON in markdown fences
             if text.startswith("```"):
                 lines = text.split("\n")
-                # Strip first and last lines (``` markers)
                 inner = "\n".join(
                     lines[1:-1] if lines[-1].strip() == "```" else lines[1:]
                 )
@@ -325,14 +306,12 @@ class PlannerObserver:
                 except Exception:  # noqa: S110
                     pass
 
-        # Dict path
         if isinstance(response, dict):
             try:
                 return StepObservation.model_validate(response)
             except Exception:  # noqa: S110
                 pass
 
-        # Last resort — log what we got so it's diagnosable
         logger.warning(
             "Could not parse observation response (type=%s). "
             "Falling back to default failure observation. Preview: %.200s",

lib/crewai/src/crewai/agents/step_executor.py

@@ -108,7 +108,6 @@ class StepExecutor:
         self.request_within_rpm_limit = request_within_rpm_limit
         self.callbacks = callbacks or []
 
-        # Native tool support — set up once
         self._use_native_tools = check_native_tool_support(
             self.llm, self.original_tools
         )
@@ -121,10 +120,6 @@ class StepExecutor:
                 _,
             ) = setup_native_tools(self.original_tools)
 
-    # ------------------------------------------------------------------
-    # Public API
-    # ------------------------------------------------------------------
-
     def execute(
         self,
         todo: TodoItem,
@@ -190,10 +185,6 @@ class StepExecutor:
                 execution_time=elapsed,
             )
 
-    # ------------------------------------------------------------------
-    # Internal: Message building
-    # ------------------------------------------------------------------
-
     def _build_isolated_messages(
         self, todo: TodoItem, context: StepExecutionContext
     ) -> list[LLMMessage]:
@@ -237,10 +228,6 @@ class StepExecutor:
         """Build the user prompt for this specific step."""
         parts: list[str] = []
 
-        # Include overall task context so the executor knows the full goal and
-        # required output format/location — critical for knowing WHAT to produce.
-        # We extract only the task body (not tool instructions or verification
-        # sections) to avoid duplicating directives already in the system prompt.
         if context.task_description:
             task_section = extract_task_section(context.task_description)
             if task_section:
@@ -267,7 +254,6 @@ class StepExecutor:
                 )
             )
 
-        # Include dependency results (final results only, no traces)
         if context.dependency_results:
             parts.append(
                 I18N_DEFAULT.retrieve("planning", "step_executor_context_header")
@@ -283,10 +269,6 @@ class StepExecutor:
 
         return "\n".join(parts)
 
-    # ------------------------------------------------------------------
-    # Internal: Multi-turn execution loop
-    # ------------------------------------------------------------------
-
     def _execute_text_parsed(
         self,
         messages: list[LLMMessage],
@@ -306,7 +288,6 @@ class StepExecutor:
         last_tool_result = ""
 
         for _ in range(max_step_iterations):
-            # Check step timeout
             if step_timeout and start_time:
                 elapsed = time.monotonic() - start_time
                 if elapsed >= step_timeout:
@@ -331,17 +312,12 @@ class StepExecutor:
                 tool_calls_made.append(formatted.tool)
                 tool_result = self._execute_text_tool_with_events(formatted)
                 last_tool_result = tool_result
-                # Append the assistant's reasoning + action, then the observation.
-                # _build_observation_message handles vision sentinels so the LLM
-                # receives an image content block instead of raw base64 text.
                 messages.append({"role": "assistant", "content": answer_str})
                 messages.append(self._build_observation_message(tool_result))
                 continue
 
-            # Raw text response with no Final Answer marker — treat as done
             return answer_str
 
-        # Max iterations reached — return the last tool result we accumulated
         return last_tool_result
 
     def _execute_text_tool_with_events(self, formatted: AgentAction) -> str:
@@ -429,10 +405,6 @@ class StepExecutor:
                 return {"input": stripped_input}
         return {"input": str(tool_input)}
 
-    # ------------------------------------------------------------------
-    # Internal: Vision support
-    # ------------------------------------------------------------------
-
     @staticmethod
     def _parse_vision_sentinel(raw: str) -> tuple[str, str] | None:
         """Parse a VISION_IMAGE sentinel into (media_type, base64_data), or None."""
@@ -517,7 +489,6 @@ class StepExecutor:
         accumulated_results: list[str] = []
 
         for _ in range(max_step_iterations):
-            # Check step timeout
             if step_timeout and start_time:
                 elapsed = time.monotonic() - start_time
                 if elapsed >= step_timeout:
@@ -541,19 +512,14 @@ class StepExecutor:
                 return answer.model_dump_json()
 
             if isinstance(answer, list) and answer and is_tool_call_list(answer):
-                # _execute_native_tool_calls appends assistant + tool messages
-                # to `messages` as a side-effect, so the next LLM call will
-                # see the full conversation history including tool outputs.
                 result = self._execute_native_tool_calls(
                     answer, messages, tool_calls_made
                 )
                 accumulated_results.append(result)
                 continue
 
-            # Text answer → LLM decided the step is done
             return str(answer)
 
-        # Max iterations reached — return everything we accumulated
         return "\n".join(filter(None, accumulated_results))
 
     def _execute_native_tool_calls(
@@ -599,9 +565,6 @@ class StepExecutor:
                     parsed = self._parse_vision_sentinel(raw_content)
                     if parsed:
                         media_type, b64_data = parsed
-                        # Replace the sentinel with a standard image_url content block.
-                        # Each provider's _format_messages handles conversion to
-                        # its native format (e.g. Anthropic image blocks).
                         modified: LLMMessage = cast(
                             LLMMessage, dict(call_result.tool_message)
                         )

lib/crewai/src/crewai/cli/checkpoint_cli.py

@@ -6,12 +6,16 @@ from datetime import datetime
 import glob
 import json
 import os
+import re
 import sqlite3
 from typing import Any
 
 import click
 
 
+_PLACEHOLDER_RE = re.compile(r"\{([A-Za-z_][A-Za-z0-9_\-]*)}")
+
+
 _SQLITE_MAGIC = b"SQLite format 3\x00"
 
 _SELECT_ALL = """
@@ -34,6 +38,25 @@ LIMIT 1
 """
 
 
+_DEFAULT_DIR = "./.checkpoints"
+_DEFAULT_DB = "./.checkpoints.db"
+
+
+def _detect_location(location: str) -> str:
+    """Resolve the default checkpoint location.
+
+    When the caller passes the default directory path, check whether a
+    SQLite database exists at the conventional ``.db`` path and prefer it.
+    """
+    if (
+        location == _DEFAULT_DIR
+        and not os.path.exists(_DEFAULT_DIR)
+        and os.path.exists(_DEFAULT_DB)
+    ):
+        return _DEFAULT_DB
+    return location
+
+
 def _is_sqlite(path: str) -> bool:
     """Check if a file is a SQLite database by reading its magic bytes."""
     if not os.path.isfile(path):
@@ -52,13 +75,7 @@ def _parse_checkpoint_json(raw: str, source: str) -> dict[str, Any]:
     nodes = data.get("event_record", {}).get("nodes", {})
     event_count = len(nodes)
 
-    trigger_event = None
-    if nodes:
-        last_node = max(
-            nodes.values(),
-            key=lambda n: n.get("event", {}).get("emission_sequence") or 0,
-        )
-        trigger_event = last_node.get("event", {}).get("type")
+    trigger_event = data.get("trigger")
 
     parsed_entities: list[dict[str, Any]] = []
     for entity in entities:
@@ -76,16 +93,47 @@ def _parse_checkpoint_json(raw: str, source: str) -> dict[str, Any]:
                 {
                     "description": t.get("description", ""),
                     "completed": t.get("output") is not None,
+                    "output": (t.get("output") or {}).get("raw", ""),
                 }
                 for t in tasks
             ]
         parsed_entities.append(info)
 
+    inputs: dict[str, Any] = {}
+    for entity in entities:
+        cp_inputs = entity.get("checkpoint_inputs")
+        if isinstance(cp_inputs, dict) and cp_inputs:
+            inputs = dict(cp_inputs)
+            break
+
+    for entity in entities:
+        for task in entity.get("tasks", []):
+            for field in (
+                "checkpoint_original_description",
+                "checkpoint_original_expected_output",
+            ):
+                text = task.get(field) or ""
+                for match in _PLACEHOLDER_RE.findall(text):
+                    if match not in inputs:
+                        inputs[match] = ""
+        for agent in entity.get("agents", []):
+            for field in ("role", "goal", "backstory"):
+                text = agent.get(field) or ""
+                for match in _PLACEHOLDER_RE.findall(text):
+                    if match not in inputs:
+                        inputs[match] = ""
+
+    branch = data.get("branch", "main")
+    parent_id = data.get("parent_id")
+
     return {
         "source": source,
         "event_count": event_count,
         "trigger": trigger_event,
         "entities": parsed_entities,
+        "branch": branch,
+        "parent_id": parent_id,
+        "inputs": inputs,
     }
 
 
@@ -189,6 +237,7 @@ def _list_sqlite(db_path: str) -> list[dict[str, Any]]:
                     "entities": [],
                     "source": checkpoint_id,
                 }
+            meta["db"] = db_path
             results.append(meta)
     return results
 
@@ -311,6 +360,10 @@ def _print_info(meta: dict[str, Any]) -> None:
     trigger = meta.get("trigger")
     if trigger:
         click.echo(f"Trigger: {trigger}")
+    click.echo(f"Branch:  {meta.get('branch', 'main')}")
+    parent_id = meta.get("parent_id")
+    if parent_id:
+        click.echo(f"Parent:  {parent_id}")
 
     for ent in meta.get("entities", []):
         eid = str(ent.get("id", ""))[:8]

lib/crewai/src/crewai/cli/checkpoint_tui.py

@@ -2,17 +2,23 @@
 
 from __future__ import annotations
 
+from collections import defaultdict
 from typing import Any, ClassVar
 
 from textual.app import App, ComposeResult
 from textual.binding import Binding
-from textual.containers import Horizontal, Vertical
-from textual.screen import ModalScreen
-from textual.widgets import Button, Footer, Header, OptionList, Static
-from textual.widgets.option_list import Option
+from textual.containers import Horizontal, Vertical, VerticalScroll
+from textual.widgets import (
+    Button,
+    Footer,
+    Header,
+    Input,
+    Static,
+    TextArea,
+    Tree,
+)
 
 from crewai.cli.checkpoint_cli import (
-    _entity_summary,
     _format_size,
     _is_sqlite,
     _list_json,
@@ -34,151 +40,54 @@ def _load_entries(location: str) -> list[dict[str, Any]]:
     return _list_json(location)
 
 
-def _format_list_label(entry: dict[str, Any]) -> str:
-    """Format a checkpoint entry for the list panel."""
-    name = entry.get("name", "")
-    ts = entry.get("ts") or ""
-    trigger = entry.get("trigger") or ""
-    summary = _entity_summary(entry.get("entities", []))
-
-    line1 = f"[bold]{name}[/]"
-    parts = []
-    if ts:
-        parts.append(f"[dim]{ts}[/]")
-    if "size" in entry:
-        parts.append(f"[dim]{_format_size(entry['size'])}[/]")
-    if trigger:
-        parts.append(f"[{_PRIMARY}]{trigger}[/]")
-    line2 = "  ".join(parts)
-    line3 = f"  [{_DIM}]{summary}[/]"
-
-    return f"{line1}\n{line2}\n{line3}"
+def _short_id(name: str) -> str:
+    """Shorten a checkpoint name for tree display."""
+    if len(name) > 30:
+        return name[:27] + "..."
+    return name
 
 
-def _format_detail(entry: dict[str, Any]) -> str:
-    """Format checkpoint details for the right panel."""
+def _entry_id(entry: dict[str, Any]) -> str:
+    """Normalize an entry's name into its checkpoint ID.
+
+    JSON filenames are ``{ts}_{uuid}_p-{parent}.json``; SQLite IDs
+    are already ``{ts}_{uuid}``. This strips the JSON suffix so
+    fork-parent lookups work in both providers.
+    """
+    name = str(entry.get("name", ""))
+    if name.endswith(".json"):
+        name = name[: -len(".json")]
+    idx = name.find("_p-")
+    if idx != -1:
+        name = name[:idx]
+    return name
+
+
+def _build_entity_header(ent: dict[str, Any]) -> str:
+    """Build rich text header for an entity (progress bar only)."""
     lines: list[str] = []
-
-    # Header
-    name = entry.get("name", "")
-    lines.append(f"[bold {_PRIMARY}]{name}[/]")
-    lines.append(f"[{_DIM}]{'─' * 50}[/]")
-    lines.append("")
-
-    # Metadata table
-    ts = entry.get("ts") or "unknown"
-    trigger = entry.get("trigger") or ""
-    lines.append(f"  [bold]Time[/]       {ts}")
-    if "size" in entry:
-        lines.append(f"  [bold]Size[/]       {_format_size(entry['size'])}")
-    lines.append(f"  [bold]Events[/]     {entry.get('event_count', 0)}")
-    if trigger:
-        lines.append(f"  [bold]Trigger[/]    [{_PRIMARY}]{trigger}[/]")
-    if "path" in entry:
-        lines.append(f"  [bold]Path[/]       [{_DIM}]{entry['path']}[/]")
-    if "db" in entry:
-        lines.append(f"  [bold]Database[/]   [{_DIM}]{entry['db']}[/]")
-
-    # Entities
-    for ent in entry.get("entities", []):
-        eid = str(ent.get("id", ""))[:8]
-        etype = ent.get("type", "unknown")
-        ename = ent.get("name", "unnamed")
-
-        lines.append("")
-        lines.append(f"  [{_DIM}]{'─' * 50}[/]")
-        lines.append(f"  [bold {_SECONDARY}]{etype}[/]: {ename} [{_DIM}]{eid}[/]")
-
-        tasks = ent.get("tasks")
-        if isinstance(tasks, list):
-            completed = ent.get("tasks_completed", 0)
-            total = ent.get("tasks_total", 0)
-            pct = int(completed / total * 100) if total else 0
-            bar_len = 20
-            filled = int(bar_len * completed / total) if total else 0
-            bar = f"[{_PRIMARY}]{'█' * filled}[/][{_DIM}]{'░' * (bar_len - filled)}[/]"
-
-            lines.append(f"  {bar}  {completed}/{total} tasks ({pct}%)")
-            lines.append("")
-
-            for i, task in enumerate(tasks):
-                if task.get("completed"):
-                    icon = "[green]✓[/]"
-                else:
-                    icon = "[yellow]○[/]"
-                desc = str(task.get("description", ""))
-                if len(desc) > 55:
-                    desc = desc[:52] + "..."
-                lines.append(f"    {icon}  {i + 1}. {desc}")
-
+    tasks = ent.get("tasks")
+    if isinstance(tasks, list):
+        completed = ent.get("tasks_completed", 0)
+        total = ent.get("tasks_total", 0)
+        pct = int(completed / total * 100) if total else 0
+        bar_len = 20
+        filled = int(bar_len * completed / total) if total else 0
+        bar = f"[{_PRIMARY}]{'█' * filled}[/][{_DIM}]{'░' * (bar_len - filled)}[/]"
+        lines.append(f"{bar}  {completed}/{total} tasks ({pct}%)")
     return "\n".join(lines)
 
 
-class ConfirmResumeScreen(ModalScreen[bool]):
-    """Modal confirmation before resuming from a checkpoint."""
-
-    CSS = f"""
-    ConfirmResumeScreen {{
-        align: center middle;
-    }}
-    #confirm-dialog {{
-        width: 60;
-        height: auto;
-        padding: 1 2;
-        background: {_BG_PANEL};
-        border: round {_PRIMARY};
-    }}
-    #confirm-label {{
-        width: 100%;
-        content-align: center middle;
-        margin-bottom: 1;
-    }}
-    #confirm-name {{
-        width: 100%;
-        content-align: center middle;
-        color: {_PRIMARY};
-        text-style: bold;
-        margin-bottom: 1;
-    }}
-    #confirm-buttons {{
-        width: 100%;
-        height: 3;
-        layout: horizontal;
-        align: center middle;
-    }}
-    Button {{
-        margin: 0 2;
-        min-width: 12;
-    }}
-    """
-
-    def __init__(self, checkpoint_name: str) -> None:
-        super().__init__()
-        self._checkpoint_name = checkpoint_name
-
-    def compose(self) -> ComposeResult:
-        with Vertical(id="confirm-dialog"):
-            yield Static("Resume from this checkpoint?", id="confirm-label")
-            yield Static(self._checkpoint_name, id="confirm-name")
-            with Horizontal(id="confirm-buttons"):
-                yield Button("Resume", variant="success", id="btn-yes")
-                yield Button("Cancel", variant="default", id="btn-no")
-
-    def on_button_pressed(self, event: Button.Pressed) -> None:
-        self.dismiss(event.button.id == "btn-yes")
-
-    def on_key(self, event: Any) -> None:
-        if event.key == "y":
-            self.dismiss(True)
-        elif event.key in ("n", "escape"):
-            self.dismiss(False)
+# Return type: (location, action, inputs, task_output_overrides)
+_TuiResult = tuple[str, str, dict[str, Any] | None, dict[int, str] | None] | None
 
 
-class CheckpointTUI(App[str | None]):
+class CheckpointTUI(App[_TuiResult]):
     """TUI to browse and inspect checkpoints.
 
-    Returns the checkpoint location string to resume from, or None if
-    the user quit without selecting.
+    Returns ``(location, action, inputs)`` where action is ``"resume"`` or
+    ``"fork"`` and inputs is a parsed dict or ``None``,
+    or ``None`` if the user quit without selecting.
     """
 
     TITLE = "CrewAI Checkpoints"
@@ -199,145 +108,431 @@ class CheckpointTUI(App[str | None]):
         background: {_PRIMARY};
         color: {_TERTIARY};
     }}
-    Horizontal {{
+    #main-layout {{
         height: 1fr;
     }}
-    #cp-list {{
-        width: 38%;
+    #tree-panel {{
+        width: 45%;
         background: {_BG_PANEL};
         border: round {_SECONDARY};
         padding: 0 1;
         scrollbar-color: {_PRIMARY};
     }}
-    #cp-list:focus {{
+    #tree-panel:focus-within {{
         border: round {_PRIMARY};
     }}
-    #cp-list > .option-list--option-highlighted {{
-        background: {_SECONDARY};
-        color: {_TERTIARY};
-        text-style: none;
-    }}
-    #cp-list > .option-list--option-highlighted * {{
-        color: {_TERTIARY};
-    }}
     #detail-container {{
-        width: 62%;
-        padding: 0 1;
+        width: 55%;
+        height: 1fr;
     }}
-    #detail {{
+    #detail-scroll {{
         height: 1fr;
         background: {_BG_PANEL};
         border: round {_SECONDARY};
         padding: 1 2;
-        overflow-y: auto;
         scrollbar-color: {_PRIMARY};
     }}
-    #detail:focus {{
+    #detail-scroll:focus-within {{
         border: round {_PRIMARY};
     }}
+    #detail-header {{
+        margin-bottom: 1;
+    }}
     #status {{
         height: 1;
         padding: 0 2;
         color: {_DIM};
     }}
+    #inputs-section {{
+        display: none;
+        height: auto;
+        max-height: 8;
+        padding: 0 1;
+    }}
+    #inputs-section.visible {{
+        display: block;
+    }}
+    #inputs-label {{
+        height: 1;
+        color: {_DIM};
+        padding: 0 1;
+    }}
+    .input-row {{
+        height: 3;
+        padding: 0 1;
+    }}
+    .input-row Static {{
+        width: auto;
+        min-width: 12;
+        padding: 1 1 0 0;
+        color: {_TERTIARY};
+    }}
+    .input-row Input {{
+        width: 1fr;
+    }}
+    #no-inputs-label {{
+        height: 1;
+        color: {_DIM};
+        padding: 0 1;
+    }}
+    #action-buttons {{
+        height: 3;
+        align: right middle;
+        padding: 0 1;
+        display: none;
+    }}
+    #action-buttons.visible {{
+        display: block;
+    }}
+    #action-buttons Button {{
+        margin: 0 0 0 1;
+        min-width: 10;
+    }}
+    #btn-resume {{
+        background: {_SECONDARY};
+        color: {_TERTIARY};
+    }}
+    #btn-resume:hover {{
+        background: {_PRIMARY};
+    }}
+    #btn-fork {{
+        background: {_PRIMARY};
+        color: {_TERTIARY};
+    }}
+    #btn-fork:hover {{
+        background: {_SECONDARY};
+    }}
+    .entity-title {{
+        padding: 1 1 0 1;
+    }}
+    .entity-detail {{
+        padding: 0 1;
+    }}
+    .task-output-editor {{
+        height: auto;
+        max-height: 10;
+        margin: 0 1 1 1;
+        border: round {_DIM};
+    }}
+    .task-output-editor:focus {{
+        border: round {_PRIMARY};
+    }}
+    .task-label {{
+        padding: 0 1;
+    }}
+    Tree {{
+        background: {_BG_PANEL};
+    }}
+    Tree > .tree--cursor {{
+        background: {_SECONDARY};
+        color: {_TERTIARY};
+    }}
     """
 
     BINDINGS: ClassVar[list[Binding | tuple[str, str] | tuple[str, str, str]]] = [
         ("q", "quit", "Quit"),
         ("r", "refresh", "Refresh"),
-        ("j", "cursor_down", "Down"),
-        ("k", "cursor_up", "Up"),
     ]
 
     def __init__(self, location: str = "./.checkpoints") -> None:
         super().__init__()
         self._location = location
         self._entries: list[dict[str, Any]] = []
-        self._selected_idx: int = 0
-        self._pending_location: str = ""
+        self._selected_entry: dict[str, Any] | None = None
+        self._input_keys: list[str] = []
+        self._task_output_ids: list[tuple[int, str, str]] = []
 
     def compose(self) -> ComposeResult:
         yield Header(show_clock=False)
-        with Horizontal():
-            yield OptionList(id="cp-list")
+        with Horizontal(id="main-layout"):
+            tree: Tree[dict[str, Any]] = Tree("Checkpoints", id="tree-panel")
+            tree.show_root = True
+            tree.guide_depth = 3
+            yield tree
             with Vertical(id="detail-container"):
                 yield Static("", id="status")
-                yield Static(
-                    f"\n  [{_DIM}]Select a checkpoint from the list[/]",  # noqa: S608
-                    id="detail",
-                )
+                with VerticalScroll(id="detail-scroll"):
+                    yield Static(
+                        f"[{_DIM}]Select a checkpoint from the tree[/]",  # noqa: S608
+                        id="detail-header",
+                    )
+                with Vertical(id="inputs-section"):
+                    yield Static("Inputs", id="inputs-label")
+                with Horizontal(id="action-buttons"):
+                    yield Button("Resume", id="btn-resume")
+                    yield Button("Fork", id="btn-fork")
         yield Footer()
 
     async def on_mount(self) -> None:
-        self.query_one("#cp-list", OptionList).border_title = "Checkpoints"
-        self.query_one("#detail", Static).border_title = "Detail"
-        self._refresh_list()
+        self._refresh_tree()
+        self.query_one("#tree-panel", Tree).root.expand()
 
-    def _refresh_list(self) -> None:
+    def _refresh_tree(self) -> None:
         self._entries = _load_entries(self._location)
-        option_list = self.query_one("#cp-list", OptionList)
-        option_list.clear_options()
+        self._selected_entry = None
+
+        tree = self.query_one("#tree-panel", Tree)
+        tree.clear()
 
         if not self._entries:
-            self.query_one("#detail", Static).update(
-                f"\n  [{_DIM}]No checkpoints in {self._location}[/]"
+            self.query_one("#detail-header", Static).update(
+                f"[{_DIM}]No checkpoints in {self._location}[/]"
             )
             self.query_one("#status", Static).update("")
             self.sub_title = self._location
             return
 
+        # Group by branch
+        branches: dict[str, list[dict[str, Any]]] = defaultdict(list)
         for entry in self._entries:
-            option_list.add_option(Option(_format_list_label(entry)))
+            branch = entry.get("branch", "main")
+            branches[branch].append(entry)
+
+        # Index checkpoint names to tree nodes so forks can attach
+        node_by_name: dict[str, Any] = {}
+
+        def _make_label(e: dict[str, Any]) -> str:
+            name = e.get("name", "")
+            ts = e.get("ts") or ""
+            trigger = e.get("trigger") or ""
+            parts = [f"[bold]{_short_id(name)}[/]"]
+            if ts:
+                time_part = ts.split(" ")[-1] if " " in ts else ts
+                parts.append(f"[{_DIM}]{time_part}[/]")
+            if trigger:
+                parts.append(f"[{_PRIMARY}]{trigger}[/]")
+            return "  ".join(parts)
+
+        fork_parents: set[str] = set()
+        for branch_name, entries in branches.items():
+            if branch_name == "main" or not entries:
+                continue
+            oldest = min(entries, key=lambda e: str(e.get("name", "")))
+            first_parent = oldest.get("parent_id")
+            if first_parent:
+                fork_parents.add(str(first_parent))
+
+        def _add_checkpoint(parent_node: Any, e: dict[str, Any]) -> None:
+            """Add a checkpoint node — expandable only if a fork attaches to it."""
+            cp_id = _entry_id(e)
+            if cp_id in fork_parents:
+                node = parent_node.add(
+                    _make_label(e), data=e, expand=False, allow_expand=True
+                )
+            else:
+                node = parent_node.add_leaf(_make_label(e), data=e)
+            node_by_name[cp_id] = node
+
+        if "main" in branches:
+            for entry in reversed(branches["main"]):
+                _add_checkpoint(tree.root, entry)
+
+        fork_branches = [
+            (name, sorted(entries, key=lambda e: str(e.get("name", ""))))
+            for name, entries in branches.items()
+            if name != "main"
+        ]
+        remaining = fork_branches
+        max_passes = len(remaining) + 1
+        while remaining and max_passes > 0:
+            max_passes -= 1
+            deferred = []
+            made_progress = False
+            for branch_name, entries in remaining:
+                first_parent = entries[0].get("parent_id") if entries else None
+                if first_parent and str(first_parent) not in node_by_name:
+                    deferred.append((branch_name, entries))
+                    continue
+                attach_to: Any = tree.root
+                if first_parent:
+                    attach_to = node_by_name.get(str(first_parent), tree.root)
+                branch_label = (
+                    f"[bold {_SECONDARY}]{branch_name}[/]  [{_DIM}]({len(entries)})[/]"
+                )
+                branch_node = attach_to.add(branch_label, expand=False)
+                for entry in entries:
+                    _add_checkpoint(branch_node, entry)
+                made_progress = True
+            remaining = deferred
+            if not made_progress:
+                break
+
+        for branch_name, entries in remaining:
+            branch_label = (
+                f"[bold {_SECONDARY}]{branch_name}[/]  "
+                f"[{_DIM}]({len(entries)})[/]  [{_DIM}](orphaned)[/]"
+            )
+            branch_node = tree.root.add(branch_label, expand=False)
+            for entry in entries:
+                _add_checkpoint(branch_node, entry)
 
         count = len(self._entries)
         storage = "SQLite" if _is_sqlite(self._location) else "JSON"
-        self.sub_title = f"{self._location}"
+        self.sub_title = self._location
         self.query_one("#status", Static).update(f" {count} checkpoint(s) | {storage}")
 
-    async def on_option_list_option_highlighted(
-        self,
-        event: OptionList.OptionHighlighted,
-    ) -> None:
-        idx = event.option_index
-        if idx is None:
-            return
-        if idx < len(self._entries):
-            self._selected_idx = idx
-            entry = self._entries[idx]
-            self.query_one("#detail", Static).update(_format_detail(entry))
+    async def _show_detail(self, entry: dict[str, Any]) -> None:
+        """Update the detail panel for a checkpoint entry."""
+        self._selected_entry = entry
+        self.query_one("#action-buttons").add_class("visible")
 
-    def action_cursor_down(self) -> None:
-        self.query_one("#cp-list", OptionList).action_cursor_down()
+        detail_scroll = self.query_one("#detail-scroll", VerticalScroll)
 
-    def action_cursor_up(self) -> None:
-        self.query_one("#cp-list", OptionList).action_cursor_up()
+        # Remove all dynamic children except the header — await so IDs are freed
+        to_remove = [c for c in detail_scroll.children if c.id != "detail-header"]
+        for child in to_remove:
+            await child.remove()
 
-    async def on_option_list_option_selected(
-        self,
-        event: OptionList.OptionSelected,
-    ) -> None:
-        idx = event.option_index
-        if idx is None or idx >= len(self._entries):
-            return
-        entry = self._entries[idx]
+        # Header
+        name = entry.get("name", "")
+        ts = entry.get("ts") or "unknown"
+        trigger = entry.get("trigger") or ""
+        branch = entry.get("branch", "main")
+        parent_id = entry.get("parent_id")
+
+        header_lines = [
+            f"[bold {_PRIMARY}]{name}[/]",
+            f"[{_DIM}]{'─' * 50}[/]",
+            "",
+            f"  [bold]Time[/]       {ts}",
+        ]
+        if "size" in entry:
+            header_lines.append(f"  [bold]Size[/]       {_format_size(entry['size'])}")
+        header_lines.append(f"  [bold]Events[/]     {entry.get('event_count', 0)}")
+        if trigger:
+            header_lines.append(f"  [bold]Trigger[/]    [{_PRIMARY}]{trigger}[/]")
+        header_lines.append(f"  [bold]Branch[/]     [{_SECONDARY}]{branch}[/]")
+        if parent_id:
+            header_lines.append(f"  [bold]Parent[/]     [{_DIM}]{parent_id}[/]")
         if "path" in entry:
-            loc = entry["path"]
-        elif _is_sqlite(self._location):
-            loc = f"{self._location}#{entry['name']}"
-        else:
-            loc = entry.get("name", "")
-        self._pending_location = loc
-        name = entry.get("name", loc)
-        self.push_screen(ConfirmResumeScreen(name), self._on_confirm)
+            header_lines.append(f"  [bold]Path[/]       [{_DIM}]{entry['path']}[/]")
+        if "db" in entry:
+            header_lines.append(f"  [bold]Database[/]   [{_DIM}]{entry['db']}[/]")
 
-    def _on_confirm(self, confirmed: bool | None) -> None:
-        if confirmed:
-            self.exit(self._pending_location)
-        else:
-            self._pending_location = ""
+        self.query_one("#detail-header", Static).update("\n".join(header_lines))
+
+        # Entity details and editable task outputs — mounted flat for scrolling
+        self._task_output_ids = []
+        flat_task_idx = 0
+        for ent_idx, ent in enumerate(entry.get("entities", [])):
+            etype = ent.get("type", "unknown")
+            ename = ent.get("name", "unnamed")
+            completed = ent.get("tasks_completed")
+            total = ent.get("tasks_total")
+            entity_title = f"[bold {_SECONDARY}]{etype}: {ename}[/]"
+            if completed is not None and total is not None:
+                entity_title += f"  [{_DIM}]{completed}/{total} tasks[/]"
+            await detail_scroll.mount(Static(entity_title, classes="entity-title"))
+            await detail_scroll.mount(
+                Static(_build_entity_header(ent), classes="entity-detail")
+            )
+
+            tasks = ent.get("tasks", [])
+            for i, task in enumerate(tasks):
+                desc = str(task.get("description", ""))
+                if len(desc) > 55:
+                    desc = desc[:52] + "..."
+                if task.get("completed"):
+                    icon = "[green]✓[/]"
+                    await detail_scroll.mount(
+                        Static(f"  {icon}  {i + 1}. {desc}", classes="task-label")
+                    )
+                    output_text = task.get("output", "")
+                    editor_id = f"task-output-{ent_idx}-{i}"
+                    await detail_scroll.mount(
+                        TextArea(
+                            str(output_text),
+                            classes="task-output-editor",
+                            id=editor_id,
+                        )
+                    )
+                    self._task_output_ids.append(
+                        (flat_task_idx, editor_id, str(output_text))
+                    )
+                else:
+                    icon = "[yellow]○[/]"
+                    await detail_scroll.mount(
+                        Static(f"  {icon}  {i + 1}. {desc}", classes="task-label")
+                    )
+                flat_task_idx += 1
+
+        # Build input fields
+        await self._build_input_fields(entry.get("inputs", {}))
+
+    async def _build_input_fields(self, inputs: dict[str, Any]) -> None:
+        """Rebuild the inputs section with one field per input key."""
+        section = self.query_one("#inputs-section")
+
+        # Remove old dynamic children — await so IDs are freed
+        for widget in list(section.query(".input-row, .no-inputs")):
+            await widget.remove()
+
+        self._input_keys = []
+
+        if not inputs:
+            await section.mount(Static(f"[{_DIM}]No inputs[/]", classes="no-inputs"))
+            section.add_class("visible")
+            return
+
+        for key, value in inputs.items():
+            self._input_keys.append(key)
+            row = Horizontal(classes="input-row")
+            row.compose_add_child(Static(f"[bold]{key}[/]"))
+            row.compose_add_child(
+                Input(value=str(value), placeholder=key, id=f"input-{key}")
+            )
+            await section.mount(row)
+
+        section.add_class("visible")
+
+    def _collect_inputs(self) -> dict[str, Any] | None:
+        """Collect current values from input fields."""
+        if not self._input_keys:
+            return None
+        result: dict[str, Any] = {}
+        for key in self._input_keys:
+            widget = self.query_one(f"#input-{key}", Input)
+            result[key] = widget.value
+        return result
+
+    def _collect_task_overrides(self) -> dict[int, str] | None:
+        """Collect edited task outputs. Returns only changed values."""
+        if not self._task_output_ids or self._selected_entry is None:
+            return None
+        overrides: dict[int, str] = {}
+        for task_idx, editor_id, original in self._task_output_ids:
+            editor = self.query_one(f"#{editor_id}", TextArea)
+            if editor.text != original:
+                overrides[task_idx] = editor.text
+        return overrides or None
+
+    def _resolve_location(self, entry: dict[str, Any]) -> str:
+        """Get the restore location string for a checkpoint entry."""
+        if "path" in entry:
+            return str(entry["path"])
+        if _is_sqlite(self._location):
+            return f"{self._location}#{entry['name']}"
+        return str(entry.get("name", ""))
+
+    async def on_tree_node_highlighted(
+        self, event: Tree.NodeHighlighted[dict[str, Any]]
+    ) -> None:
+        if event.node.data is not None:
+            await self._show_detail(event.node.data)
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        if self._selected_entry is None:
+            return
+        inputs = self._collect_inputs()
+        overrides = self._collect_task_overrides()
+        loc = self._resolve_location(self._selected_entry)
+        if event.button.id == "btn-resume":
+            self.exit((loc, "resume", inputs, overrides))
+        elif event.button.id == "btn-fork":
+            self.exit((loc, "fork", inputs, overrides))
 
     def action_refresh(self) -> None:
-        self._refresh_list()
+        self._refresh_tree()
 
 
 async def _run_checkpoint_tui_async(location: str) -> None:
@@ -345,17 +540,78 @@ async def _run_checkpoint_tui_async(location: str) -> None:
     import click
 
     app = CheckpointTUI(location=location)
-    selected = await app.run_async()
+    selection = await app.run_async()
 
-    if selected is None:
+    if selection is None:
         return
 
-    click.echo(f"\nResuming from: {selected}\n")
+    selected, action, inputs, task_overrides = selection
 
     from crewai.crew import Crew
+    from crewai.state.checkpoint_config import CheckpointConfig
 
-    crew = Crew.from_checkpoint(selected)
-    result = await crew.akickoff()
+    config = CheckpointConfig(restore_from=selected)
+
+    if action == "fork":
+        click.echo(f"\nForking from: {selected}\n")
+        crew = Crew.fork(config)
+    else:
+        click.echo(f"\nResuming from: {selected}\n")
+        crew = Crew.from_checkpoint(config)
+
+    if task_overrides:
+        click.echo("Modifications:")
+        overridden_agents: set[int] = set()
+        for task_idx, new_output in task_overrides.items():
+            if task_idx < len(crew.tasks) and crew.tasks[task_idx].output is not None:
+                desc = crew.tasks[task_idx].description or f"Task {task_idx + 1}"
+                if len(desc) > 60:
+                    desc = desc[:57] + "..."
+                crew.tasks[task_idx].output.raw = new_output  # type: ignore[union-attr]
+                preview = new_output.replace("\n", " ")
+                if len(preview) > 80:
+                    preview = preview[:77] + "..."
+                click.echo(f"  Task {task_idx + 1}: {desc}")
+                click.echo(f"    -> {preview}")
+                agent = crew.tasks[task_idx].agent
+                if agent and agent.agent_executor:
+                    nth = sum(1 for t in crew.tasks[:task_idx] if t.agent is agent)
+                    messages = agent.agent_executor.messages
+                    system_positions = [
+                        i for i, m in enumerate(messages) if m.get("role") == "system"
+                    ]
+                    if nth < len(system_positions):
+                        seg_start = system_positions[nth]
+                        seg_end = (
+                            system_positions[nth + 1]
+                            if nth + 1 < len(system_positions)
+                            else len(messages)
+                        )
+                        for j in range(seg_end - 1, seg_start, -1):
+                            if messages[j].get("role") == "assistant":
+                                messages[j]["content"] = new_output
+                                break
+                    overridden_agents.add(id(agent))
+
+        earliest = min(task_overrides)
+        for offset, subsequent in enumerate(
+            crew.tasks[earliest + 1 :], start=earliest + 1
+        ):
+            if subsequent.output and offset not in task_overrides:
+                subsequent.output = None
+            if subsequent.agent and subsequent.agent.agent_executor:
+                subsequent.agent.agent_executor._resuming = False
+                if id(subsequent.agent) not in overridden_agents:
+                    subsequent.agent.agent_executor.messages = []
+        click.echo()
+
+    if inputs:
+        click.echo("Inputs:")
+        for k, v in inputs.items():
+            click.echo(f"  {k}: {v}")
+        click.echo()
+
+    result = await crew.akickoff(inputs=inputs)
     click.echo(f"\nResult: {getattr(result, 'raw', result)}")
 
 

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

@@ -392,10 +392,15 @@ def deploy() -> None:
 
 @deploy.command(name="create")
 @click.option("-y", "--yes", is_flag=True, help="Skip the confirmation prompt")
-def deploy_create(yes: bool) -> None:
+@click.option(
+    "--skip-validate",
+    is_flag=True,
+    help="Skip the pre-deploy validation checks.",
+)
+def deploy_create(yes: bool, skip_validate: bool) -> None:
     """Create a Crew deployment."""
     deploy_cmd = DeployCommand()
-    deploy_cmd.create_crew(yes)
+    deploy_cmd.create_crew(yes, skip_validate=skip_validate)
 
 
 @deploy.command(name="list")
@@ -407,10 +412,28 @@ def deploy_list() -> None:
 
 @deploy.command(name="push")
 @click.option("-u", "--uuid", type=str, help="Crew UUID parameter")
-def deploy_push(uuid: str | None) -> None:
+@click.option(
+    "--skip-validate",
+    is_flag=True,
+    help="Skip the pre-deploy validation checks.",
+)
+def deploy_push(uuid: str | None, skip_validate: bool) -> None:
     """Deploy the Crew."""
     deploy_cmd = DeployCommand()
-    deploy_cmd.deploy(uuid=uuid)
+    deploy_cmd.deploy(uuid=uuid, skip_validate=skip_validate)
+
+
+@deploy.command(name="validate")
+def deploy_validate() -> None:
+    """Validate the current project against common deployment failures.
+
+    Runs the same pre-deploy checks that `crewai deploy create` and
+    `crewai deploy push` run automatically, without contacting the platform.
+    Exits non-zero if any blocking issues are found.
+    """
+    from crewai.cli.deploy.validate import run_validate_command
+
+    run_validate_command()
 
 
 @deploy.command(name="status")
@@ -793,6 +816,9 @@ def traces_status() -> None:
 @click.pass_context
 def checkpoint(ctx: click.Context, location: str) -> None:
     """Browse and inspect checkpoints. Launches a TUI when called without a subcommand."""
+    from crewai.cli.checkpoint_cli import _detect_location
+
+    location = _detect_location(location)
     ctx.ensure_object(dict)
     ctx.obj["location"] = location
     if ctx.invoked_subcommand is None:
@@ -805,18 +831,18 @@ def checkpoint(ctx: click.Context, location: str) -> None:
 @click.argument("location", default="./.checkpoints")
 def checkpoint_list(location: str) -> None:
     """List checkpoints in a directory."""
-    from crewai.cli.checkpoint_cli import list_checkpoints
+    from crewai.cli.checkpoint_cli import _detect_location, list_checkpoints
 
-    list_checkpoints(location)
+    list_checkpoints(_detect_location(location))
 
 
 @checkpoint.command("info")
 @click.argument("path", default="./.checkpoints")
 def checkpoint_info(path: str) -> None:
     """Show details of a checkpoint. Pass a file or directory for latest."""
-    from crewai.cli.checkpoint_cli import info_checkpoint
+    from crewai.cli.checkpoint_cli import _detect_location, info_checkpoint
 
-    info_checkpoint(path)
+    info_checkpoint(_detect_location(path))
 
 
 if __name__ == "__main__":

lib/crewai/src/crewai/cli/crew_chat.py

@@ -13,7 +13,6 @@ from packaging import version
 import tomli
 
 from crewai.cli.utils import read_toml
-from crewai.cli.version import get_crewai_version
 from crewai.crew import Crew
 from crewai.llm import LLM
 from crewai.llms.base_llm import BaseLLM
@@ -21,6 +20,7 @@ from crewai.types.crew_chat import ChatInputField, ChatInputs
 from crewai.utilities.llm_utils import create_llm
 from crewai.utilities.printer import PRINTER
 from crewai.utilities.types import LLMMessage
+from crewai.utilities.version import get_crewai_version
 
 
 MIN_REQUIRED_VERSION: Final[Literal["0.98.0"]] = "0.98.0"

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

@@ -4,12 +4,35 @@ from rich.console import Console
 
 from crewai.cli import git
 from crewai.cli.command import BaseCommand, PlusAPIMixin
+from crewai.cli.deploy.validate import validate_project
 from crewai.cli.utils import fetch_and_json_env_file, get_project_name
 
 
 console = Console()
 
 
+def _run_predeploy_validation(skip_validate: bool) -> bool:
+    """Run pre-deploy validation unless skipped.
+
+    Returns True if deployment should proceed, False if it should abort.
+    """
+    if skip_validate:
+        console.print(
+            "[yellow]Skipping pre-deploy validation (--skip-validate).[/yellow]"
+        )
+        return True
+
+    console.print("Running pre-deploy validation...", style="bold blue")
+    validator = validate_project()
+    if not validator.ok:
+        console.print(
+            "\n[bold red]Pre-deploy validation failed. "
+            "Fix the issues above or re-run with --skip-validate.[/bold red]"
+        )
+        return False
+    return True
+
+
 class DeployCommand(BaseCommand, PlusAPIMixin):
     """
     A class to handle deployment-related operations for CrewAI projects.
@@ -60,13 +83,16 @@ class DeployCommand(BaseCommand, PlusAPIMixin):
                 f"{log_message['timestamp']} - {log_message['level']}: {log_message['message']}"
             )
 
-    def deploy(self, uuid: str | None = None) -> None:
+    def deploy(self, uuid: str | None = None, skip_validate: bool = False) -> None:
         """
         Deploy a crew using either UUID or project name.
 
         Args:
             uuid (Optional[str]): The UUID of the crew to deploy.
+            skip_validate (bool): Skip pre-deploy validation checks.
         """
+        if not _run_predeploy_validation(skip_validate):
+            return
         self._telemetry.start_deployment_span(uuid)
         console.print("Starting deployment...", style="bold blue")
         if uuid:
@@ -80,10 +106,16 @@ class DeployCommand(BaseCommand, PlusAPIMixin):
         self._validate_response(response)
         self._display_deployment_info(response.json())
 
-    def create_crew(self, confirm: bool = False) -> None:
+    def create_crew(self, confirm: bool = False, skip_validate: bool = False) -> None:
         """
         Create a new crew deployment.
+
+        Args:
+            confirm (bool): Whether to skip the interactive confirmation prompt.
+            skip_validate (bool): Skip pre-deploy validation checks.
         """
+        if not _run_predeploy_validation(skip_validate):
+            return
         self._telemetry.create_crew_deployment_span()
         console.print("Creating deployment...", style="bold blue")
         env_vars = fetch_and_json_env_file()

lib/crewai/src/crewai/cli/deploy/validate.py

@@ -0,0 +1,845 @@
+"""Pre-deploy validation for CrewAI projects.
+
+Catches locally what a deploy would reject at build or runtime so users
+don't burn deployment attempts on fixable project-structure problems.
+
+Each check is grouped into one of:
+- ERROR: will block a deployment; validator exits non-zero.
+- WARNING: may still deploy but is almost always a deployment bug; printed
+  but does not block.
+
+The individual checks mirror the categories observed in production
+deployment-failure logs:
+
+1. pyproject.toml present with ``[project].name``
+2. lockfile (``uv.lock`` or ``poetry.lock``) present and not stale
+3. package directory at ``src/<package>/`` exists (no empty name, no egg-info)
+4. standard crew files: ``crew.py``, ``config/agents.yaml``, ``config/tasks.yaml``
+5. flow entrypoint: ``main.py`` with a Flow subclass
+6. hatch wheel target resolves (packages = [...] or default dir matches name)
+7. crew/flow module imports cleanly (catches ``@CrewBase not found``,
+   ``No Flow subclass found``, provider import errors)
+8. environment variables referenced in code vs ``.env`` / deployment env
+9. installed crewai vs lockfile pin (catches missing-attribute failures from
+   stale pins)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+import json
+import logging
+import os
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import sys
+from typing import Any
+
+from rich.console import Console
+
+from crewai.cli.utils import parse_toml
+
+
+console = Console()
+logger = logging.getLogger(__name__)
+
+
+class Severity(str, Enum):
+    """Severity of a validation finding."""
+
+    ERROR = "error"
+    WARNING = "warning"
+
+
+@dataclass
+class ValidationResult:
+    """A single finding from a validation check.
+
+    Attributes:
+        severity: whether this blocks deploy or is advisory.
+        code: stable short identifier, used in tests and docs
+            (e.g. ``missing_pyproject``, ``stale_lockfile``).
+        title: one-line summary shown to the user.
+        detail: optional multi-line explanation.
+        hint: optional remediation suggestion.
+    """
+
+    severity: Severity
+    code: str
+    title: str
+    detail: str = ""
+    hint: str = ""
+
+
+# Maps known provider env var names → label used in hint messages.
+_KNOWN_API_KEY_HINTS: dict[str, str] = {
+    "OPENAI_API_KEY": "OpenAI",
+    "ANTHROPIC_API_KEY": "Anthropic",
+    "GOOGLE_API_KEY": "Google",
+    "GEMINI_API_KEY": "Gemini",
+    "AZURE_OPENAI_API_KEY": "Azure OpenAI",
+    "AZURE_API_KEY": "Azure",
+    "AWS_ACCESS_KEY_ID": "AWS",
+    "AWS_SECRET_ACCESS_KEY": "AWS",
+    "COHERE_API_KEY": "Cohere",
+    "GROQ_API_KEY": "Groq",
+    "MISTRAL_API_KEY": "Mistral",
+    "TAVILY_API_KEY": "Tavily",
+    "SERPER_API_KEY": "Serper",
+    "SERPLY_API_KEY": "Serply",
+    "PERPLEXITY_API_KEY": "Perplexity",
+    "DEEPSEEK_API_KEY": "DeepSeek",
+    "OPENROUTER_API_KEY": "OpenRouter",
+    "FIRECRAWL_API_KEY": "Firecrawl",
+    "EXA_API_KEY": "Exa",
+    "BROWSERBASE_API_KEY": "Browserbase",
+}
+
+
+def normalize_package_name(project_name: str) -> str:
+    """Normalize a pyproject project.name into a Python package directory name.
+
+    Mirrors the rules in ``crewai.cli.create_crew.create_crew`` so the
+    validator agrees with the scaffolder about where ``src/<pkg>/`` should
+    live.
+    """
+    folder = project_name.replace(" ", "_").replace("-", "_").lower()
+    return re.sub(r"[^a-zA-Z0-9_]", "", folder)
+
+
+class DeployValidator:
+    """Runs the full pre-deploy validation suite against a project directory."""
+
+    def __init__(self, project_root: Path | None = None) -> None:
+        self.project_root: Path = (project_root or Path.cwd()).resolve()
+        self.results: list[ValidationResult] = []
+        self._pyproject: dict[str, Any] | None = None
+        self._project_name: str | None = None
+        self._package_name: str | None = None
+        self._package_dir: Path | None = None
+        self._is_flow: bool = False
+
+    def _add(
+        self,
+        severity: Severity,
+        code: str,
+        title: str,
+        detail: str = "",
+        hint: str = "",
+    ) -> None:
+        self.results.append(
+            ValidationResult(
+                severity=severity,
+                code=code,
+                title=title,
+                detail=detail,
+                hint=hint,
+            )
+        )
+
+    @property
+    def errors(self) -> list[ValidationResult]:
+        return [r for r in self.results if r.severity is Severity.ERROR]
+
+    @property
+    def warnings(self) -> list[ValidationResult]:
+        return [r for r in self.results if r.severity is Severity.WARNING]
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+    def run(self) -> list[ValidationResult]:
+        """Run all checks. Later checks are skipped when earlier ones make
+        them impossible (e.g. no pyproject.toml → no lockfile check)."""
+        if not self._check_pyproject():
+            return self.results
+
+        self._check_lockfile()
+
+        if not self._check_package_dir():
+            self._check_hatch_wheel_target()
+            return self.results
+
+        if self._is_flow:
+            self._check_flow_entrypoint()
+        else:
+            self._check_crew_entrypoint()
+            self._check_config_yamls()
+
+        self._check_hatch_wheel_target()
+        self._check_module_imports()
+        self._check_env_vars()
+        self._check_version_vs_lockfile()
+
+        return self.results
+
+    def _check_pyproject(self) -> bool:
+        pyproject_path = self.project_root / "pyproject.toml"
+        if not pyproject_path.exists():
+            self._add(
+                Severity.ERROR,
+                "missing_pyproject",
+                "Cannot find pyproject.toml",
+                detail=(
+                    f"Expected pyproject.toml at {pyproject_path}. "
+                    "CrewAI projects must be installable Python packages."
+                ),
+                hint="Run `crewai create crew <name>` to scaffold a valid project layout.",
+            )
+            return False
+
+        try:
+            self._pyproject = parse_toml(pyproject_path.read_text())
+        except Exception as e:
+            self._add(
+                Severity.ERROR,
+                "invalid_pyproject",
+                "pyproject.toml is not valid TOML",
+                detail=str(e),
+            )
+            return False
+
+        project = self._pyproject.get("project") or {}
+        name = project.get("name")
+        if not isinstance(name, str) or not name.strip():
+            self._add(
+                Severity.ERROR,
+                "missing_project_name",
+                "pyproject.toml is missing [project].name",
+                detail=(
+                    "Without a project name the platform cannot resolve your "
+                    "package directory (this produces errors like "
+                    "'Cannot find src//crew.py')."
+                ),
+                hint='Set a `name = "..."` field under `[project]` in pyproject.toml.',
+            )
+            return False
+
+        self._project_name = name
+        self._package_name = normalize_package_name(name)
+        self._is_flow = (self._pyproject.get("tool") or {}).get("crewai", {}).get(
+            "type"
+        ) == "flow"
+        return True
+
+    def _check_lockfile(self) -> None:
+        uv_lock = self.project_root / "uv.lock"
+        poetry_lock = self.project_root / "poetry.lock"
+        pyproject = self.project_root / "pyproject.toml"
+
+        if not uv_lock.exists() and not poetry_lock.exists():
+            self._add(
+                Severity.ERROR,
+                "missing_lockfile",
+                "Expected to find at least one of these files: uv.lock or poetry.lock",
+                hint=(
+                    "Run `uv lock` (recommended) or `poetry lock` in your project "
+                    "directory, commit the lockfile, then redeploy."
+                ),
+            )
+            return
+
+        lockfile = uv_lock if uv_lock.exists() else poetry_lock
+        try:
+            if lockfile.stat().st_mtime < pyproject.stat().st_mtime:
+                self._add(
+                    Severity.WARNING,
+                    "stale_lockfile",
+                    f"{lockfile.name} is older than pyproject.toml",
+                    detail=(
+                        "Your lockfile may not reflect recent dependency changes. "
+                        "The platform resolves from the lockfile, so deployed "
+                        "dependencies may differ from local."
+                    ),
+                    hint="Run `uv lock` (or `poetry lock`) and commit the result.",
+                )
+        except OSError:
+            pass
+
+    def _check_package_dir(self) -> bool:
+        if self._package_name is None:
+            return False
+
+        src_dir = self.project_root / "src"
+        if not src_dir.is_dir():
+            self._add(
+                Severity.ERROR,
+                "missing_src_dir",
+                "Missing src/ directory",
+                detail=(
+                    "CrewAI deployments expect a src-layout project: "
+                    f"src/{self._package_name}/crew.py (or main.py for flows)."
+                ),
+                hint="Run `crewai create crew <name>` to see the expected layout.",
+            )
+            return False
+
+        package_dir = src_dir / self._package_name
+        if not package_dir.is_dir():
+            siblings = [
+                p.name
+                for p in src_dir.iterdir()
+                if p.is_dir() and not p.name.endswith(".egg-info")
+            ]
+            egg_info = [
+                p.name for p in src_dir.iterdir() if p.name.endswith(".egg-info")
+            ]
+
+            hint_parts = [
+                f'Create src/{self._package_name}/ to match [project].name = "{self._project_name}".'
+            ]
+            if siblings:
+                hint_parts.append(
+                    f"Found other package directories: {', '.join(siblings)}. "
+                    f"Either rename one to '{self._package_name}' or update [project].name."
+                )
+            if egg_info:
+                hint_parts.append(
+                    f"Delete stale build artifacts: {', '.join(egg_info)} "
+                    "(these confuse the platform's package discovery)."
+                )
+
+            self._add(
+                Severity.ERROR,
+                "missing_package_dir",
+                f"Cannot find src/{self._package_name}/",
+                detail=(
+                    "The platform looks for your crew source under "
+                    "src/<package_name>/, derived from [project].name."
+                ),
+                hint=" ".join(hint_parts),
+            )
+            return False
+
+        for p in src_dir.iterdir():
+            if p.name.endswith(".egg-info"):
+                self._add(
+                    Severity.WARNING,
+                    "stale_egg_info",
+                    f"Stale build artifact in src/: {p.name}",
+                    detail=(
+                        ".egg-info directories can be mistaken for your package "
+                        "and cause 'Cannot find src/<name>.egg-info/crew.py' errors."
+                    ),
+                    hint=f"Delete {p} and add `*.egg-info/` to .gitignore.",
+                )
+
+        self._package_dir = package_dir
+        return True
+
+    def _check_crew_entrypoint(self) -> None:
+        if self._package_dir is None:
+            return
+        crew_py = self._package_dir / "crew.py"
+        if not crew_py.is_file():
+            self._add(
+                Severity.ERROR,
+                "missing_crew_py",
+                f"Cannot find {crew_py.relative_to(self.project_root)}",
+                detail=(
+                    "Standard crew projects must define a Crew class decorated "
+                    "with @CrewBase inside crew.py."
+                ),
+                hint=(
+                    "Create crew.py with an @CrewBase-annotated class, or set "
+                    '`[tool.crewai] type = "flow"` in pyproject.toml if this is a flow.'
+                ),
+            )
+
+    def _check_config_yamls(self) -> None:
+        if self._package_dir is None:
+            return
+        config_dir = self._package_dir / "config"
+        if not config_dir.is_dir():
+            self._add(
+                Severity.ERROR,
+                "missing_config_dir",
+                f"Cannot find {config_dir.relative_to(self.project_root)}",
+                hint="Create a config/ directory with agents.yaml and tasks.yaml.",
+            )
+            return
+
+        for yaml_name in ("agents.yaml", "tasks.yaml"):
+            yaml_path = config_dir / yaml_name
+            if not yaml_path.is_file():
+                self._add(
+                    Severity.ERROR,
+                    f"missing_{yaml_name.replace('.', '_')}",
+                    f"Cannot find {yaml_path.relative_to(self.project_root)}",
+                    detail=(
+                        "CrewAI loads agent and task config from these files; "
+                        "missing them causes empty-config warnings and runtime crashes."
+                    ),
+                )
+
+    def _check_flow_entrypoint(self) -> None:
+        if self._package_dir is None:
+            return
+        main_py = self._package_dir / "main.py"
+        if not main_py.is_file():
+            self._add(
+                Severity.ERROR,
+                "missing_flow_main",
+                f"Cannot find {main_py.relative_to(self.project_root)}",
+                detail=(
+                    "Flow projects must define a Flow subclass in main.py. "
+                    'This project has `[tool.crewai] type = "flow"` set.'
+                ),
+                hint="Create main.py with a `class MyFlow(Flow[...])`.",
+            )
+
+    def _check_hatch_wheel_target(self) -> None:
+        if not self._pyproject:
+            return
+
+        build_system = self._pyproject.get("build-system") or {}
+        backend = build_system.get("build-backend", "")
+        if "hatchling" not in backend:
+            return
+
+        hatch_wheel = (
+            (self._pyproject.get("tool") or {})
+            .get("hatch", {})
+            .get("build", {})
+            .get("targets", {})
+            .get("wheel", {})
+        )
+        if hatch_wheel.get("packages") or hatch_wheel.get("only-include"):
+            return
+
+        if self._package_dir and self._package_dir.is_dir():
+            return
+
+        self._add(
+            Severity.ERROR,
+            "hatch_wheel_target_missing",
+            "Hatchling cannot determine which files to ship",
+            detail=(
+                "Your pyproject uses hatchling but has no "
+                "[tool.hatch.build.targets.wheel] configuration and no "
+                "directory matching your project name."
+            ),
+            hint=(
+                "Add:\n"
+                "  [tool.hatch.build.targets.wheel]\n"
+                f'  packages = ["src/{self._package_name}"]'
+            ),
+        )
+
+    def _check_module_imports(self) -> None:
+        """Import the user's crew/flow via `uv run` so the check sees the same
+        package versions as `crewai run` would. Result is reported as JSON on
+        the subprocess's stdout."""
+        script = (
+            "import json, sys, traceback, os\n"
+            "os.chdir(sys.argv[1])\n"
+            "try:\n"
+            "    from crewai.cli.utils import get_crews, get_flows\n"
+            "    is_flow = sys.argv[2] == 'flow'\n"
+            "    if is_flow:\n"
+            "        instances = get_flows()\n"
+            "        kind = 'flow'\n"
+            "    else:\n"
+            "        instances = get_crews()\n"
+            "        kind = 'crew'\n"
+            "    print(json.dumps({'ok': True, 'kind': kind, 'count': len(instances)}))\n"
+            "except BaseException as e:\n"
+            "    print(json.dumps({\n"
+            "        'ok': False,\n"
+            "        'error_type': type(e).__name__,\n"
+            "        'error': str(e),\n"
+            "        'traceback': traceback.format_exc(),\n"
+            "    }))\n"
+        )
+
+        uv_path = shutil.which("uv")
+        if uv_path is None:
+            self._add(
+                Severity.WARNING,
+                "uv_not_found",
+                "Skipping import check: `uv` not installed",
+                hint="Install uv: https://docs.astral.sh/uv/",
+            )
+            return
+
+        try:
+            proc = subprocess.run(  # noqa: S603 - args constructed from trusted inputs
+                [
+                    uv_path,
+                    "run",
+                    "python",
+                    "-c",
+                    script,
+                    str(self.project_root),
+                    "flow" if self._is_flow else "crew",
+                ],
+                cwd=self.project_root,
+                capture_output=True,
+                text=True,
+                timeout=120,
+                check=False,
+            )
+        except subprocess.TimeoutExpired:
+            self._add(
+                Severity.ERROR,
+                "import_timeout",
+                "Importing your crew/flow module timed out after 120s",
+                detail=(
+                    "User code may be making network calls or doing heavy work "
+                    "at import time. Move that work into agent methods."
+                ),
+            )
+            return
+
+        # The payload is the last JSON object on stdout; user code may print
+        # other lines before it.
+        payload: dict[str, Any] | None = None
+        for line in reversed(proc.stdout.splitlines()):
+            line = line.strip()
+            if line.startswith("{") and line.endswith("}"):
+                try:
+                    payload = json.loads(line)
+                    break
+                except json.JSONDecodeError:
+                    continue
+
+        if payload is None:
+            self._add(
+                Severity.ERROR,
+                "import_failed",
+                "Could not import your crew/flow module",
+                detail=(proc.stderr or proc.stdout or "").strip()[:1500],
+                hint="Run `crewai run` locally first to reproduce the error.",
+            )
+            return
+
+        if payload.get("ok"):
+            if payload.get("count", 0) == 0:
+                kind = payload.get("kind", "crew")
+                if kind == "flow":
+                    self._add(
+                        Severity.ERROR,
+                        "no_flow_subclass",
+                        "No Flow subclass found in the module",
+                        hint=(
+                            "main.py must define a class extending "
+                            "`crewai.flow.Flow`, instantiable with no arguments."
+                        ),
+                    )
+                else:
+                    self._add(
+                        Severity.ERROR,
+                        "no_crewbase_class",
+                        "Crew class annotated with @CrewBase not found",
+                        hint=(
+                            "Decorate your crew class with @CrewBase from "
+                            "crewai.project (see `crewai create crew` template)."
+                        ),
+                    )
+            return
+
+        err_msg = str(payload.get("error", ""))
+        err_type = str(payload.get("error_type", "Exception"))
+        tb = str(payload.get("traceback", ""))
+        self._classify_import_error(err_type, err_msg, tb)
+
+    def _classify_import_error(self, err_type: str, err_msg: str, tb: str) -> None:
+        """Turn a raw import-time exception into a user-actionable finding."""
+        # Must be checked before the generic "native provider" branch below:
+        # the extras-missing message contains the same phrase. Providers
+        # format the install command as plain text (`to install: uv add
+        # "crewai[extra]"`); also tolerate backtick-delimited variants.
+        m = re.search(
+            r"(?P<pkg>[A-Za-z0-9_ -]+?)\s+native provider not available"
+            r".*?to install:\s*`?(?P<cmd>uv add [\"']crewai\[[^\]]+\][\"'])`?",
+            err_msg,
+        )
+        if m:
+            self._add(
+                Severity.ERROR,
+                "missing_provider_extra",
+                f"{m.group('pkg').strip()} provider extra not installed",
+                hint=f"Run: {m.group('cmd')}",
+            )
+            return
+
+        # crewai.llm.LLM.__new__ wraps provider init errors as
+        # ImportError("Error importing native provider: ...").
+        if "Error importing native provider" in err_msg or "native provider" in err_msg:
+            missing_key = self._extract_missing_api_key(err_msg)
+            if missing_key:
+                provider = _KNOWN_API_KEY_HINTS.get(missing_key, missing_key)
+                self._add(
+                    Severity.WARNING,
+                    "llm_init_missing_key",
+                    f"LLM is constructed at import time but {missing_key} is not set",
+                    detail=(
+                        f"Your crew instantiates a {provider} LLM during module "
+                        "load (e.g. in a class field default or @crew method). "
+                        f"The {provider} provider currently requires {missing_key} "
+                        "at construction time, so this will fail on the platform "
+                        "unless the key is set in your deployment environment."
+                    ),
+                    hint=(
+                        f"Add {missing_key} to your deployment's Environment "
+                        "Variables before deploying, or move LLM construction "
+                        "inside agent methods so it runs lazily."
+                    ),
+                )
+                return
+            self._add(
+                Severity.ERROR,
+                "llm_provider_init_failed",
+                "LLM native provider failed to initialize",
+                detail=err_msg,
+                hint=(
+                    "Check your LLM(model=...) configuration and provider-specific "
+                    "extras (e.g. `uv add 'crewai[azure-ai-inference]'` for Azure)."
+                ),
+            )
+            return
+
+        if err_type == "KeyError":
+            key = err_msg.strip("'\"")
+            if key in _KNOWN_API_KEY_HINTS or key.endswith("_API_KEY"):
+                self._add(
+                    Severity.WARNING,
+                    "env_var_read_at_import",
+                    f"{key} is read at import time via os.environ[...]",
+                    detail=(
+                        "Using os.environ[...] (rather than os.getenv(...)) "
+                        "at module scope crashes the build if the key isn't set."
+                    ),
+                    hint=(
+                        f"Either add {key} as a deployment env var, or switch "
+                        "to os.getenv() and move the access inside agent methods."
+                    ),
+                )
+                return
+
+        if "Crew class annotated with @CrewBase not found" in err_msg:
+            self._add(
+                Severity.ERROR,
+                "no_crewbase_class",
+                "Crew class annotated with @CrewBase not found",
+                detail=err_msg,
+            )
+            return
+        if "No Flow subclass found" in err_msg:
+            self._add(
+                Severity.ERROR,
+                "no_flow_subclass",
+                "No Flow subclass found in the module",
+                detail=err_msg,
+            )
+            return
+
+        if (
+            err_type == "AttributeError"
+            and "has no attribute '_load_response_format'" in err_msg
+        ):
+            self._add(
+                Severity.ERROR,
+                "stale_crewai_pin",
+                "Your lockfile pins a crewai version missing `_load_response_format`",
+                detail=err_msg,
+                hint=(
+                    "Run `uv lock --upgrade-package crewai` (or `poetry update crewai`) "
+                    "to pin a newer release."
+                ),
+            )
+            return
+
+        if "pydantic" in tb.lower() or "validation error" in err_msg.lower():
+            self._add(
+                Severity.ERROR,
+                "pydantic_validation_error",
+                "Pydantic validation failed while loading your crew",
+                detail=err_msg[:800],
+                hint=(
+                    "Check agent/task configuration fields. `crewai run` locally "
+                    "will show the full traceback."
+                ),
+            )
+            return
+
+        self._add(
+            Severity.ERROR,
+            "import_failed",
+            f"Importing your crew failed: {err_type}",
+            detail=err_msg[:800],
+            hint="Run `crewai run` locally to see the full traceback.",
+        )
+
+    @staticmethod
+    def _extract_missing_api_key(err_msg: str) -> str | None:
+        """Pull 'FOO_API_KEY' out of '... FOO_API_KEY is required ...'."""
+        m = re.search(r"([A-Z][A-Z0-9_]*_API_KEY)\s+is required", err_msg)
+        if m:
+            return m.group(1)
+        m = re.search(r"['\"]([A-Z][A-Z0-9_]*_API_KEY)['\"]", err_msg)
+        if m:
+            return m.group(1)
+        return None
+
+    def _check_env_vars(self) -> None:
+        """Warn about env vars referenced in user code but missing locally.
+        Best-effort only — the platform sets vars server-side, so we never error.
+        """
+        if not self._package_dir:
+            return
+
+        referenced: set[str] = set()
+        pattern = re.compile(
+            r"""(?x)
+            (?:os\.environ\s*(?:\[\s*|\.get\s*\(\s*)
+              |os\.getenv\s*\(\s*
+              |getenv\s*\(\s*)
+            ['"]([A-Z][A-Z0-9_]*)['"]
+            """
+        )
+
+        for path in self._package_dir.rglob("*.py"):
+            try:
+                text = path.read_text(encoding="utf-8", errors="ignore")
+            except OSError:
+                continue
+            referenced.update(pattern.findall(text))
+
+        for path in self._package_dir.rglob("*.yaml"):
+            try:
+                text = path.read_text(encoding="utf-8", errors="ignore")
+            except OSError:
+                continue
+            referenced.update(re.findall(r"\$\{?([A-Z][A-Z0-9_]+)\}?", text))
+
+        env_file = self.project_root / ".env"
+        env_keys: set[str] = set()
+        if env_file.exists():
+            for line in env_file.read_text(errors="ignore").splitlines():
+                line = line.strip()
+                if not line or line.startswith("#") or "=" not in line:
+                    continue
+                env_keys.add(line.split("=", 1)[0].strip())
+
+        missing_known: list[str] = sorted(
+            var
+            for var in referenced
+            if var in _KNOWN_API_KEY_HINTS
+            and var not in env_keys
+            and var not in os.environ
+        )
+        if missing_known:
+            self._add(
+                Severity.WARNING,
+                "env_vars_not_in_dotenv",
+                f"{len(missing_known)} referenced API key(s) not in .env",
+                detail=(
+                    "These env vars are referenced in your source but not set "
+                    f"locally: {', '.join(missing_known)}. Deploys will fail "
+                    "unless they are added to the deployment's Environment "
+                    "Variables in the CrewAI dashboard."
+                ),
+            )
+
+    def _check_version_vs_lockfile(self) -> None:
+        """Warn when the lockfile pins a crewai release older than 1.13.0,
+        which is where ``_load_response_format`` was introduced.
+        """
+        uv_lock = self.project_root / "uv.lock"
+        poetry_lock = self.project_root / "poetry.lock"
+        lockfile = (
+            uv_lock
+            if uv_lock.exists()
+            else poetry_lock
+            if poetry_lock.exists()
+            else None
+        )
+        if lockfile is None:
+            return
+
+        try:
+            text = lockfile.read_text(errors="ignore")
+        except OSError:
+            return
+
+        m = re.search(
+            r'name\s*=\s*"crewai"\s*\nversion\s*=\s*"([^"]+)"',
+            text,
+        )
+        if not m:
+            return
+        locked = m.group(1)
+
+        try:
+            from packaging.version import Version
+
+            if Version(locked) < Version("1.13.0"):
+                self._add(
+                    Severity.WARNING,
+                    "old_crewai_pin",
+                    f"Lockfile pins crewai=={locked} (older than 1.13.0)",
+                    detail=(
+                        "Older pinned versions are missing API surface the "
+                        "platform builder expects (e.g. `_load_response_format`)."
+                    ),
+                    hint="Run `uv lock --upgrade-package crewai` and redeploy.",
+                )
+        except Exception as e:
+            logger.debug("Could not parse crewai pin from lockfile: %s", e)
+
+
+def render_report(results: list[ValidationResult]) -> None:
+    """Pretty-print results to the shared rich console."""
+    if not results:
+        console.print("[bold green]Pre-deploy validation passed.[/bold green]")
+        return
+
+    errors = [r for r in results if r.severity is Severity.ERROR]
+    warnings = [r for r in results if r.severity is Severity.WARNING]
+
+    for result in errors:
+        console.print(f"[bold red]ERROR[/bold red] [{result.code}] {result.title}")
+        if result.detail:
+            console.print(f"  {result.detail}")
+        if result.hint:
+            console.print(f"  [dim]hint:[/dim] {result.hint}")
+
+    for result in warnings:
+        console.print(
+            f"[bold yellow]WARNING[/bold yellow] [{result.code}] {result.title}"
+        )
+        if result.detail:
+            console.print(f"  {result.detail}")
+        if result.hint:
+            console.print(f"  [dim]hint:[/dim] {result.hint}")
+
+    summary_parts: list[str] = []
+    if errors:
+        summary_parts.append(f"[bold red]{len(errors)} error(s)[/bold red]")
+    if warnings:
+        summary_parts.append(f"[bold yellow]{len(warnings)} warning(s)[/bold yellow]")
+    console.print(f"\n{' / '.join(summary_parts)}")
+
+
+def validate_project(project_root: Path | None = None) -> DeployValidator:
+    """Entrypoint: run validation, render results, return the validator.
+
+    The caller inspects ``validator.ok`` to decide whether to proceed with a
+    deploy.
+    """
+    validator = DeployValidator(project_root=project_root)
+    validator.run()
+    render_report(validator.results)
+    return validator
+
+
+def run_validate_command() -> None:
+    """Implementation of `crewai deploy validate`."""
+    validator = validate_project()
+    if not validator.ok:
+        sys.exit(1)

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

@@ -7,7 +7,7 @@ from rich.console import Console
 from crewai.cli.authentication.main import Oauth2Settings, ProviderFactory
 from crewai.cli.command import BaseCommand
 from crewai.cli.settings.main import SettingsCommand
-from crewai.cli.version import get_crewai_version
+from crewai.utilities.version import get_crewai_version
 
 
 console = Console()

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

@@ -6,7 +6,7 @@ import httpx
 
 from crewai.cli.config import Settings
 from crewai.cli.constants import DEFAULT_CREWAI_ENTERPRISE_URL
-from crewai.cli.version import get_crewai_version
+from crewai.utilities.version import get_crewai_version
 
 
 class PlusAPI:

lib/crewai/src/crewai/cli/run_crew.py

@@ -5,7 +5,7 @@ import click
 from packaging import version
 
 from crewai.cli.utils import build_env_with_all_tool_credentials, read_toml
-from crewai.cli.version import get_crewai_version
+from crewai.utilities.version import get_crewai_version
 
 
 class CrewType(Enum):

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.14.2a1"
+    "crewai[tools]==1.14.2a4"
 ]
 
 [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.14.2a1"
+    "crewai[tools]==1.14.2a4"
 ]
 
 [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.14.2a1"
+    "crewai[tools]==1.14.2a4"
 ]
 
 [tool.crewai]

lib/crewai/src/crewai/cli/version.py

@@ -3,7 +3,6 @@
 from collections.abc import Mapping
 from datetime import datetime, timedelta
 from functools import lru_cache
-import importlib.metadata
 import json
 from pathlib import Path
 from typing import Any
@@ -13,6 +12,8 @@ from urllib.error import URLError
 import appdirs
 from packaging.version import InvalidVersion, Version, parse
 
+from crewai.utilities.version import get_crewai_version
+
 
 @lru_cache(maxsize=1)
 def _get_cache_file() -> Path:
@@ -25,11 +26,6 @@ def _get_cache_file() -> Path:
     return cache_dir / "version_cache.json"
 
 
-def get_crewai_version() -> str:
-    """Get the version number of CrewAI running the CLI."""
-    return importlib.metadata.version("crewai")
-
-
 def _is_cache_valid(cache_data: Mapping[str, Any]) -> bool:
     """Check if the cache is still valid, less than 24 hours old."""
     if "timestamp" not in cache_data:

lib/crewai/src/crewai/crew.py

@@ -42,7 +42,6 @@ if TYPE_CHECKING:
     from opentelemetry.trace import Span
 
     from crewai.context import ExecutionContext
-    from crewai.state.provider.core import BaseProvider
 
 try:
     from crewai_files import get_supported_content_types
@@ -104,7 +103,11 @@ from crewai.rag.types import SearchResult
 from crewai.security.fingerprint import Fingerprint
 from crewai.security.security_config import SecurityConfig
 from crewai.skills.models import Skill
-from crewai.state.checkpoint_config import CheckpointConfig, _coerce_checkpoint
+from crewai.state.checkpoint_config import (
+    CheckpointConfig,
+    _coerce_checkpoint,
+    apply_checkpoint,
+)
 from crewai.task import Task
 from crewai.tasks.conditional_task import ConditionalTask
 from crewai.tasks.task_output import TaskOutput
@@ -365,32 +368,21 @@ class Crew(FlowTrackable, BaseModel):
     checkpoint_kickoff_event_id: str | None = Field(default=None)
 
     @classmethod
-    def from_checkpoint(
-        cls, path: str, *, provider: BaseProvider | None = None
-    ) -> Crew:
-        """Restore a Crew from a checkpoint file, ready to resume via kickoff().
+    def from_checkpoint(cls, config: CheckpointConfig) -> Crew:
+        """Restore a Crew from a checkpoint, ready to resume via kickoff().
 
         Args:
-            path: Path to a checkpoint JSON file.
-            provider: Storage backend to read from. Defaults to JsonProvider.
+            config: Checkpoint configuration with ``restore_from`` set to
+                the path of the checkpoint to load.
 
         Returns:
             A Crew instance. Call kickoff() to resume from the last completed task.
         """
         from crewai.context import apply_execution_context
         from crewai.events.event_bus import crewai_event_bus
-        from crewai.state.provider.json_provider import JsonProvider
-        from crewai.state.provider.utils import detect_provider
         from crewai.state.runtime import RuntimeState
 
-        if provider is None:
-            provider = detect_provider(path)
-
-        state = RuntimeState.from_checkpoint(
-            path,
-            provider=provider or JsonProvider(),
-            context={"from_checkpoint": True},
-        )
+        state = RuntimeState.from_checkpoint(config, context={"from_checkpoint": True})
         crewai_event_bus.set_runtime_state(state)
         for entity in state.root:
             if isinstance(entity, cls):
@@ -398,7 +390,32 @@ class Crew(FlowTrackable, BaseModel):
                     apply_execution_context(entity.execution_context)
                 entity._restore_runtime()
                 return entity
-        raise ValueError(f"No Crew found in checkpoint: {path}")
+        raise ValueError(f"No Crew found in checkpoint: {config.restore_from}")
+
+    @classmethod
+    def fork(
+        cls,
+        config: CheckpointConfig,
+        branch: str | None = None,
+    ) -> Crew:
+        """Fork a Crew from a checkpoint, creating a new execution branch.
+
+        Args:
+            config: Checkpoint configuration with ``restore_from`` set.
+            branch: Branch label for the fork. Auto-generated if not provided.
+
+        Returns:
+            A Crew instance on the new branch. Call kickoff() to run.
+        """
+        crew = cls.from_checkpoint(config)
+        state = crewai_event_bus._runtime_state
+        if state is None:
+            raise RuntimeError(
+                "Cannot fork: no runtime state on the event bus. "
+                "Ensure from_checkpoint() succeeded before calling fork()."
+            )
+        state.fork(branch)
+        return crew
 
     def _restore_runtime(self) -> None:
         """Re-create runtime objects after restoring from a checkpoint."""
@@ -419,6 +436,13 @@ class Crew(FlowTrackable, BaseModel):
                         if agent.agent_executor is not None and task.output is None:
                             agent.agent_executor.task = task
                         break
+        for task in self.tasks:
+            if task.checkpoint_original_description is not None:
+                task._original_description = task.checkpoint_original_description
+            if task.checkpoint_original_expected_output is not None:
+                task._original_expected_output = (
+                    task.checkpoint_original_expected_output
+                )
         if self.checkpoint_inputs is not None:
             self._inputs = self.checkpoint_inputs
         if self.checkpoint_kickoff_event_id is not None:
@@ -854,16 +878,23 @@ class Crew(FlowTrackable, BaseModel):
         self,
         inputs: dict[str, Any] | None = None,
         input_files: dict[str, FileInput] | None = None,
+        from_checkpoint: CheckpointConfig | None = None,
     ) -> CrewOutput | CrewStreamingOutput:
         """Execute the crew's workflow.
 
         Args:
             inputs: Optional input dictionary for task interpolation.
             input_files: Optional dict of named file inputs for the crew.
+            from_checkpoint: Optional checkpoint config. If ``restore_from``
+                is set, the crew resumes from that checkpoint. Remaining
+                config fields enable checkpointing for the run.
 
         Returns:
             CrewOutput or CrewStreamingOutput if streaming is enabled.
         """
+        restored = apply_checkpoint(self, from_checkpoint)
+        if restored is not None:
+            return restored.kickoff(inputs=inputs, input_files=input_files)  # type: ignore[no-any-return]
         get_env_context()
         if self.stream:
             enable_agent_streaming(self.agents)
@@ -976,12 +1007,15 @@ class Crew(FlowTrackable, BaseModel):
         self,
         inputs: dict[str, Any] | None = None,
         input_files: dict[str, FileInput] | None = None,
+        from_checkpoint: CheckpointConfig | None = None,
     ) -> CrewOutput | CrewStreamingOutput:
         """Asynchronous kickoff method to start the crew execution.
 
         Args:
             inputs: Optional input dictionary for task interpolation.
             input_files: Optional dict of named file inputs for the crew.
+            from_checkpoint: Optional checkpoint config. If ``restore_from``
+                is set, the crew resumes from that checkpoint.
 
         Returns:
             CrewOutput or CrewStreamingOutput if streaming is enabled.
@@ -990,6 +1024,9 @@ class Crew(FlowTrackable, BaseModel):
         to get stream chunks. After iteration completes, access the final result
         via .result.
         """
+        restored = apply_checkpoint(self, from_checkpoint)
+        if restored is not None:
+            return await restored.kickoff_async(inputs=inputs, input_files=input_files)  # type: ignore[no-any-return]
         inputs = inputs or {}
 
         if self.stream:
@@ -1050,6 +1087,7 @@ class Crew(FlowTrackable, BaseModel):
         self,
         inputs: dict[str, Any] | None = None,
         input_files: dict[str, FileInput] | None = None,
+        from_checkpoint: CheckpointConfig | None = None,
     ) -> CrewOutput | CrewStreamingOutput:
         """Native async kickoff method using async task execution throughout.
 
@@ -1060,10 +1098,15 @@ class Crew(FlowTrackable, BaseModel):
         Args:
             inputs: Optional input dictionary for task interpolation.
             input_files: Optional dict of named file inputs for the crew.
+            from_checkpoint: Optional checkpoint config. If ``restore_from``
+                is set, the crew resumes from that checkpoint.
 
         Returns:
             CrewOutput or CrewStreamingOutput if streaming is enabled.
         """
+        restored = apply_checkpoint(self, from_checkpoint)
+        if restored is not None:
+            return await restored.akickoff(inputs=inputs, input_files=input_files)  # type: ignore[no-any-return]
         if self.stream:
             enable_agent_streaming(self.agents)
             ctx = StreamingContext(use_async=True)

lib/crewai/src/crewai/events/base_events.py

@@ -2,14 +2,56 @@ from collections.abc import Iterator
 import contextvars
 from datetime import datetime, timezone
 import itertools
-from typing import Any
+from typing import Any, TypedDict
 import uuid
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, SerializationInfo
 
 from crewai.utilities.serialization import Serializable, to_serializable
 
 
+def _is_trace_context(info: SerializationInfo) -> bool:
+    """Check if serialization is happening in trace context."""
+    return bool(info.context and info.context.get("trace"))
+
+
+class AgentRef(TypedDict):
+    id: str
+    role: str
+
+
+class TaskRef(TypedDict):
+    id: str
+    name: str
+
+
+def _trace_agent_ref(agent: Any) -> AgentRef | None:
+    """Return a lightweight agent reference for trace serialization."""
+    if agent is None:
+        return None
+    return AgentRef(
+        id=str(getattr(agent, "id", "")),
+        role=getattr(agent, "role", ""),
+    )
+
+
+def _trace_task_ref(task: Any) -> TaskRef | None:
+    """Return a lightweight task reference for trace serialization."""
+    if task is None:
+        return None
+    return TaskRef(
+        id=str(getattr(task, "id", "")),
+        name=str(getattr(task, "name", None) or getattr(task, "description", "")),
+    )
+
+
+def _trace_tool_names(tools: Any) -> list[str] | None:
+    """Return a list of tool names for trace serialization."""
+    if not tools:
+        return None
+    return [getattr(t, "name", str(t)) for t in tools]
+
+
 _emission_counter: contextvars.ContextVar[Iterator[int]] = contextvars.ContextVar(
     "_emission_counter"
 )

lib/crewai/src/crewai/events/listeners/tracing/trace_batch_manager.py

@@ -13,13 +13,13 @@ from crewai.cli.authentication.token import AuthError, get_auth_token
 from crewai.cli.config import Settings
 from crewai.cli.constants import DEFAULT_CREWAI_ENTERPRISE_URL
 from crewai.cli.plus_api import PlusAPI
-from crewai.cli.version import get_crewai_version
 from crewai.events.listeners.tracing.types import TraceEvent
 from crewai.events.listeners.tracing.utils import (
     get_user_id,
     is_tracing_enabled_in_context,
     should_auto_collect_first_time_traces,
 )
+from crewai.utilities.version import get_crewai_version
 
 
 logger = getLogger(__name__)

lib/crewai/src/crewai/events/listeners/tracing/trace_listener.py

@@ -1,13 +1,12 @@
 """Trace collection listener for orchestrating trace collection."""
 
 import os
-from typing import Any, ClassVar
+from typing import Any
 import uuid
 
 from typing_extensions import Self
 
 from crewai.cli.authentication.token import AuthError, get_auth_token
-from crewai.cli.version import get_crewai_version
 from crewai.events.base_event_listener import BaseEventListener
 from crewai.events.base_events import BaseEvent
 from crewai.events.event_bus import CrewAIEventsBus
@@ -127,20 +126,16 @@ from crewai.events.types.tool_usage_events import (
     ToolUsageStartedEvent,
 )
 from crewai.events.utils.console_formatter import ConsoleFormatter
+from crewai.utilities.version import get_crewai_version
+
+
+_TRACE_CONTEXT: dict[str, bool] = {"trace": True}
+"""Serialization context that triggers lightweight field serializers on event models."""
 
 
 class TraceCollectionListener(BaseEventListener):
     """Trace collection listener that orchestrates trace collection."""
 
-    complex_events: ClassVar[list[str]] = [
-        "task_started",
-        "task_completed",
-        "llm_call_started",
-        "llm_call_completed",
-        "agent_execution_started",
-        "agent_execution_completed",
-    ]
-
     _instance: Self | None = None
     _initialized: bool = False
     _listeners_setup: bool = False
@@ -824,9 +819,19 @@ class TraceCollectionListener(BaseEventListener):
     def _build_event_data(
         self, event_type: str, event: Any, source: Any
     ) -> dict[str, Any]:
-        """Build event data"""
-        if event_type not in self.complex_events:
-            return safe_serialize_to_dict(event)
+        """Build event data with context-based serialization to reduce trace bloat.
+
+        Field serializers on event models check for context={"trace": True} and
+        return lightweight references instead of full nested objects. This replaces
+        the old denylist approach with Pydantic v2's native context mechanism.
+
+        Only crew_kickoff_started gets a full crew structure (built separately).
+        Complex events (task_started, etc.) use custom projections for specific shapes.
+        All other events get context-aware serialization automatically.
+        """
+        if event_type == "crew_kickoff_started":
+            return self._build_crew_started_data(event)
+
         if event_type == "task_started":
             task_name = event.task.name or event.task.description
             task_display_name = (
@@ -867,19 +872,77 @@ class TraceCollectionListener(BaseEventListener):
                 "agent_backstory": event.agent.backstory,
             }
         if event_type == "llm_call_started":
-            event_data = safe_serialize_to_dict(event)
+            event_data = safe_serialize_to_dict(event, context=_TRACE_CONTEXT)
             event_data["task_name"] = event.task_name or getattr(
                 event, "task_description", None
             )
             return event_data
         if event_type == "llm_call_completed":
-            return safe_serialize_to_dict(event)
+            return safe_serialize_to_dict(event, context=_TRACE_CONTEXT)
 
-        return {
-            "event_type": event_type,
-            "event": safe_serialize_to_dict(event),
-            "source": source,
-        }
+        return safe_serialize_to_dict(event, context=_TRACE_CONTEXT)
+
+    def _build_crew_started_data(self, event: Any) -> dict[str, Any]:
+        """Build comprehensive crew structure for crew_kickoff_started event.
+
+        This is the ONE place where we serialize the full crew structure.
+        Subsequent events use lightweight references via field serializers.
+        """
+        event_data = safe_serialize_to_dict(event, context=_TRACE_CONTEXT)
+
+        crew = getattr(event, "crew", None)
+        if crew is not None:
+            agents_data = []
+            for agent in getattr(crew, "agents", []) or []:
+                agent_data = {
+                    "id": str(getattr(agent, "id", "")),
+                    "role": getattr(agent, "role", ""),
+                    "goal": getattr(agent, "goal", ""),
+                    "backstory": getattr(agent, "backstory", ""),
+                    "verbose": getattr(agent, "verbose", False),
+                    "allow_delegation": getattr(agent, "allow_delegation", False),
+                    "max_iter": getattr(agent, "max_iter", None),
+                    "max_rpm": getattr(agent, "max_rpm", None),
+                }
+                tools = getattr(agent, "tools", None)
+                if tools:
+                    agent_data["tool_names"] = [
+                        getattr(t, "name", str(t)) for t in tools
+                    ]
+                agents_data.append(agent_data)
+
+            tasks_data = []
+            for task in getattr(crew, "tasks", []) or []:
+                task_data = {
+                    "id": str(getattr(task, "id", "")),
+                    "name": getattr(task, "name", None),
+                    "description": getattr(task, "description", ""),
+                    "expected_output": getattr(task, "expected_output", ""),
+                    "async_execution": getattr(task, "async_execution", False),
+                    "human_input": getattr(task, "human_input", False),
+                }
+                task_agent = getattr(task, "agent", None)
+                if task_agent:
+                    task_data["agent_ref"] = {
+                        "id": str(getattr(task_agent, "id", "")),
+                        "role": getattr(task_agent, "role", ""),
+                    }
+                context_tasks = getattr(task, "context", None)
+                if context_tasks:
+                    task_data["context_task_ids"] = [
+                        str(getattr(ct, "id", "")) for ct in context_tasks
+                    ]
+                tasks_data.append(task_data)
+
+            event_data["crew_structure"] = {
+                "agents": agents_data,
+                "tasks": tasks_data,
+                "process": str(getattr(crew, "process", "")),
+                "verbose": getattr(crew, "verbose", False),
+                "memory": getattr(crew, "memory", False),
+            }
+
+        return event_data
 
     def _show_tracing_disabled_message(self) -> None:
         """Show a message when tracing is disabled."""

lib/crewai/src/crewai/events/listeners/tracing/utils.py

@@ -429,10 +429,22 @@ def mark_first_execution_done(user_consented: bool = False) -> None:
         p.write_text(json.dumps(data, indent=2))
 
 
-def safe_serialize_to_dict(obj: Any, exclude: set[str] | None = None) -> dict[str, Any]:
-    """Safely serialize an object to a dictionary for event data."""
+def safe_serialize_to_dict(
+    obj: Any,
+    exclude: set[str] | None = None,
+    context: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Safely serialize an object to a dictionary for event data.
+
+    Args:
+        obj: Object to serialize.
+        exclude: Set of keys to exclude from the result.
+        context: Optional context dict passed through to Pydantic's model_dump().
+            Field serializers can inspect this to customize output
+            (e.g. context={"trace": True} for lightweight trace serialization).
+    """
     try:
-        serialized = to_serializable(obj, exclude)
+        serialized = to_serializable(obj, exclude, context=context)
         if isinstance(serialized, dict):
             return serialized
         return {"serialized_data": serialized}

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

@@ -5,11 +5,17 @@ from __future__ import annotations
 from collections.abc import Sequence
 from typing import Any, Literal
 
-from pydantic import ConfigDict, model_validator
+from pydantic import ConfigDict, SerializationInfo, field_serializer, model_validator
 from typing_extensions import Self
 
 from crewai.agents.agent_builder.base_agent import BaseAgent
-from crewai.events.base_events import BaseEvent
+from crewai.events.base_events import (
+    BaseEvent,
+    _is_trace_context,
+    _trace_agent_ref,
+    _trace_task_ref,
+    _trace_tool_names,
+)
 from crewai.tools.base_tool import BaseTool
 from crewai.tools.structured_tool import CrewStructuredTool
 
@@ -31,6 +37,21 @@ class AgentExecutionStartedEvent(BaseEvent):
         _set_agent_fingerprint(self, self.agent)
         return self
 
+    @field_serializer("agent")
+    @classmethod
+    def _serialize_agent(cls, v: Any, info: SerializationInfo) -> Any:
+        return _trace_agent_ref(v) if _is_trace_context(info) else v
+
+    @field_serializer("task")
+    @classmethod
+    def _serialize_task(cls, v: Any, info: SerializationInfo) -> Any:
+        return _trace_task_ref(v) if _is_trace_context(info) else v
+
+    @field_serializer("tools")
+    @classmethod
+    def _serialize_tools(cls, v: Any, info: SerializationInfo) -> Any:
+        return _trace_tool_names(v) if _is_trace_context(info) else v
+
 
 class AgentExecutionCompletedEvent(BaseEvent):
     """Event emitted when an agent completes executing a task"""
@@ -48,6 +69,16 @@ class AgentExecutionCompletedEvent(BaseEvent):
         _set_agent_fingerprint(self, self.agent)
         return self
 
+    @field_serializer("agent")
+    @classmethod
+    def _serialize_agent(cls, v: Any, info: SerializationInfo) -> Any:
+        return _trace_agent_ref(v) if _is_trace_context(info) else v
+
+    @field_serializer("task")
+    @classmethod
+    def _serialize_task(cls, v: Any, info: SerializationInfo) -> Any:
+        return _trace_task_ref(v) if _is_trace_context(info) else v
+
 
 class AgentExecutionErrorEvent(BaseEvent):
     """Event emitted when an agent encounters an error during execution"""
@@ -65,6 +96,16 @@ class AgentExecutionErrorEvent(BaseEvent):
         _set_agent_fingerprint(self, self.agent)
         return self
 
+    @field_serializer("agent")
+    @classmethod
+    def _serialize_agent(cls, v: Any, info: SerializationInfo) -> Any:
+        return _trace_agent_ref(v) if _is_trace_context(info) else v
+
+    @field_serializer("task")
+    @classmethod
+    def _serialize_task(cls, v: Any, info: SerializationInfo) -> Any:
+        return _trace_task_ref(v) if _is_trace_context(info) else v
+
 
 # New event classes for LiteAgent
 class LiteAgentExecutionStartedEvent(BaseEvent):
@@ -77,6 +118,11 @@ class LiteAgentExecutionStartedEvent(BaseEvent):
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
+    @field_serializer("tools")
+    @classmethod
+    def _serialize_tools(cls, v: Any, info: SerializationInfo) -> Any:
+        return _trace_tool_names(v) if _is_trace_context(info) else v
+
 
 class LiteAgentExecutionCompletedEvent(BaseEvent):
     """Event emitted when a LiteAgent completes execution"""

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

@@ -1,6 +1,8 @@
 from typing import TYPE_CHECKING, Any, Literal
 
-from crewai.events.base_events import BaseEvent
+from pydantic import SerializationInfo, field_serializer
+
+from crewai.events.base_events import BaseEvent, _is_trace_context
 
 
 if TYPE_CHECKING:
@@ -26,6 +28,14 @@ class CrewBaseEvent(BaseEvent):
             if self.crew.fingerprint.metadata:
                 self.fingerprint_metadata = self.crew.fingerprint.metadata
 
+    @field_serializer("crew")
+    @classmethod
+    def _serialize_crew(cls, v: Any, info: SerializationInfo) -> Any:
+        """Exclude crew in trace context — crew_kickoff_started builds structure separately."""
+        if _is_trace_context(info):
+            return None
+        return v
+
     def to_json(self, exclude: set[str] | None = None) -> Any:
         if exclude is None:
             exclude = set()

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

@@ -1,9 +1,9 @@
 from enum import Enum
 from typing import Any, Literal
 
-from pydantic import BaseModel
+from pydantic import BaseModel, SerializationInfo, field_serializer
 
-from crewai.events.base_events import BaseEvent
+from crewai.events.base_events import BaseEvent, _is_trace_context
 
 
 class LLMEventBase(BaseEvent):
@@ -49,6 +49,16 @@ class LLMCallStartedEvent(LLMEventBase):
     callbacks: list[Any] | None = None
     available_functions: dict[str, Any] | None = None
 
+    @field_serializer("callbacks")
+    @classmethod
+    def _serialize_callbacks(cls, v: Any, info: SerializationInfo) -> Any:
+        return None if _is_trace_context(info) else v
+
+    @field_serializer("available_functions")
+    @classmethod
+    def _serialize_available_functions(cls, v: Any, info: SerializationInfo) -> Any:
+        return None if _is_trace_context(info) else v
+
 
 class LLMCallCompletedEvent(LLMEventBase):
     """Event emitted when a LLM call completes"""

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

@@ -1,6 +1,8 @@
 from typing import Any, Literal
 
-from crewai.events.base_events import BaseEvent
+from pydantic import SerializationInfo, field_serializer
+
+from crewai.events.base_events import BaseEvent, _is_trace_context, _trace_task_ref
 from crewai.tasks.task_output import TaskOutput
 
 
@@ -32,6 +34,11 @@ class TaskStartedEvent(BaseEvent):
         super().__init__(**data)
         _set_task_fingerprint(self, self.task)
 
+    @field_serializer("task")
+    @classmethod
+    def _serialize_task(cls, v: Any, info: SerializationInfo) -> Any:
+        return _trace_task_ref(v) if _is_trace_context(info) else v
+
 
 class TaskCompletedEvent(BaseEvent):
     """Event emitted when a task completes"""
@@ -44,6 +51,11 @@ class TaskCompletedEvent(BaseEvent):
         super().__init__(**data)
         _set_task_fingerprint(self, self.task)
 
+    @field_serializer("task")
+    @classmethod
+    def _serialize_task(cls, v: Any, info: SerializationInfo) -> Any:
+        return _trace_task_ref(v) if _is_trace_context(info) else v
+
 
 class TaskFailedEvent(BaseEvent):
     """Event emitted when a task fails"""
@@ -56,6 +68,11 @@ class TaskFailedEvent(BaseEvent):
         super().__init__(**data)
         _set_task_fingerprint(self, self.task)
 
+    @field_serializer("task")
+    @classmethod
+    def _serialize_task(cls, v: Any, info: SerializationInfo) -> Any:
+        return _trace_task_ref(v) if _is_trace_context(info) else v
+
 
 class TaskEvaluationEvent(BaseEvent):
     """Event emitted when a task evaluation is completed"""
@@ -67,3 +84,8 @@ class TaskEvaluationEvent(BaseEvent):
     def __init__(self, **data: Any) -> None:
         super().__init__(**data)
         _set_task_fingerprint(self, self.task)
+
+    @field_serializer("task")
+    @classmethod
+    def _serialize_task(cls, v: Any, info: SerializationInfo) -> Any:
+        return _trace_task_ref(v) if _is_trace_context(info) else v

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

@@ -2,9 +2,9 @@ from collections.abc import Callable
 from datetime import datetime
 from typing import Any, Literal
 
-from pydantic import ConfigDict
+from pydantic import ConfigDict, SerializationInfo, field_serializer
 
-from crewai.events.base_events import BaseEvent
+from crewai.events.base_events import BaseEvent, _is_trace_context, _trace_agent_ref
 
 
 class ToolUsageEvent(BaseEvent):
@@ -26,6 +26,11 @@ class ToolUsageEvent(BaseEvent):
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
+    @field_serializer("agent")
+    @classmethod
+    def _serialize_agent(cls, v: Any, info: SerializationInfo) -> Any:
+        return _trace_agent_ref(v) if _is_trace_context(info) else v
+
     def __init__(self, **data: Any) -> None:
         if data.get("from_task"):
             task = data["from_task"]
@@ -99,6 +104,11 @@ class ToolExecutionErrorEvent(BaseEvent):
     tool_class: Callable[..., Any]
     agent: Any | None = None
 
+    @field_serializer("agent")
+    @classmethod
+    def _serialize_agent(cls, v: Any, info: SerializationInfo) -> Any:
+        return _trace_agent_ref(v) if _is_trace_context(info) else v
+
     def __init__(self, **data: Any) -> None:
         super().__init__(**data)
         # Set fingerprint data from the agent

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

@@ -113,7 +113,11 @@ from crewai.flow.utils import (
 )
 from crewai.memory.memory_scope import MemoryScope, MemorySlice
 from crewai.memory.unified_memory import Memory
-from crewai.state.checkpoint_config import CheckpointConfig, _coerce_checkpoint
+from crewai.state.checkpoint_config import (
+    CheckpointConfig,
+    _coerce_checkpoint,
+    apply_checkpoint,
+)
 
 
 if TYPE_CHECKING:
@@ -122,7 +126,6 @@ if TYPE_CHECKING:
     from crewai.context import ExecutionContext
     from crewai.flow.async_feedback.types import PendingFeedbackContext
     from crewai.llms.base_llm import BaseLLM
-    from crewai.state.provider.core import BaseProvider
 
 from crewai.flow.visualization import build_flow_structure, render_interactive
 from crewai.types.streaming import CrewStreamingOutput, FlowStreamingOutput
@@ -928,20 +931,21 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
     ] = Field(default=None)
 
     @classmethod
-    def from_checkpoint(
-        cls, path: str, *, provider: BaseProvider | None = None
-    ) -> Flow:  # type: ignore[type-arg]
-        """Restore a Flow from a checkpoint file."""
+    def from_checkpoint(cls, config: CheckpointConfig) -> Flow:  # type: ignore[type-arg]
+        """Restore a Flow from a checkpoint.
+
+        Args:
+            config: Checkpoint configuration with ``restore_from`` set to
+                the path of the checkpoint to load.
+
+        Returns:
+            A Flow instance ready to resume.
+        """
         from crewai.context import apply_execution_context
         from crewai.events.event_bus import crewai_event_bus
-        from crewai.state.provider.json_provider import JsonProvider
         from crewai.state.runtime import RuntimeState
 
-        state = RuntimeState.from_checkpoint(
-            path,
-            provider=provider or JsonProvider(),
-            context={"from_checkpoint": True},
-        )
+        state = RuntimeState.from_checkpoint(config, context={"from_checkpoint": True})
         crewai_event_bus.set_runtime_state(state)
         for entity in state.root:
             if not isinstance(entity, Flow):
@@ -958,7 +962,32 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
             instance.checkpoint_state = entity.checkpoint_state
             instance._restore_from_checkpoint()
             return instance
-        raise ValueError(f"No Flow found in checkpoint: {path}")
+        raise ValueError(f"No Flow found in checkpoint: {config.restore_from}")
+
+    @classmethod
+    def fork(
+        cls,
+        config: CheckpointConfig,
+        branch: str | None = None,
+    ) -> Flow:  # type: ignore[type-arg]
+        """Fork a Flow from a checkpoint, creating a new execution branch.
+
+        Args:
+            config: Checkpoint configuration with ``restore_from`` set.
+            branch: Branch label for the fork. Auto-generated if not provided.
+
+        Returns:
+            A Flow instance on the new branch. Call kickoff() to run.
+        """
+        flow = cls.from_checkpoint(config)
+        state = crewai_event_bus._runtime_state
+        if state is None:
+            raise RuntimeError(
+                "Cannot fork: no runtime state on the event bus. "
+                "Ensure from_checkpoint() succeeded before calling fork()."
+            )
+        state.fork(branch)
+        return flow
 
     checkpoint_completed_methods: set[str] | None = Field(default=None)
     checkpoint_method_outputs: list[Any] | None = Field(default=None)
@@ -1956,6 +1985,7 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
         self,
         inputs: dict[str, Any] | None = None,
         input_files: dict[str, FileInput] | None = None,
+        from_checkpoint: CheckpointConfig | None = None,
     ) -> Any | FlowStreamingOutput:
         """Start the flow execution in a synchronous context.
 
@@ -1965,10 +1995,15 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
         Args:
             inputs: Optional dictionary containing input values and/or a state ID.
             input_files: Optional dict of named file inputs for the flow.
+            from_checkpoint: Optional checkpoint config. If ``restore_from``
+                is set, the flow resumes from that checkpoint.
 
         Returns:
             The final output from the flow or FlowStreamingOutput if streaming.
         """
+        restored = apply_checkpoint(self, from_checkpoint)
+        if restored is not None:
+            return restored.kickoff(inputs=inputs, input_files=input_files)
         get_env_context()
         if self.stream:
             result_holder: list[Any] = []
@@ -2025,6 +2060,7 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
         self,
         inputs: dict[str, Any] | None = None,
         input_files: dict[str, FileInput] | None = None,
+        from_checkpoint: CheckpointConfig | None = None,
     ) -> Any | FlowStreamingOutput:
         """Start the flow execution asynchronously.
 
@@ -2036,10 +2072,15 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
         Args:
             inputs: Optional dictionary containing input values and/or a state ID for restoration.
             input_files: Optional dict of named file inputs for the flow.
+            from_checkpoint: Optional checkpoint config. If ``restore_from``
+                is set, the flow resumes from that checkpoint.
 
         Returns:
             The final output from the flow, which is the result of the last executed method.
         """
+        restored = apply_checkpoint(self, from_checkpoint)
+        if restored is not None:
+            return await restored.kickoff_async(inputs=inputs, input_files=input_files)
         if self.stream:
             result_holder: list[Any] = []
             current_task_info: TaskInfo = {
@@ -2298,17 +2339,20 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
         self,
         inputs: dict[str, Any] | None = None,
         input_files: dict[str, FileInput] | None = None,
+        from_checkpoint: CheckpointConfig | None = None,
     ) -> Any | FlowStreamingOutput:
         """Native async method to start the flow execution. Alias for kickoff_async.
 
         Args:
             inputs: Optional dictionary containing input values and/or a state ID for restoration.
             input_files: Optional dict of named file inputs for the flow.
+            from_checkpoint: Optional checkpoint config. If ``restore_from``
+                is set, the flow resumes from that checkpoint.
 
         Returns:
             The final output from the flow, which is the result of the last executed method.
         """
-        return await self.kickoff_async(inputs, input_files)
+        return await self.kickoff_async(inputs, input_files, from_checkpoint)
 
     async def _execute_start_method(self, start_method_name: FlowMethodName) -> None:
         """Executes a flow's start method and its triggered listeners.

lib/crewai/src/crewai/lite_agent.py

@@ -16,7 +16,6 @@ from typing import (
     get_origin,
 )
 import uuid
-import warnings
 
 from pydantic import (
     UUID4,
@@ -26,7 +25,7 @@ from pydantic import (
     field_validator,
     model_validator,
 )
-from typing_extensions import Self
+from typing_extensions import Self, deprecated
 
 
 if TYPE_CHECKING:
@@ -173,9 +172,12 @@ def _kickoff_with_a2a_support(
     )
 
 
+@deprecated(
+    "LiteAgent is deprecated and will be removed in v2.0.0.",
+    category=FutureWarning,
+)
 class LiteAgent(FlowTrackable, BaseModel):
-    """
-    A lightweight agent that can process messages and use tools.
+    """A lightweight agent that can process messages and use tools.
 
     .. deprecated::
         LiteAgent is deprecated and will be removed in a future version.
@@ -278,18 +280,6 @@ class LiteAgent(FlowTrackable, BaseModel):
     )
     _memory: Any = PrivateAttr(default=None)
 
-    @model_validator(mode="after")
-    def emit_deprecation_warning(self) -> Self:
-        """Emit deprecation warning for LiteAgent usage."""
-        warnings.warn(
-            "LiteAgent is deprecated and will be removed in a future version. "
-            "Use Agent().kickoff(messages) instead, which provides the same "
-            "functionality with additional features like memory and knowledge support.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self
-
     @model_validator(mode="after")
     def setup_llm(self) -> Self:
         """Set up the LLM and other components after initialization."""

lib/crewai/src/crewai/llm.py

@@ -51,6 +51,7 @@ from crewai.utilities.exceptions.context_window_exceeding_exception import (
 )
 from crewai.utilities.logger_utils import suppress_warnings
 from crewai.utilities.string_utils import sanitize_tool_name
+from crewai.utilities.token_counter_callback import TokenCalcHandler
 
 
 try:
@@ -75,8 +76,13 @@ try:
     from litellm.types.utils import (
         ChatCompletionDeltaToolCall,
         Choices,
+        Delta as LiteLLMDelta,
         Function,
+        Message,
         ModelResponse,
+        ModelResponseBase,
+        ModelResponseStream,
+        StreamingChoices as LiteLLMStreamingChoices,
     )
     from litellm.utils import supports_response_schema
 
@@ -85,6 +91,11 @@ except ImportError:
     LITELLM_AVAILABLE = False
     litellm = None  # type: ignore[assignment]
     Choices = None  # type: ignore[assignment, misc]
+    LiteLLMDelta = None  # type: ignore[assignment, misc]
+    Message = None  # type: ignore[assignment, misc]
+    ModelResponseBase = None  # type: ignore[assignment, misc]
+    ModelResponseStream = None  # type: ignore[assignment, misc]
+    LiteLLMStreamingChoices = None  # type: ignore[assignment, misc]
     get_supported_openai_params = None  # type: ignore[assignment]
     ChatCompletionDeltaToolCall = None  # type: ignore[assignment, misc]
     Function = None  # type: ignore[assignment, misc]
@@ -709,7 +720,7 @@ class LLM(BaseLLM):
                 chunk_content = None
                 response_id = None
 
-                if hasattr(chunk, "id"):
+                if isinstance(chunk, ModelResponseBase):
                     response_id = chunk.id
 
                 # Safely extract content from various chunk formats
@@ -718,18 +729,16 @@ class LLM(BaseLLM):
                     choices = None
                     if isinstance(chunk, dict) and "choices" in chunk:
                         choices = chunk["choices"]
-                    elif hasattr(chunk, "choices"):
-                        # Check if choices is not a type but an actual attribute with value
-                        if not isinstance(chunk.choices, type):
-                            choices = chunk.choices
+                    elif isinstance(chunk, ModelResponseStream):
+                        choices = chunk.choices
 
                     # Try to extract usage information if available
+                    # NOTE: usage is a pydantic extra field on ModelResponseBase,
+                    # so it must be accessed via model_extra.
                     if isinstance(chunk, dict) and "usage" in chunk:
                         usage_info = chunk["usage"]
-                    elif hasattr(chunk, "usage"):
-                        # Check if usage is not a type but an actual attribute with value
-                        if not isinstance(chunk.usage, type):
-                            usage_info = chunk.usage
+                    elif isinstance(chunk, ModelResponseBase) and chunk.model_extra:
+                        usage_info = chunk.model_extra.get("usage") or usage_info
 
                     if choices and len(choices) > 0:
                         choice = choices[0]
@@ -738,7 +747,7 @@ class LLM(BaseLLM):
                         delta = None
                         if isinstance(choice, dict) and "delta" in choice:
                             delta = choice["delta"]
-                        elif hasattr(choice, "delta"):
+                        elif isinstance(choice, LiteLLMStreamingChoices):
                             delta = choice.delta
 
                         # Extract content from delta
@@ -748,7 +757,7 @@ class LLM(BaseLLM):
                                 if "content" in delta and delta["content"] is not None:
                                     chunk_content = delta["content"]
                             # Handle object format
-                            elif hasattr(delta, "content"):
+                            elif isinstance(delta, LiteLLMDelta):
                                 chunk_content = delta.content
 
                             # Handle case where content might be None or empty
@@ -821,9 +830,8 @@ class LLM(BaseLLM):
                         choices = None
                         if isinstance(last_chunk, dict) and "choices" in last_chunk:
                             choices = last_chunk["choices"]
-                        elif hasattr(last_chunk, "choices"):
-                            if not isinstance(last_chunk.choices, type):
-                                choices = last_chunk.choices
+                        elif isinstance(last_chunk, ModelResponseStream):
+                            choices = last_chunk.choices
 
                         if choices and len(choices) > 0:
                             choice = choices[0]
@@ -832,14 +840,14 @@ class LLM(BaseLLM):
                             message = None
                             if isinstance(choice, dict) and "message" in choice:
                                 message = choice["message"]
-                            elif hasattr(choice, "message"):
+                            elif isinstance(choice, Choices):
                                 message = choice.message
 
                             if message:
                                 content = None
                                 if isinstance(message, dict) and "content" in message:
                                     content = message["content"]
-                                elif hasattr(message, "content"):
+                                elif isinstance(message, Message):
                                     content = message.content
 
                                 if content:
@@ -866,24 +874,23 @@ class LLM(BaseLLM):
                     choices = None
                     if isinstance(last_chunk, dict) and "choices" in last_chunk:
                         choices = last_chunk["choices"]
-                    elif hasattr(last_chunk, "choices"):
-                        if not isinstance(last_chunk.choices, type):
-                            choices = last_chunk.choices
+                    elif isinstance(last_chunk, ModelResponseStream):
+                        choices = last_chunk.choices
 
                     if choices and len(choices) > 0:
                         choice = choices[0]
 
-                        message = None
-                        if isinstance(choice, dict) and "message" in choice:
-                            message = choice["message"]
-                        elif hasattr(choice, "message"):
-                            message = choice.message
+                        delta = None
+                        if isinstance(choice, dict) and "delta" in choice:
+                            delta = choice["delta"]
+                        elif isinstance(choice, LiteLLMStreamingChoices):
+                            delta = choice.delta
 
-                        if message:
-                            if isinstance(message, dict) and "tool_calls" in message:
-                                tool_calls = message["tool_calls"]
-                            elif hasattr(message, "tool_calls"):
-                                tool_calls = message.tool_calls
+                        if delta:
+                            if isinstance(delta, dict) and "tool_calls" in delta:
+                                tool_calls = delta["tool_calls"]
+                            elif isinstance(delta, LiteLLMDelta):
+                                tool_calls = delta.tool_calls
             except Exception as e:
                 logging.debug(f"Error checking for tool calls: {e}")
 
@@ -1037,7 +1044,7 @@ class LLM(BaseLLM):
         """
         if callbacks and len(callbacks) > 0:
             for callback in callbacks:
-                if hasattr(callback, "log_success_event"):
+                if isinstance(callback, TokenCalcHandler):
                     # Use the usage_info we've been tracking
                     if not usage_info:
                         # Try to get usage from the last chunk if we haven't already
@@ -1048,9 +1055,14 @@ class LLM(BaseLLM):
                                     and "usage" in last_chunk
                                 ):
                                     usage_info = last_chunk["usage"]
-                                elif hasattr(last_chunk, "usage"):
-                                    if not isinstance(last_chunk.usage, type):
-                                        usage_info = last_chunk.usage
+                                elif (
+                                    isinstance(last_chunk, ModelResponseBase)
+                                    and last_chunk.model_extra
+                                ):
+                                    usage_info = (
+                                        last_chunk.model_extra.get("usage")
+                                        or usage_info
+                                    )
                         except Exception as e:
                             logging.debug(f"Error extracting usage info: {e}")
 
@@ -1123,13 +1135,10 @@ class LLM(BaseLLM):
                 params["response_model"] = response_model
             response = litellm.completion(**params)
 
-            if (
-                hasattr(response, "usage")
-                and not isinstance(response.usage, type)
-                and response.usage
-            ):
-                usage_info = response.usage
-                self._track_token_usage_internal(usage_info)
+            if isinstance(response, ModelResponseBase) and response.model_extra:
+                usage_info = response.model_extra.get("usage")
+                if usage_info:
+                    self._track_token_usage_internal(usage_info)
 
         except LLMContextLengthExceededError:
             # Re-raise our own context length error
@@ -1141,7 +1150,11 @@ class LLM(BaseLLM):
                 raise LLMContextLengthExceededError(error_msg) from e
             raise
 
-        response_usage = self._usage_to_dict(getattr(response, "usage", None))
+        response_usage = self._usage_to_dict(
+            response.model_extra.get("usage")
+            if isinstance(response, ModelResponseBase) and response.model_extra
+            else None
+        )
 
         # --- 2) Handle structured output response (when response_model is provided)
         if response_model is not None:
@@ -1166,8 +1179,13 @@ class LLM(BaseLLM):
         # --- 3) Handle callbacks with usage info
         if callbacks and len(callbacks) > 0:
             for callback in callbacks:
-                if hasattr(callback, "log_success_event"):
-                    usage_info = getattr(response, "usage", None)
+                if isinstance(callback, TokenCalcHandler):
+                    usage_info = (
+                        response.model_extra.get("usage")
+                        if isinstance(response, ModelResponseBase)
+                        and response.model_extra
+                        else None
+                    )
                     if usage_info:
                         callback.log_success_event(
                             kwargs=params,
@@ -1176,7 +1194,7 @@ class LLM(BaseLLM):
                             end_time=0,
                         )
         # --- 4) Check for tool calls
-        tool_calls = getattr(response_message, "tool_calls", [])
+        tool_calls = response_message.tool_calls or []
 
         # --- 5) If no tool calls or no available functions, return the text response directly as long as there is a text response
         if (not tool_calls or not available_functions) and text_response:
@@ -1269,13 +1287,10 @@ class LLM(BaseLLM):
                 params["response_model"] = response_model
             response = await litellm.acompletion(**params)
 
-            if (
-                hasattr(response, "usage")
-                and not isinstance(response.usage, type)
-                and response.usage
-            ):
-                usage_info = response.usage
-                self._track_token_usage_internal(usage_info)
+            if isinstance(response, ModelResponseBase) and response.model_extra:
+                usage_info = response.model_extra.get("usage")
+                if usage_info:
+                    self._track_token_usage_internal(usage_info)
 
         except LLMContextLengthExceededError:
             # Re-raise our own context length error
@@ -1287,7 +1302,11 @@ class LLM(BaseLLM):
                 raise LLMContextLengthExceededError(error_msg) from e
             raise
 
-        response_usage = self._usage_to_dict(getattr(response, "usage", None))
+        response_usage = self._usage_to_dict(
+            response.model_extra.get("usage")
+            if isinstance(response, ModelResponseBase) and response.model_extra
+            else None
+        )
 
         if response_model is not None:
             if isinstance(response, BaseModel):
@@ -1309,8 +1328,13 @@ class LLM(BaseLLM):
 
         if callbacks and len(callbacks) > 0:
             for callback in callbacks:
-                if hasattr(callback, "log_success_event"):
-                    usage_info = getattr(response, "usage", None)
+                if isinstance(callback, TokenCalcHandler):
+                    usage_info = (
+                        response.model_extra.get("usage")
+                        if isinstance(response, ModelResponseBase)
+                        and response.model_extra
+                        else None
+                    )
                     if usage_info:
                         callback.log_success_event(
                             kwargs=params,
@@ -1319,7 +1343,7 @@ class LLM(BaseLLM):
                             end_time=0,
                         )
 
-        tool_calls = getattr(response_message, "tool_calls", [])
+        tool_calls = response_message.tool_calls or []
 
         if (not tool_calls or not available_functions) and text_response:
             self._handle_emit_call_events(
@@ -1394,18 +1418,19 @@ class LLM(BaseLLM):
             async for chunk in await litellm.acompletion(**params):
                 chunk_count += 1
                 chunk_content = None
-                response_id = chunk.id if hasattr(chunk, "id") else None
+                response_id = chunk.id if isinstance(chunk, ModelResponseBase) else None
 
                 try:
                     choices = None
                     if isinstance(chunk, dict) and "choices" in chunk:
                         choices = chunk["choices"]
-                    elif hasattr(chunk, "choices"):
-                        if not isinstance(chunk.choices, type):
-                            choices = chunk.choices
+                    elif isinstance(chunk, ModelResponseStream):
+                        choices = chunk.choices
 
-                    if hasattr(chunk, "usage") and chunk.usage is not None:
-                        usage_info = chunk.usage
+                    if isinstance(chunk, ModelResponseBase) and chunk.model_extra:
+                        chunk_usage = chunk.model_extra.get("usage")
+                        if chunk_usage is not None:
+                            usage_info = chunk_usage
 
                     if choices and len(choices) > 0:
                         first_choice = choices[0]
@@ -1413,19 +1438,19 @@ class LLM(BaseLLM):
 
                         if isinstance(first_choice, dict):
                             delta = first_choice.get("delta", {})
-                        elif hasattr(first_choice, "delta"):
+                        elif isinstance(first_choice, LiteLLMStreamingChoices):
                             delta = first_choice.delta
 
                         if delta:
                             if isinstance(delta, dict):
                                 chunk_content = delta.get("content")
-                            elif hasattr(delta, "content"):
+                            elif isinstance(delta, LiteLLMDelta):
                                 chunk_content = delta.content
 
                             tool_calls: list[ChatCompletionDeltaToolCall] | None = None
                             if isinstance(delta, dict):
                                 tool_calls = delta.get("tool_calls")
-                            elif hasattr(delta, "tool_calls"):
+                            elif isinstance(delta, LiteLLMDelta):
                                 tool_calls = delta.tool_calls
 
                             if tool_calls:
@@ -1461,7 +1486,7 @@ class LLM(BaseLLM):
 
             if callbacks and len(callbacks) > 0 and usage_info:
                 for callback in callbacks:
-                    if hasattr(callback, "log_success_event"):
+                    if isinstance(callback, TokenCalcHandler):
                         callback.log_success_event(
                             kwargs=params,
                             response_obj={"usage": usage_info},
@@ -1920,7 +1945,7 @@ class LLM(BaseLLM):
             return None
         if isinstance(usage, dict):
             return usage
-        if hasattr(usage, "model_dump"):
+        if isinstance(usage, BaseModel):
             result: dict[str, Any] = usage.model_dump()
             return result
         if hasattr(usage, "__dict__"):
@@ -1984,7 +2009,7 @@ class LLM(BaseLLM):
                 )
             return messages
 
-        provider = getattr(self, "provider", None) or self.model
+        provider = self.provider or self.model
 
         for msg in messages:
             files = msg.get("files")
@@ -2035,7 +2060,7 @@ class LLM(BaseLLM):
                 )
             return messages
 
-        provider = getattr(self, "provider", None) or self.model
+        provider = self.provider or self.model
 
         for msg in messages:
             files = msg.get("files")

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

@@ -172,6 +172,8 @@ class BaseLLM(BaseModel, ABC):
             "completion_tokens": 0,
             "successful_requests": 0,
             "cached_prompt_tokens": 0,
+            "reasoning_tokens": 0,
+            "cache_creation_tokens": 0,
         }
     )
 
@@ -808,14 +810,24 @@ class BaseLLM(BaseModel, ABC):
         cached_tokens = (
             usage_data.get("cached_tokens")
             or usage_data.get("cached_prompt_tokens")
+            or usage_data.get("cache_read_input_tokens")
             or 0
         )
+        if not cached_tokens:
+            prompt_details = usage_data.get("prompt_tokens_details")
+            if isinstance(prompt_details, dict):
+                cached_tokens = prompt_details.get("cached_tokens", 0) or 0
+
+        reasoning_tokens = usage_data.get("reasoning_tokens", 0) or 0
+        cache_creation_tokens = usage_data.get("cache_creation_tokens", 0) or 0
 
         self._token_usage["prompt_tokens"] += prompt_tokens
         self._token_usage["completion_tokens"] += completion_tokens
         self._token_usage["total_tokens"] += prompt_tokens + completion_tokens
         self._token_usage["successful_requests"] += 1
         self._token_usage["cached_prompt_tokens"] += cached_tokens
+        self._token_usage["reasoning_tokens"] += reasoning_tokens
+        self._token_usage["cache_creation_tokens"] += cache_creation_tokens
 
     def get_token_usage_summary(self) -> UsageMetrics:
         """Get summary of token usage for this LLM instance.

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

@@ -11,10 +11,14 @@ from crewai.events.types.llm_events import LLMCallType
 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.llms.providers.utils.common import safe_tool_conversion
 from crewai.utilities.agent_utils import is_context_length_exceeded
 from crewai.utilities.exceptions.context_window_exceeding_exception import (
     LLMContextLengthExceededError,
 )
+from crewai.utilities.pydantic_schema_utils import (
+    sanitize_tool_params_for_anthropic_strict,
+)
 from crewai.utilities.types import LLMMessage
 
 
@@ -189,16 +193,41 @@ class AnthropicCompletion(BaseLLM):
 
     @model_validator(mode="after")
     def _init_clients(self) -> AnthropicCompletion:
-        self._client = Anthropic(**self._get_client_params())
+        """Eagerly build clients when the API key is available, otherwise
+        defer so ``LLM(model="anthropic/...")`` can be constructed at module
+        import time even before deployment env vars are set.
+        """
+        try:
+            self._client = self._build_sync_client()
+            self._async_client = self._build_async_client()
+        except ValueError:
+            pass
+        return self
 
-        async_client_params = self._get_client_params()
+    def _build_sync_client(self) -> Any:
+        return Anthropic(**self._get_client_params())
+
+    def _build_async_client(self) -> Any:
+        # Skip the sync httpx.Client that `_get_client_params` would
+        # otherwise construct under `interceptor`; we attach an async one
+        # below and would leak the sync one if both were built.
+        async_client_params = self._get_client_params(include_http_client=False)
         if self.interceptor:
             async_transport = AsyncHTTPTransport(interceptor=self.interceptor)
-            async_http_client = httpx.AsyncClient(transport=async_transport)
-            async_client_params["http_client"] = async_http_client
+            async_client_params["http_client"] = httpx.AsyncClient(
+                transport=async_transport
+            )
+        return AsyncAnthropic(**async_client_params)
 
-        self._async_client = AsyncAnthropic(**async_client_params)
-        return self
+    def _get_sync_client(self) -> Any:
+        if self._client is None:
+            self._client = self._build_sync_client()
+        return self._client
+
+    def _get_async_client(self) -> Any:
+        if self._async_client is None:
+            self._async_client = self._build_async_client()
+        return self._async_client
 
     def to_config_dict(self) -> dict[str, Any]:
         """Extend base config with Anthropic-specific fields."""
@@ -213,8 +242,15 @@ class AnthropicCompletion(BaseLLM):
             config["timeout"] = self.timeout
         return config
 
-    def _get_client_params(self) -> dict[str, Any]:
-        """Get client parameters."""
+    def _get_client_params(self, include_http_client: bool = True) -> dict[str, Any]:
+        """Get client parameters.
+
+        Args:
+            include_http_client: When True (default) and an interceptor is
+                set, attach a sync ``httpx.Client``. The async builder
+                passes ``False`` so it can attach its own async client
+                without leaking a sync one.
+        """
 
         if self.api_key is None:
             self.api_key = os.getenv("ANTHROPIC_API_KEY")
@@ -228,7 +264,7 @@ class AnthropicCompletion(BaseLLM):
             "max_retries": self.max_retries,
         }
 
-        if self.interceptor:
+        if include_http_client and self.interceptor:
             transport = HTTPTransport(interceptor=self.interceptor)
             http_client = httpx.Client(transport=transport)
             client_params["http_client"] = http_client  # type: ignore[assignment]
@@ -473,10 +509,8 @@ class AnthropicCompletion(BaseLLM):
                 continue
 
             try:
-                from crewai.llms.providers.utils.common import safe_tool_conversion
-
                 name, description, parameters = safe_tool_conversion(tool, "Anthropic")
-            except (ImportError, KeyError, ValueError) as e:
+            except (KeyError, ValueError) as e:
                 logging.error(f"Error converting tool to Anthropic format: {e}")
                 raise e
 
@@ -485,8 +519,15 @@ class AnthropicCompletion(BaseLLM):
                 "description": description,
             }
 
+            func_info = tool.get("function", {})
+            strict_enabled = bool(func_info.get("strict"))
+
             if parameters and isinstance(parameters, dict):
-                anthropic_tool["input_schema"] = parameters
+                anthropic_tool["input_schema"] = (
+                    sanitize_tool_params_for_anthropic_strict(parameters)
+                    if strict_enabled
+                    else parameters
+                )
             else:
                 anthropic_tool["input_schema"] = {
                     "type": "object",
@@ -494,6 +535,9 @@ class AnthropicCompletion(BaseLLM):
                     "required": [],
                 }
 
+            if strict_enabled:
+                anthropic_tool["strict"] = True
+
             anthropic_tools.append(anthropic_tool)
 
         return anthropic_tools
@@ -786,11 +830,11 @@ class AnthropicCompletion(BaseLLM):
         try:
             if betas:
                 params["betas"] = betas
-                response = self._client.beta.messages.create(
+                response = self._get_sync_client().beta.messages.create(
                     **params, extra_body=extra_body
                 )
             else:
-                response = self._client.messages.create(**params)
+                response = self._get_sync_client().messages.create(**params)
 
         except Exception as e:
             if is_context_length_exceeded(e):
@@ -938,9 +982,11 @@ 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._get_sync_client().beta.messages.stream(
+                **stream_params, extra_body=extra_body
+            )
             if betas
-            else self._client.messages.stream(**stream_params)
+            else self._get_sync_client().messages.stream(**stream_params)
         )
         with stream_context as stream:
             response_id = None
@@ -1219,7 +1265,9 @@ 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._get_sync_client().messages.create(
+                **follow_up_params
+            )
 
             # Track token usage for follow-up call
             follow_up_usage = self._extract_anthropic_token_usage(final_response)
@@ -1315,11 +1363,11 @@ class AnthropicCompletion(BaseLLM):
         try:
             if betas:
                 params["betas"] = betas
-                response = await self._async_client.beta.messages.create(
+                response = await self._get_async_client().beta.messages.create(
                     **params, extra_body=extra_body
                 )
             else:
-                response = await self._async_client.messages.create(**params)
+                response = await self._get_async_client().messages.create(**params)
 
         except Exception as e:
             if is_context_length_exceeded(e):
@@ -1453,11 +1501,11 @@ class AnthropicCompletion(BaseLLM):
         current_tool_calls: dict[int, dict[str, Any]] = {}
 
         stream_context = (
-            self._async_client.beta.messages.stream(
+            self._get_async_client().beta.messages.stream(
                 **stream_params, extra_body=extra_body
             )
             if betas
-            else self._async_client.messages.stream(**stream_params)
+            else self._get_async_client().messages.stream(**stream_params)
         )
         async with stream_context as stream:
             response_id = None
@@ -1622,7 +1670,7 @@ class AnthropicCompletion(BaseLLM):
         ]
 
         try:
-            final_response: Message = await self._async_client.messages.create(
+            final_response: Message = await self._get_async_client().messages.create(
                 **follow_up_params
             )
 
@@ -1704,18 +1752,23 @@ class AnthropicCompletion(BaseLLM):
     def _extract_anthropic_token_usage(
         response: Message | BetaMessage,
     ) -> dict[str, Any]:
-        """Extract token usage from Anthropic response."""
+        """Extract token usage and response metadata from Anthropic response."""
         if hasattr(response, "usage") and response.usage:
             usage = response.usage
             input_tokens = getattr(usage, "input_tokens", 0)
             output_tokens = getattr(usage, "output_tokens", 0)
             cache_read_tokens = getattr(usage, "cache_read_input_tokens", 0) or 0
-            return {
+            cache_creation_tokens = (
+                getattr(usage, "cache_creation_input_tokens", 0) or 0
+            )
+            result: dict[str, Any] = {
                 "input_tokens": input_tokens,
                 "output_tokens": output_tokens,
                 "total_tokens": input_tokens + output_tokens,
                 "cached_prompt_tokens": cache_read_tokens,
+                "cache_creation_tokens": cache_creation_tokens,
             }
+            return result
         return {"total_tokens": 0}
 
     def supports_multimodal(self) -> bool:
@@ -1745,8 +1798,8 @@ class AnthropicCompletion(BaseLLM):
             from crewai_files.uploaders.anthropic import AnthropicFileUploader
 
             return AnthropicFileUploader(
-                client=self._client,
-                async_client=self._async_client,
+                client=self._get_sync_client(),
+                async_client=self._get_async_client(),
             )
         except ImportError:
             return None

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

@@ -116,43 +116,100 @@ class AzureCompletion(BaseLLM):
             data.get("api_version") or os.getenv("AZURE_API_VERSION") or "2024-06-01"
         )
 
-        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 data["endpoint"]:
-            raise ValueError(
-                "Azure endpoint is required. Set AZURE_ENDPOINT environment variable or pass endpoint parameter."
-            )
-
+        # Credentials and endpoint are validated lazily in `_init_clients`
+        # so the LLM can be constructed before deployment env vars are set.
         model = data.get("model", "")
-        data["endpoint"] = AzureCompletion._validate_and_fix_endpoint(
-            data["endpoint"], model
+        if data["endpoint"]:
+            data["endpoint"] = AzureCompletion._validate_and_fix_endpoint(
+                data["endpoint"], model
+            )
+        data["is_azure_openai_endpoint"] = AzureCompletion._is_azure_openai_endpoint(
+            data["endpoint"]
         )
         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
 
+    @staticmethod
+    def _is_azure_openai_endpoint(endpoint: str | None) -> bool:
+        if not endpoint:
+            return False
+        hostname = urlparse(endpoint).hostname or ""
+        return (
+            hostname == "openai.azure.com" or hostname.endswith(".openai.azure.com")
+        ) and "/openai/deployments/" in endpoint
+
     @model_validator(mode="after")
     def _init_clients(self) -> AzureCompletion:
+        """Eagerly build clients when credentials are available, otherwise
+        defer so ``LLM(model="azure/...")`` can be constructed at module
+        import time even before deployment env vars are set.
+        """
+        try:
+            self._client = self._build_sync_client()
+            self._async_client = self._build_async_client()
+        except ValueError:
+            pass
+        return self
+
+    def _build_sync_client(self) -> Any:
+        return ChatCompletionsClient(**self._make_client_kwargs())
+
+    def _build_async_client(self) -> Any:
+        return AsyncChatCompletionsClient(**self._make_client_kwargs())
+
+    def _make_client_kwargs(self) -> dict[str, Any]:
+        # Re-read env vars so that a deferred build can pick up credentials
+        # that weren't set at instantiation time (e.g. LLM constructed at
+        # module import before deployment env vars were injected).
         if not self.api_key:
-            raise ValueError("Azure API key is required.")
+            self.api_key = os.getenv("AZURE_API_KEY")
+        if not self.endpoint:
+            endpoint = (
+                os.getenv("AZURE_ENDPOINT")
+                or os.getenv("AZURE_OPENAI_ENDPOINT")
+                or os.getenv("AZURE_API_BASE")
+            )
+            if endpoint:
+                self.endpoint = AzureCompletion._validate_and_fix_endpoint(
+                    endpoint, self.model
+                )
+                # Recompute the routing flag now that the endpoint is known —
+                # _prepare_completion_params uses it to decide whether to
+                # include `model` in the request body (Azure OpenAI endpoints
+                # embed the deployment name in the URL and reject it).
+                self.is_azure_openai_endpoint = (
+                    AzureCompletion._is_azure_openai_endpoint(self.endpoint)
+                )
+
+        if not self.api_key:
+            raise ValueError(
+                "Azure API key is required. Set AZURE_API_KEY environment "
+                "variable or pass api_key parameter."
+            )
+        if not self.endpoint:
+            raise ValueError(
+                "Azure endpoint is required. Set AZURE_ENDPOINT environment "
+                "variable or pass endpoint parameter."
+            )
         client_kwargs: dict[str, Any] = {
             "endpoint": self.endpoint,
             "credential": AzureKeyCredential(self.api_key),
         }
         if self.api_version:
             client_kwargs["api_version"] = self.api_version
+        return client_kwargs
 
-        self._client = ChatCompletionsClient(**client_kwargs)
-        self._async_client = AsyncChatCompletionsClient(**client_kwargs)
-        return self
+    def _get_sync_client(self) -> Any:
+        if self._client is None:
+            self._client = self._build_sync_client()
+        return self._client
+
+    def _get_async_client(self) -> Any:
+        if self._async_client is None:
+            self._async_client = self._build_async_client()
+        return self._async_client
 
     def to_config_dict(self) -> dict[str, Any]:
         """Extend base config with Azure-specific fields."""
@@ -713,8 +770,7 @@ class AzureCompletion(BaseLLM):
     ) -> str | Any:
         """Handle non-streaming chat completion."""
         try:
-            # Cast params to Any to avoid type checking issues with TypedDict unpacking
-            response: ChatCompletions = self._client.complete(**params)
+            response: ChatCompletions = self._get_sync_client().complete(**params)
             return self._process_completion_response(
                 response=response,
                 params=params,
@@ -913,7 +969,7 @@ class AzureCompletion(BaseLLM):
         tool_calls: dict[int, dict[str, Any]] = {}
 
         usage_data: dict[str, Any] | None = None
-        for update in self._client.complete(**params):
+        for update in self._get_sync_client().complete(**params):
             if isinstance(update, StreamingChatCompletionsUpdate):
                 if update.usage:
                     usage = update.usage
@@ -953,8 +1009,9 @@ class AzureCompletion(BaseLLM):
     ) -> str | Any:
         """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)
+            response: ChatCompletions = await self._get_async_client().complete(
+                **params
+            )
             return self._process_completion_response(
                 response=response,
                 params=params,
@@ -980,7 +1037,7 @@ class AzureCompletion(BaseLLM):
 
         usage_data: dict[str, Any] | None = None
 
-        stream = await self._async_client.complete(**params)
+        stream = await self._get_async_client().complete(**params)
         async for update in stream:
             if isinstance(update, StreamingChatCompletionsUpdate):
                 if hasattr(update, "usage") and update.usage:
@@ -1076,28 +1133,39 @@ class AzureCompletion(BaseLLM):
 
     @staticmethod
     def _extract_azure_token_usage(response: ChatCompletions) -> dict[str, Any]:
-        """Extract token usage from Azure response."""
+        """Extract token usage and response metadata from Azure response."""
         if hasattr(response, "usage") and response.usage:
             usage = response.usage
             cached_tokens = 0
             prompt_details = getattr(usage, "prompt_tokens_details", None)
             if prompt_details:
                 cached_tokens = getattr(prompt_details, "cached_tokens", 0) or 0
-            return {
+            reasoning_tokens = 0
+            completion_details = getattr(usage, "completion_tokens_details", None)
+            if completion_details:
+                reasoning_tokens = (
+                    getattr(completion_details, "reasoning_tokens", 0) or 0
+                )
+            result: dict[str, Any] = {
                 "prompt_tokens": getattr(usage, "prompt_tokens", 0),
                 "completion_tokens": getattr(usage, "completion_tokens", 0),
                 "total_tokens": getattr(usage, "total_tokens", 0),
                 "cached_prompt_tokens": cached_tokens,
+                "reasoning_tokens": reasoning_tokens,
             }
+            return result
         return {"total_tokens": 0}
 
     async def aclose(self) -> None:
         """Close the async client and clean up resources.
 
         This ensures proper cleanup of the underlying aiohttp session
-        to avoid unclosed connector warnings.
+        to avoid unclosed connector warnings. Accesses the cached client
+        directly rather than going through `_get_async_client` so a
+        cleanup on an uninitialized LLM is a harmless no-op rather than
+        a credential-required error.
         """
-        if hasattr(self._async_client, "close"):
+        if self._async_client is not None and hasattr(self._async_client, "close"):
             await self._async_client.close()
 
     async def __aenter__(self) -> Self:

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

@@ -12,6 +12,7 @@ from typing_extensions import Required
 
 from crewai.events.types.llm_events import LLMCallType
 from crewai.llms.base_llm import BaseLLM, llm_call_context
+from crewai.llms.providers.utils.common import safe_tool_conversion
 from crewai.utilities.agent_utils import is_context_length_exceeded
 from crewai.utilities.exceptions.context_window_exceeding_exception import (
     LLMContextLengthExceededError,
@@ -302,6 +303,22 @@ class BedrockCompletion(BaseLLM):
 
     @model_validator(mode="after")
     def _init_clients(self) -> BedrockCompletion:
+        """Eagerly build the sync client when AWS credentials resolve,
+        otherwise defer so ``LLM(model="bedrock/...")`` can be constructed
+        at module import time even before deployment env vars are set.
+
+        Only credential/SDK errors are caught — programming errors like
+        ``TypeError`` or ``AttributeError`` propagate so real bugs aren't
+        silently swallowed.
+        """
+        try:
+            self._client = self._build_sync_client()
+        except (BotoCoreError, ClientError, ValueError) as e:
+            logging.debug("Deferring Bedrock client construction: %s", e)
+        self._async_exit_stack = AsyncExitStack() if AIOBOTOCORE_AVAILABLE else None
+        return self
+
+    def _build_sync_client(self) -> Any:
         config = Config(
             read_timeout=300,
             retries={"max_attempts": 3, "mode": "adaptive"},
@@ -313,9 +330,17 @@ class BedrockCompletion(BaseLLM):
             aws_session_token=self.aws_session_token,
             region_name=self.region_name,
         )
-        self._client = session.client("bedrock-runtime", config=config)
-        self._async_exit_stack = AsyncExitStack() if AIOBOTOCORE_AVAILABLE else None
-        return self
+        return session.client("bedrock-runtime", config=config)
+
+    def _get_sync_client(self) -> Any:
+        if self._client is None:
+            self._client = self._build_sync_client()
+        return self._client
+
+    def _get_async_client(self) -> Any:
+        """Async client is set up separately by ``_ensure_async_client``
+        using ``aiobotocore`` inside an exit stack."""
+        return self._async_client
 
     def to_config_dict(self) -> dict[str, Any]:
         """Extend base config with Bedrock-specific fields."""
@@ -655,7 +680,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._get_sync_client().converse(
                 modelId=self.model_id,
                 messages=cast(
                     "Sequence[MessageTypeDef | MessageOutputTypeDef]",
@@ -944,7 +969,7 @@ class BedrockCompletion(BaseLLM):
         usage_data: dict[str, Any] | None = None
 
         try:
-            response = self._client.converse_stream(
+            response = self._get_sync_client().converse_stream(
                 modelId=self.model_id,
                 messages=cast(
                     "Sequence[MessageTypeDef | MessageOutputTypeDef]",
@@ -1948,8 +1973,6 @@ class BedrockCompletion(BaseLLM):
         tools: list[dict[str, Any]],
     ) -> list[ConverseToolTypeDef]:
         """Convert CrewAI tools to Converse API format following AWS specification."""
-        from crewai.llms.providers.utils.common import safe_tool_conversion
-
         converse_tools: list[ConverseToolTypeDef] = []
 
         for tool in tools:
@@ -2025,11 +2048,18 @@ class BedrockCompletion(BaseLLM):
         input_tokens = usage.get("inputTokens", 0)
         output_tokens = usage.get("outputTokens", 0)
         total_tokens = usage.get("totalTokens", input_tokens + output_tokens)
+        raw_cached = (
+            usage.get("cacheReadInputTokenCount")
+            or usage.get("cacheReadInputTokens")
+            or 0
+        )
+        cached_tokens = raw_cached if isinstance(raw_cached, int) else 0
 
         self._token_usage["prompt_tokens"] += input_tokens
         self._token_usage["completion_tokens"] += output_tokens
         self._token_usage["total_tokens"] += total_tokens
         self._token_usage["successful_requests"] += 1
+        self._token_usage["cached_prompt_tokens"] += cached_tokens
 
     def supports_function_calling(self) -> bool:
         """Check if the model supports function calling."""

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

@@ -118,9 +118,33 @@ class GeminiCompletion(BaseLLM):
 
     @model_validator(mode="after")
     def _init_client(self) -> GeminiCompletion:
-        self._client = self._initialize_client(self.use_vertexai)
+        """Eagerly build the client when credentials resolve, otherwise defer
+        so ``LLM(model="gemini/...")`` can be constructed at module import time
+        even before deployment env vars are set.
+        """
+        try:
+            self._client = self._initialize_client(self.use_vertexai)
+        except ValueError:
+            pass
         return self
 
+    def _get_sync_client(self) -> Any:
+        if self._client is None:
+            # Re-read env vars so a deferred build can pick up credentials
+            # that weren't set at instantiation time.
+            if not self.api_key:
+                self.api_key = os.getenv("GOOGLE_API_KEY") or os.getenv(
+                    "GEMINI_API_KEY"
+                )
+            if not self.project:
+                self.project = os.getenv("GOOGLE_CLOUD_PROJECT")
+            self._client = self._initialize_client(self.use_vertexai)
+        return self._client
+
+    def _get_async_client(self) -> Any:
+        """Gemini uses a single client for both sync and async calls."""
+        return self._get_sync_client()
+
     def to_config_dict(self) -> dict[str, Any]:
         """Extend base config with Gemini/Vertex-specific fields."""
         config = super().to_config_dict()
@@ -228,6 +252,7 @@ class GeminiCompletion(BaseLLM):
 
         if (
             hasattr(self, "client")
+            and self._client is not None
             and hasattr(self._client, "vertexai")
             and self._client.vertexai
         ):
@@ -1112,7 +1137,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._get_sync_client().models.generate_content(
                 model=self.model,
                 contents=contents_for_api,
                 config=config,
@@ -1153,7 +1178,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._get_sync_client().models.generate_content_stream(
             model=self.model,
             contents=contents_for_api,
             config=config,
@@ -1191,7 +1216,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._get_async_client().aio.models.generate_content(
                 model=self.model,
                 contents=contents_for_api,
                 config=config,
@@ -1232,7 +1257,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._get_async_client().aio.models.generate_content_stream(
             model=self.model,
             contents=contents_for_api,
             config=config,
@@ -1306,17 +1331,20 @@ class GeminiCompletion(BaseLLM):
 
     @staticmethod
     def _extract_token_usage(response: GenerateContentResponse) -> dict[str, Any]:
-        """Extract token usage from Gemini response."""
+        """Extract token usage and response metadata from Gemini response."""
         if response.usage_metadata:
             usage = response.usage_metadata
             cached_tokens = getattr(usage, "cached_content_token_count", 0) or 0
-            return {
+            thinking_tokens = getattr(usage, "thoughts_token_count", 0) or 0
+            result: dict[str, Any] = {
                 "prompt_token_count": getattr(usage, "prompt_token_count", 0),
                 "candidates_token_count": getattr(usage, "candidates_token_count", 0),
                 "total_token_count": getattr(usage, "total_token_count", 0),
                 "total_tokens": getattr(usage, "total_token_count", 0),
                 "cached_prompt_tokens": cached_tokens,
+                "reasoning_tokens": thinking_tokens,
             }
+            return result
         return {"total_tokens": 0}
 
     @staticmethod
@@ -1436,6 +1464,6 @@ class GeminiCompletion(BaseLLM):
         try:
             from crewai_files.uploaders.gemini import GeminiFileUploader
 
-            return GeminiFileUploader(client=self._client)
+            return GeminiFileUploader(client=self._get_sync_client())
         except ImportError:
             return None

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

@@ -32,11 +32,15 @@ from crewai.events.types.llm_events import LLMCallType
 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.llms.providers.utils.common import safe_tool_conversion
 from crewai.utilities.agent_utils import is_context_length_exceeded
 from crewai.utilities.exceptions.context_window_exceeding_exception import (
     LLMContextLengthExceededError,
 )
-from crewai.utilities.pydantic_schema_utils import generate_model_description
+from crewai.utilities.pydantic_schema_utils import (
+    generate_model_description,
+    sanitize_tool_params_for_openai_strict,
+)
 from crewai.utilities.types import LLMMessage
 
 
@@ -253,22 +257,40 @@ class OpenAICompletion(BaseLLM):
 
     @model_validator(mode="after")
     def _init_clients(self) -> OpenAICompletion:
+        """Eagerly build clients when the API key is available, otherwise
+        defer so ``LLM(model="openai/...")`` can be constructed at module
+        import time even before deployment env vars are set.
+        """
+        try:
+            self._client = self._build_sync_client()
+            self._async_client = self._build_async_client()
+        except ValueError:
+            pass
+        return self
+
+    def _build_sync_client(self) -> Any:
         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
+            client_config["http_client"] = httpx.Client(transport=transport)
+        return OpenAI(**client_config)
 
-        self._client = OpenAI(**client_config)
-
-        async_client_config = self._get_client_params()
+    def _build_async_client(self) -> Any:
+        client_config = self._get_client_params()
         if self.interceptor:
-            async_transport = AsyncHTTPTransport(interceptor=self.interceptor)
-            async_http_client = httpx.AsyncClient(transport=async_transport)
-            async_client_config["http_client"] = async_http_client
+            transport = AsyncHTTPTransport(interceptor=self.interceptor)
+            client_config["http_client"] = httpx.AsyncClient(transport=transport)
+        return AsyncOpenAI(**client_config)
 
-        self._async_client = AsyncOpenAI(**async_client_config)
-        return self
+    def _get_sync_client(self) -> Any:
+        if self._client is None:
+            self._client = self._build_sync_client()
+        return self._client
+
+    def _get_async_client(self) -> Any:
+        if self._async_client is None:
+            self._async_client = self._build_async_client()
+        return self._async_client
 
     @property
     def last_response_id(self) -> str | None:
@@ -764,8 +786,6 @@ class OpenAICompletion(BaseLLM):
             "function": {"name": "...", "description": "...", "parameters": {...}}
         }
         """
-        from crewai.llms.providers.utils.common import safe_tool_conversion
-
         responses_tools = []
 
         for tool in tools:
@@ -797,7 +817,7 @@ class OpenAICompletion(BaseLLM):
     ) -> str | ResponsesAPIResult | Any:
         """Handle non-streaming Responses API call."""
         try:
-            response: Response = self._client.responses.create(**params)
+            response: Response = self._get_sync_client().responses.create(**params)
 
             # Track response ID for auto-chaining
             if self.auto_chain and response.id:
@@ -933,7 +953,9 @@ 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._get_async_client().responses.create(
+                **params
+            )
 
             # Track response ID for auto-chaining
             if self.auto_chain and response.id:
@@ -1069,7 +1091,7 @@ class OpenAICompletion(BaseLLM):
         final_response: Response | None = None
         usage: dict[str, Any] | None = None
 
-        stream = self._client.responses.create(**params)
+        stream = self._get_sync_client().responses.create(**params)
         response_id_stream = None
 
         for event in stream:
@@ -1197,7 +1219,7 @@ class OpenAICompletion(BaseLLM):
         final_response: Response | None = None
         usage: dict[str, Any] | None = None
 
-        stream = await self._async_client.responses.create(**params)
+        stream = await self._get_async_client().responses.create(**params)
         response_id_stream = None
 
         async for event in stream:
@@ -1324,19 +1346,23 @@ class OpenAICompletion(BaseLLM):
         ]
 
     def _extract_responses_token_usage(self, response: Response) -> dict[str, Any]:
-        """Extract token usage from Responses API response."""
+        """Extract token usage and response metadata from Responses API response."""
         if response.usage:
-            result = {
+            result: dict[str, Any] = {
                 "prompt_tokens": response.usage.input_tokens,
                 "completion_tokens": response.usage.output_tokens,
                 "total_tokens": response.usage.total_tokens,
             }
-            # Extract cached prompt tokens from input_tokens_details
             input_details = getattr(response.usage, "input_tokens_details", None)
             if input_details:
                 result["cached_prompt_tokens"] = (
                     getattr(input_details, "cached_tokens", 0) or 0
                 )
+            output_details = getattr(response.usage, "output_tokens_details", None)
+            if output_details:
+                result["reasoning_tokens"] = (
+                    getattr(output_details, "reasoning_tokens", 0) or 0
+                )
             return result
         return {"total_tokens": 0}
 
@@ -1544,11 +1570,6 @@ class OpenAICompletion(BaseLLM):
         self, tools: list[dict[str, BaseTool]]
     ) -> list[dict[str, Any]]:
         """Convert CrewAI tool format to OpenAI function calling format."""
-        from crewai.llms.providers.utils.common import safe_tool_conversion
-        from crewai.utilities.pydantic_schema_utils import (
-            force_additional_properties_false,
-        )
-
         openai_tools = []
 
         for tool in tools:
@@ -1567,8 +1588,9 @@ class OpenAICompletion(BaseLLM):
                 params_dict = (
                     parameters if isinstance(parameters, dict) else dict(parameters)
                 )
-                params_dict = force_additional_properties_false(params_dict)
-                openai_tool["function"]["parameters"] = params_dict
+                openai_tool["function"]["parameters"] = (
+                    sanitize_tool_params_for_openai_strict(params_dict)
+                )
 
             openai_tools.append(openai_tool)
         return openai_tools
@@ -1587,7 +1609,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._get_sync_client().beta.chat.completions.parse(
                     **parse_params,
                     response_format=response_model,
                 )
@@ -1611,7 +1633,9 @@ class OpenAICompletion(BaseLLM):
                     )
                     return parsed_object
 
-            response: ChatCompletion = self._client.chat.completions.create(**params)
+            response: ChatCompletion = self._get_sync_client().chat.completions.create(
+                **params
+            )
 
             usage = self._extract_openai_token_usage(response)
 
@@ -1838,7 +1862,7 @@ class OpenAICompletion(BaseLLM):
             }
 
             stream: ChatCompletionStream[BaseModel]
-            with self._client.beta.chat.completions.stream(
+            with self._get_sync_client().beta.chat.completions.stream(
                 **parse_params, response_format=response_model
             ) as stream:
                 for chunk in stream:
@@ -1875,7 +1899,7 @@ class OpenAICompletion(BaseLLM):
             return ""
 
         completion_stream: Stream[ChatCompletionChunk] = (
-            self._client.chat.completions.create(**params)
+            self._get_sync_client().chat.completions.create(**params)
         )
 
         usage_data: dict[str, Any] | None = None
@@ -1972,9 +1996,11 @@ 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(
-                    **parse_params,
-                    response_format=response_model,
+                parsed_response = (
+                    await self._get_async_client().beta.chat.completions.parse(
+                        **parse_params,
+                        response_format=response_model,
+                    )
                 )
                 math_reasoning = parsed_response.choices[0].message
 
@@ -1996,8 +2022,8 @@ class OpenAICompletion(BaseLLM):
                     )
                     return parsed_object
 
-            response: ChatCompletion = await self._async_client.chat.completions.create(
-                **params
+            response: ChatCompletion = (
+                await self._get_async_client().chat.completions.create(**params)
             )
 
             usage = self._extract_openai_token_usage(response)
@@ -2123,7 +2149,7 @@ class OpenAICompletion(BaseLLM):
         if response_model:
             completion_stream: AsyncIterator[
                 ChatCompletionChunk
-            ] = await self._async_client.chat.completions.create(**params)
+            ] = await self._get_async_client().chat.completions.create(**params)
 
             accumulated_content = ""
             usage_data: dict[str, Any] | None = None
@@ -2179,7 +2205,7 @@ class OpenAICompletion(BaseLLM):
 
         stream: AsyncIterator[
             ChatCompletionChunk
-        ] = await self._async_client.chat.completions.create(**params)
+        ] = await self._get_async_client().chat.completions.create(**params)
 
         usage_data = None
 
@@ -2307,20 +2333,24 @@ class OpenAICompletion(BaseLLM):
     def _extract_openai_token_usage(
         self, response: ChatCompletion | ChatCompletionChunk
     ) -> dict[str, Any]:
-        """Extract token usage from OpenAI ChatCompletion or ChatCompletionChunk response."""
+        """Extract token usage and response metadata from OpenAI ChatCompletion."""
         if hasattr(response, "usage") and response.usage:
             usage = response.usage
-            result = {
+            result: dict[str, Any] = {
                 "prompt_tokens": getattr(usage, "prompt_tokens", 0),
                 "completion_tokens": getattr(usage, "completion_tokens", 0),
                 "total_tokens": getattr(usage, "total_tokens", 0),
             }
-            # Extract cached prompt tokens from prompt_tokens_details
             prompt_details = getattr(usage, "prompt_tokens_details", None)
             if prompt_details:
                 result["cached_prompt_tokens"] = (
                     getattr(prompt_details, "cached_tokens", 0) or 0
                 )
+            completion_details = getattr(usage, "completion_tokens_details", None)
+            if completion_details:
+                result["reasoning_tokens"] = (
+                    getattr(completion_details, "reasoning_tokens", 0) or 0
+                )
             return result
         return {"total_tokens": 0}
 
@@ -2371,8 +2401,8 @@ class OpenAICompletion(BaseLLM):
             from crewai_files.uploaders.openai import OpenAIFileUploader
 
             return OpenAIFileUploader(
-                client=self._client,
-                async_client=self._async_client,
+                client=self._get_sync_client(),
+                async_client=self._get_async_client(),
             )
         except ImportError:
             return None

lib/crewai/src/crewai/state/checkpoint_config.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from pathlib import Path
 from typing import Annotated, Any, Literal
 
 from pydantic import BaseModel, Field, model_validator
@@ -201,11 +202,20 @@ class CheckpointConfig(BaseModel):
         description="Maximum checkpoints to keep. Oldest are pruned after "
         "each write. None means keep all.",
     )
+    restore_from: Path | str | None = Field(
+        default=None,
+        description="Path or location of a checkpoint to restore from. "
+        "When passed via a kickoff method's from_checkpoint parameter, "
+        "the crew or flow resumes from this checkpoint.",
+    )
 
     @model_validator(mode="after")
     def _register_handlers(self) -> CheckpointConfig:
         from crewai.state.checkpoint_listener import _ensure_handlers_registered
 
+        if isinstance(self.provider, SqliteProvider) and not Path(self.location).suffix:
+            self.location = f"{self.location}.db"
+
         _ensure_handlers_registered()
         return self
 
@@ -216,3 +226,25 @@ class CheckpointConfig(BaseModel):
     @property
     def trigger_events(self) -> set[str]:
         return set(self.on_events)
+
+
+def apply_checkpoint(instance: Any, from_checkpoint: CheckpointConfig | None) -> Any:
+    """Handle checkpoint config for a kickoff method.
+
+    If *from_checkpoint* carries a ``restore_from`` path, builds and returns a
+    restored instance (with ``restore_from`` cleared).  The caller should
+    dispatch into its own kickoff variant on that restored instance.
+
+    If *from_checkpoint* is present but has no ``restore_from``, sets
+    ``instance.checkpoint`` and returns ``None`` (proceed normally).
+
+    If *from_checkpoint* is ``None``, returns ``None`` immediately.
+    """
+    if from_checkpoint is None:
+        return None
+    if from_checkpoint.restore_from is not None:
+        restored = type(instance).from_checkpoint(from_checkpoint)
+        restored.checkpoint = from_checkpoint.model_copy(update={"restore_from": None})
+        return restored
+    instance.checkpoint = from_checkpoint
+    return None

lib/crewai/src/crewai/state/checkpoint_listener.py

@@ -7,6 +7,7 @@ avoids per-event overhead when no entity uses checkpointing.
 
 from __future__ import annotations
 
+import json
 import logging
 import threading
 from typing import Any
@@ -102,14 +103,25 @@ def _find_checkpoint(source: Any) -> CheckpointConfig | None:
     return None
 
 
-def _do_checkpoint(state: RuntimeState, cfg: CheckpointConfig) -> None:
+def _do_checkpoint(
+    state: RuntimeState, cfg: CheckpointConfig, event: BaseEvent | None = None
+) -> None:
     """Write a checkpoint and prune old ones if configured."""
     _prepare_entities(state.root)
-    data = state.model_dump_json()
-    cfg.provider.checkpoint(data, cfg.location)
+    payload = state.model_dump(mode="json")
+    if event is not None:
+        payload["trigger"] = event.type
+    data = json.dumps(payload)
+    location = cfg.provider.checkpoint(
+        data,
+        cfg.location,
+        parent_id=state._parent_id,
+        branch=state._branch,
+    )
+    state._chain_lineage(cfg.provider, location)
 
     if cfg.max_checkpoints is not None:
-        cfg.provider.prune(cfg.location, cfg.max_checkpoints)
+        cfg.provider.prune(cfg.location, cfg.max_checkpoints, branch=state._branch)
 
 
 def _should_checkpoint(source: Any, event: BaseEvent) -> CheckpointConfig | None:
@@ -128,7 +140,7 @@ def _on_any_event(source: Any, event: BaseEvent, state: Any) -> None:
     if cfg is None:
         return
     try:
-        _do_checkpoint(state, cfg)
+        _do_checkpoint(state, cfg, event)
     except Exception:
         logger.warning("Auto-checkpoint failed for event %s", event.type, exc_info=True)
 

lib/crewai/src/crewai/state/provider/core.py

@@ -17,12 +17,21 @@ class BaseProvider(BaseModel, ABC):
     provider_type: str = "base"
 
     @abstractmethod
-    def checkpoint(self, data: str, location: str) -> str:
+    def checkpoint(
+        self,
+        data: str,
+        location: str,
+        *,
+        parent_id: str | None = None,
+        branch: str = "main",
+    ) -> str:
         """Persist a snapshot synchronously.
 
         Args:
             data: The serialized string to persist.
             location: Storage destination (directory, file path, URI, etc.).
+            parent_id: ID of the parent checkpoint for lineage tracking.
+            branch: Branch label for this checkpoint.
 
         Returns:
             A location identifier for the saved checkpoint.
@@ -30,12 +39,21 @@ class BaseProvider(BaseModel, ABC):
         ...
 
     @abstractmethod
-    async def acheckpoint(self, data: str, location: str) -> str:
+    async def acheckpoint(
+        self,
+        data: str,
+        location: str,
+        *,
+        parent_id: str | None = None,
+        branch: str = "main",
+    ) -> str:
         """Persist a snapshot asynchronously.
 
         Args:
             data: The serialized string to persist.
             location: Storage destination (directory, file path, URI, etc.).
+            parent_id: ID of the parent checkpoint for lineage tracking.
+            branch: Branch label for this checkpoint.
 
         Returns:
             A location identifier for the saved checkpoint.
@@ -43,12 +61,25 @@ class BaseProvider(BaseModel, ABC):
         ...
 
     @abstractmethod
-    def prune(self, location: str, max_keep: int) -> None:
-        """Remove old checkpoints, keeping at most *max_keep*.
+    def prune(self, location: str, max_keep: int, *, branch: str = "main") -> None:
+        """Remove old checkpoints, keeping at most *max_keep* per branch.
 
         Args:
             location: The storage destination passed to ``checkpoint``.
             max_keep: Maximum number of checkpoints to retain.
+            branch: Only prune checkpoints on this branch.
+        """
+        ...
+
+    @abstractmethod
+    def extract_id(self, location: str) -> str:
+        """Extract the checkpoint ID from a location string.
+
+        Args:
+            location: The identifier returned by a previous ``checkpoint`` call.
+
+        Returns:
+            The checkpoint ID.
         """
         ...
 

lib/crewai/src/crewai/state/provider/json_provider.py

@@ -19,48 +19,87 @@ from crewai.state.provider.core import BaseProvider
 logger = logging.getLogger(__name__)
 
 
+def _safe_branch(base: str, branch: str) -> None:
+    """Validate that a branch name doesn't escape the base directory.
+
+    Raises:
+        ValueError: If the branch resolves outside the base directory.
+    """
+    base_resolved = str(Path(base).resolve())
+    target_resolved = str((Path(base) / branch).resolve())
+    if (
+        not target_resolved.startswith(base_resolved + os.sep)
+        and target_resolved != base_resolved
+    ):
+        raise ValueError(f"Branch name escapes checkpoint directory: {branch!r}")
+
+
 class JsonProvider(BaseProvider):
     """Persists runtime state checkpoints as JSON files on the local filesystem."""
 
     provider_type: Literal["json"] = "json"
 
-    def checkpoint(self, data: str, location: str) -> str:
+    def checkpoint(
+        self,
+        data: str,
+        location: str,
+        *,
+        parent_id: str | None = None,
+        branch: str = "main",
+    ) -> str:
         """Write a JSON checkpoint file.
 
         Args:
             data: The serialized JSON string to persist.
-            location: Directory where the checkpoint will be saved.
+            location: Base directory where checkpoints are saved.
+            parent_id: ID of the parent checkpoint for lineage tracking.
+                Encoded in the filename for queryable lineage without
+                parsing the blob.
+            branch: Branch label. Files are stored under ``location/branch/``.
 
         Returns:
             The path to the written checkpoint file.
         """
-        file_path = _build_path(location)
+        file_path = _build_path(location, branch, parent_id)
         file_path.parent.mkdir(parents=True, exist_ok=True)
 
         with open(file_path, "w") as f:
             f.write(data)
         return str(file_path)
 
-    async def acheckpoint(self, data: str, location: str) -> str:
+    async def acheckpoint(
+        self,
+        data: str,
+        location: str,
+        *,
+        parent_id: str | None = None,
+        branch: str = "main",
+    ) -> str:
         """Write a JSON checkpoint file asynchronously.
 
         Args:
             data: The serialized JSON string to persist.
-            location: Directory where the checkpoint will be saved.
+            location: Base directory where checkpoints are saved.
+            parent_id: ID of the parent checkpoint for lineage tracking.
+                Encoded in the filename for queryable lineage without
+                parsing the blob.
+            branch: Branch label. Files are stored under ``location/branch/``.
 
         Returns:
             The path to the written checkpoint file.
         """
-        file_path = _build_path(location)
+        file_path = _build_path(location, branch, parent_id)
         await aiofiles.os.makedirs(str(file_path.parent), exist_ok=True)
 
         async with aiofiles.open(file_path, "w") as f:
             await f.write(data)
         return str(file_path)
 
-    def prune(self, location: str, max_keep: int) -> None:
-        """Remove oldest checkpoint files beyond *max_keep*."""
-        pattern = os.path.join(location, "*.json")
+    def prune(self, location: str, max_keep: int, *, branch: str = "main") -> None:
+        """Remove oldest checkpoint files beyond *max_keep* on a branch."""
+        _safe_branch(location, branch)
+        branch_dir = os.path.join(location, branch)
+        pattern = os.path.join(branch_dir, "*.json")
         files = sorted(glob.glob(pattern), key=os.path.getmtime)
         for path in files if max_keep == 0 else files[:-max_keep]:
             try:
@@ -68,6 +107,16 @@ class JsonProvider(BaseProvider):
             except OSError:  # noqa: PERF203
                 logger.debug("Failed to remove %s", path, exc_info=True)
 
+    def extract_id(self, location: str) -> str:
+        """Extract the checkpoint ID from a file path.
+
+        The filename format is ``{ts}_{uuid8}_p-{parent}.json``.
+        The checkpoint ID is the ``{ts}_{uuid8}`` prefix.
+        """
+        stem = Path(location).stem
+        idx = stem.find("_p-")
+        return stem[:idx] if idx != -1 else stem
+
     def from_checkpoint(self, location: str) -> str:
         """Read a JSON checkpoint file.
 
@@ -92,15 +141,24 @@ class JsonProvider(BaseProvider):
             return await f.read()
 
 
-def _build_path(directory: str) -> Path:
-    """Build a timestamped checkpoint file path.
+def _build_path(
+    directory: str, branch: str = "main", parent_id: str | None = None
+) -> Path:
+    """Build a timestamped checkpoint file path under a branch subdirectory.
+
+    Filename format: ``{ts}_{uuid8}_p-{parent_id}.json``
 
     Args:
-        directory: Parent directory for the checkpoint file.
+        directory: Base directory for checkpoints.
+        branch: Branch label used as a subdirectory name.
+        parent_id: Parent checkpoint ID to encode in the filename.
 
     Returns:
         The target file path.
     """
+    _safe_branch(directory, branch)
     ts = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S")
-    filename = f"{ts}_{uuid.uuid4().hex[:8]}.json"
-    return Path(directory) / filename
+    short_uuid = uuid.uuid4().hex[:8]
+    parent_suffix = parent_id or "none"
+    filename = f"{ts}_{short_uuid}_p-{parent_suffix}.json"
+    return Path(directory) / branch / filename

lib/crewai/src/crewai/state/provider/sqlite_provider.py

@@ -17,15 +17,20 @@ _CREATE_TABLE = """
 CREATE TABLE IF NOT EXISTS checkpoints (
     id TEXT PRIMARY KEY,
     created_at TEXT NOT NULL,
+    parent_id TEXT,
+    branch TEXT NOT NULL DEFAULT 'main',
     data JSONB NOT NULL
 )
 """
 
-_INSERT = "INSERT INTO checkpoints (id, created_at, data) VALUES (?, ?, jsonb(?))"
+_INSERT = (
+    "INSERT INTO checkpoints (id, created_at, parent_id, branch, data) "
+    "VALUES (?, ?, ?, ?, jsonb(?))"
+)
 _SELECT = "SELECT json(data) FROM checkpoints WHERE id = ?"
 _PRUNE = """
-DELETE FROM checkpoints WHERE rowid NOT IN (
-    SELECT rowid FROM checkpoints ORDER BY rowid DESC LIMIT ?
+DELETE FROM checkpoints WHERE branch = ? AND rowid NOT IN (
+    SELECT rowid FROM checkpoints WHERE branch = ? ORDER BY rowid DESC LIMIT ?
 )
 """
 
@@ -50,12 +55,21 @@ class SqliteProvider(BaseProvider):
 
     provider_type: Literal["sqlite"] = "sqlite"
 
-    def checkpoint(self, data: str, location: str) -> str:
+    def checkpoint(
+        self,
+        data: str,
+        location: str,
+        *,
+        parent_id: str | None = None,
+        branch: str = "main",
+    ) -> str:
         """Write a checkpoint to the SQLite database.
 
         Args:
             data: The serialized JSON string to persist.
             location: Path to the SQLite database file.
+            parent_id: ID of the parent checkpoint for lineage tracking.
+            branch: Branch label for this checkpoint.
 
         Returns:
             A location string in the format ``"db_path#checkpoint_id"``.
@@ -65,16 +79,25 @@ class SqliteProvider(BaseProvider):
         with sqlite3.connect(location) as conn:
             conn.execute("PRAGMA journal_mode=WAL")
             conn.execute(_CREATE_TABLE)
-            conn.execute(_INSERT, (checkpoint_id, ts, data))
+            conn.execute(_INSERT, (checkpoint_id, ts, parent_id, branch, data))
             conn.commit()
         return f"{location}#{checkpoint_id}"
 
-    async def acheckpoint(self, data: str, location: str) -> str:
+    async def acheckpoint(
+        self,
+        data: str,
+        location: str,
+        *,
+        parent_id: str | None = None,
+        branch: str = "main",
+    ) -> str:
         """Write a checkpoint to the SQLite database asynchronously.
 
         Args:
             data: The serialized JSON string to persist.
             location: Path to the SQLite database file.
+            parent_id: ID of the parent checkpoint for lineage tracking.
+            branch: Branch label for this checkpoint.
 
         Returns:
             A location string in the format ``"db_path#checkpoint_id"``.
@@ -84,16 +107,20 @@ class SqliteProvider(BaseProvider):
         async with aiosqlite.connect(location) as db:
             await db.execute("PRAGMA journal_mode=WAL")
             await db.execute(_CREATE_TABLE)
-            await db.execute(_INSERT, (checkpoint_id, ts, data))
+            await db.execute(_INSERT, (checkpoint_id, ts, parent_id, branch, data))
             await db.commit()
         return f"{location}#{checkpoint_id}"
 
-    def prune(self, location: str, max_keep: int) -> None:
-        """Remove oldest checkpoint rows beyond *max_keep*."""
+    def prune(self, location: str, max_keep: int, *, branch: str = "main") -> None:
+        """Remove oldest checkpoint rows beyond *max_keep* on a branch."""
         with sqlite3.connect(location) as conn:
-            conn.execute(_PRUNE, (max_keep,))
+            conn.execute(_PRUNE, (branch, branch, max_keep))
             conn.commit()
 
+    def extract_id(self, location: str) -> str:
+        """Extract the checkpoint ID from a ``db_path#id`` string."""
+        return location.rsplit("#", 1)[1]
+
     def from_checkpoint(self, location: str) -> str:
         """Read a checkpoint from the SQLite database.
 

lib/crewai/src/crewai/state/runtime.py

@@ -9,8 +9,11 @@ via ``RuntimeState.model_rebuild()``.
 
 from __future__ import annotations
 
+import logging
 from typing import TYPE_CHECKING, Any
+import uuid
 
+from packaging.version import Version
 from pydantic import (
     ModelWrapValidatorHandler,
     PrivateAttr,
@@ -20,9 +23,14 @@ from pydantic import (
 )
 
 from crewai.context import capture_execution_context
+from crewai.state.checkpoint_config import CheckpointConfig
 from crewai.state.event_record import EventRecord
 from crewai.state.provider.core import BaseProvider
 from crewai.state.provider.json_provider import JsonProvider
+from crewai.utilities.version import get_crewai_version
+
+
+logger = logging.getLogger(__name__)
 
 
 if TYPE_CHECKING:
@@ -58,12 +66,51 @@ def _sync_checkpoint_fields(entity: object) -> None:
         entity.checkpoint_inputs = entity._inputs
         entity.checkpoint_train = entity._train
         entity.checkpoint_kickoff_event_id = entity._kickoff_event_id
+        for task in entity.tasks:
+            task.checkpoint_original_description = task._original_description
+            task.checkpoint_original_expected_output = task._original_expected_output
+
+
+def _migrate(data: dict[str, Any]) -> dict[str, Any]:
+    """Apply version-based migrations to checkpoint data.
+
+    Each block handles checkpoints older than a specific version,
+    transforming them forward to the current format. Blocks run in
+    version order so migrations compose.
+
+    Args:
+        data: The raw deserialized checkpoint dict.
+
+    Returns:
+        The migrated checkpoint dict.
+    """
+    raw = data.get("crewai_version")
+    current = Version(get_crewai_version())
+    stored = Version(raw) if raw else Version("0.0.0")
+
+    if raw is None:
+        logger.warning("Checkpoint has no crewai_version — treating as 0.0.0")
+    elif stored != current:
+        logger.debug(
+            "Migrating checkpoint from crewAI %s to %s",
+            stored,
+            current,
+        )
+
+    # --- migrations in version order ---
+    # if stored < Version("X.Y.Z"):
+    #     data.setdefault("some_field", "default")
+
+    return data
 
 
 class RuntimeState(RootModel):  # type: ignore[type-arg]
     root: list[Entity]
     _provider: BaseProvider = PrivateAttr(default_factory=JsonProvider)
     _event_record: EventRecord = PrivateAttr(default_factory=EventRecord)
+    _checkpoint_id: str | None = PrivateAttr(default=None)
+    _parent_id: str | None = PrivateAttr(default=None)
+    _branch: str = PrivateAttr(default="main")
 
     @property
     def event_record(self) -> EventRecord:
@@ -73,8 +120,11 @@ class RuntimeState(RootModel):  # type: ignore[type-arg]
     @model_serializer(mode="plain")
     def _serialize(self) -> dict[str, Any]:
         return {
+            "crewai_version": get_crewai_version(),
+            "parent_id": self._parent_id,
+            "branch": self._branch,
             "entities": [e.model_dump(mode="json") for e in self.root],
-            "event_record": self._event_record.model_dump(),
+            "event_record": self._event_record.model_dump(mode="json"),
         }
 
     @model_validator(mode="wrap")
@@ -83,13 +133,29 @@ class RuntimeState(RootModel):  # type: ignore[type-arg]
         cls, data: Any, handler: ModelWrapValidatorHandler[RuntimeState]
     ) -> RuntimeState:
         if isinstance(data, dict) and "entities" in data:
+            data = _migrate(data)
             record_data = data.get("event_record")
             state = handler(data["entities"])
             if record_data:
                 state._event_record = EventRecord.model_validate(record_data)
+            state._parent_id = data.get("parent_id")
+            state._branch = data.get("branch", "main")
             return state
         return handler(data)
 
+    def _chain_lineage(self, provider: BaseProvider, location: str) -> None:
+        """Update lineage fields after a successful checkpoint write.
+
+        Sets ``_checkpoint_id`` and ``_parent_id`` so the next write
+        records the correct parent in the lineage chain.
+
+        Args:
+            provider: The provider that performed the write.
+            location: The location string returned by the provider.
+        """
+        self._checkpoint_id = provider.extract_id(location)
+        self._parent_id = self._checkpoint_id
+
     def checkpoint(self, location: str) -> str:
         """Write a checkpoint.
 
@@ -101,7 +167,14 @@ class RuntimeState(RootModel):  # type: ignore[type-arg]
             A location identifier for the saved checkpoint.
         """
         _prepare_entities(self.root)
-        return self._provider.checkpoint(self.model_dump_json(), location)
+        result = self._provider.checkpoint(
+            self.model_dump_json(),
+            location,
+            parent_id=self._parent_id,
+            branch=self._branch,
+        )
+        self._chain_lineage(self._provider, result)
+        return result
 
     async def acheckpoint(self, location: str) -> str:
         """Async version of :meth:`checkpoint`.
@@ -114,41 +187,84 @@ class RuntimeState(RootModel):  # type: ignore[type-arg]
             A location identifier for the saved checkpoint.
         """
         _prepare_entities(self.root)
-        return await self._provider.acheckpoint(self.model_dump_json(), location)
+        result = await self._provider.acheckpoint(
+            self.model_dump_json(),
+            location,
+            parent_id=self._parent_id,
+            branch=self._branch,
+        )
+        self._chain_lineage(self._provider, result)
+        return result
+
+    def fork(self, branch: str | None = None) -> None:
+        """Create a new execution branch and write an initial checkpoint.
+
+        If this state was restored from a checkpoint, an initial checkpoint
+        is written on the new branch so the fork point is recorded.
+
+        Args:
+            branch: Branch label. Auto-generated from the current checkpoint
+                ID if not provided. Always unique — safe to call multiple
+                times without collisions.
+        """
+        if branch:
+            self._branch = branch
+        elif self._checkpoint_id:
+            self._branch = f"fork/{self._checkpoint_id}_{uuid.uuid4().hex[:6]}"
+        else:
+            self._branch = f"fork/{uuid.uuid4().hex[:8]}"
 
     @classmethod
-    def from_checkpoint(
-        cls, location: str, provider: BaseProvider, **kwargs: Any
-    ) -> RuntimeState:
+    def from_checkpoint(cls, config: CheckpointConfig, **kwargs: Any) -> RuntimeState:
         """Restore a RuntimeState from a checkpoint.
 
         Args:
-            location: The identifier returned by a previous ``checkpoint`` call.
-            provider: The storage backend to read from.
+            config: Checkpoint configuration with ``restore_from`` set.
             **kwargs: Passed to ``model_validate_json``.
 
         Returns:
             A restored RuntimeState.
         """
+        from crewai.state.provider.utils import detect_provider
+
+        if config.restore_from is None:
+            raise ValueError("CheckpointConfig.restore_from must be set")
+        location = str(config.restore_from)
+        provider = detect_provider(location)
         raw = provider.from_checkpoint(location)
-        return cls.model_validate_json(raw, **kwargs)
+        state = cls.model_validate_json(raw, **kwargs)
+        state._provider = provider
+        checkpoint_id = provider.extract_id(location)
+        state._checkpoint_id = checkpoint_id
+        state._parent_id = checkpoint_id
+        return state
 
     @classmethod
     async def afrom_checkpoint(
-        cls, location: str, provider: BaseProvider, **kwargs: Any
+        cls, config: CheckpointConfig, **kwargs: Any
     ) -> RuntimeState:
         """Async version of :meth:`from_checkpoint`.
 
         Args:
-            location: The identifier returned by a previous ``acheckpoint`` call.
-            provider: The storage backend to read from.
+            config: Checkpoint configuration with ``restore_from`` set.
             **kwargs: Passed to ``model_validate_json``.
 
         Returns:
             A restored RuntimeState.
         """
+        from crewai.state.provider.utils import detect_provider
+
+        if config.restore_from is None:
+            raise ValueError("CheckpointConfig.restore_from must be set")
+        location = str(config.restore_from)
+        provider = detect_provider(location)
         raw = await provider.afrom_checkpoint(location)
-        return cls.model_validate_json(raw, **kwargs)
+        state = cls.model_validate_json(raw, **kwargs)
+        state._provider = provider
+        checkpoint_id = provider.extract_id(location)
+        state._checkpoint_id = checkpoint_id
+        state._parent_id = checkpoint_id
+        return state
 
 
 def _prepare_entities(root: list[Entity]) -> None:

lib/crewai/src/crewai/task.py

@@ -45,6 +45,7 @@ from crewai.events.types.task_events import (
     TaskStartedEvent,
 )
 from crewai.llms.base_llm import BaseLLM
+from crewai.llms.providers.openai.completion import OpenAICompletion
 from crewai.security import Fingerprint, SecurityConfig
 from crewai.tasks.output_format import OutputFormat
 from crewai.tasks.task_output import TaskOutput
@@ -230,6 +231,8 @@ class Task(BaseModel):
     _original_description: str | None = PrivateAttr(default=None)
     _original_expected_output: str | None = PrivateAttr(default=None)
     _original_output_file: str | None = PrivateAttr(default=None)
+    checkpoint_original_description: str | None = Field(default=None, exclude=False)
+    checkpoint_original_expected_output: str | None = Field(default=None, exclude=False)
     _thread: threading.Thread | None = PrivateAttr(default=None)
     model_config = {"arbitrary_types_allowed": True}
 
@@ -299,12 +302,14 @@ class Task(BaseModel):
 
     @model_validator(mode="after")
     def validate_required_fields(self) -> Self:
-        required_fields = ["description", "expected_output"]
-        for field in required_fields:
-            if getattr(self, field) is None:
-                raise ValueError(
-                    f"{field} must be provided either directly or through config"
-                )
+        if self.description is None:
+            raise ValueError(
+                "description must be provided either directly or through config"
+            )
+        if self.expected_output is None:
+            raise ValueError(
+                "expected_output must be provided either directly or through config"
+            )
         return self
 
     @model_validator(mode="after")
@@ -836,8 +841,8 @@ class Task(BaseModel):
         should_inject = self.allow_crewai_trigger_context
 
         if should_inject and self.agent:
-            crew = getattr(self.agent, "crew", None)
-            if crew and hasattr(crew, "_inputs") and crew._inputs:
+            crew = self.agent.crew
+            if crew and not isinstance(crew, str) and crew._inputs:
                 trigger_payload = crew._inputs.get("crewai_trigger_payload")
                 if trigger_payload is not None:
                     description += f"\n\nTrigger Payload: {trigger_payload}"
@@ -850,11 +855,12 @@ class Task(BaseModel):
                     isinstance(self.agent.llm, BaseLLM)
                     and self.agent.llm.supports_multimodal()
                 ):
-                    provider: str = str(
-                        getattr(self.agent.llm, "provider", None)
-                        or getattr(self.agent.llm, "model", "openai")
+                    provider: str = self.agent.llm.provider or self.agent.llm.model
+                    api: str | None = (
+                        self.agent.llm.api
+                        if isinstance(self.agent.llm, OpenAICompletion)
+                        else None
                     )
-                    api: str | None = getattr(self.agent.llm, "api", None)
                     supported_types = get_supported_content_types(provider, api)
 
                 def is_auto_injected(content_type: str) -> bool:

lib/crewai/src/crewai/types/usage_metrics.py

@@ -29,6 +29,14 @@ class UsageMetrics(BaseModel):
     completion_tokens: int = Field(
         default=0, description="Number of tokens used in completions."
     )
+    reasoning_tokens: int = Field(
+        default=0,
+        description="Number of reasoning/thinking tokens (e.g. OpenAI o-series, Gemini thinking).",
+    )
+    cache_creation_tokens: int = Field(
+        default=0,
+        description="Number of cache creation tokens (e.g. Anthropic cache writes).",
+    )
     successful_requests: int = Field(
         default=0, description="Number of successful requests made."
     )
@@ -43,4 +51,6 @@ class UsageMetrics(BaseModel):
         self.prompt_tokens += usage_metrics.prompt_tokens
         self.cached_prompt_tokens += usage_metrics.cached_prompt_tokens
         self.completion_tokens += usage_metrics.completion_tokens
+        self.reasoning_tokens += usage_metrics.reasoning_tokens
+        self.cache_creation_tokens += usage_metrics.cache_creation_tokens
         self.successful_requests += usage_metrics.successful_requests

lib/crewai/src/crewai/utilities/pydantic_schema_utils.py

@@ -19,7 +19,7 @@ from collections.abc import Callable
 from copy import deepcopy
 import datetime
 import logging
-from typing import TYPE_CHECKING, Annotated, Any, Final, Literal, TypedDict, Union
+from typing import TYPE_CHECKING, Annotated, Any, Final, Literal, TypedDict, Union, cast
 import uuid
 
 import jsonref  # type: ignore[import-untyped]
@@ -417,6 +417,119 @@ def strip_null_from_types(schema: dict[str, Any]) -> dict[str, Any]:
     return schema
 
 
+_STRICT_METADATA_KEYS: Final[tuple[str, ...]] = (
+    "title",
+    "default",
+    "examples",
+    "example",
+    "$comment",
+    "readOnly",
+    "writeOnly",
+    "deprecated",
+)
+
+_CLAUDE_STRICT_UNSUPPORTED: Final[tuple[str, ...]] = (
+    "minimum",
+    "maximum",
+    "exclusiveMinimum",
+    "exclusiveMaximum",
+    "multipleOf",
+    "minLength",
+    "maxLength",
+    "pattern",
+    "minItems",
+    "maxItems",
+    "uniqueItems",
+    "minContains",
+    "maxContains",
+    "minProperties",
+    "maxProperties",
+    "patternProperties",
+    "propertyNames",
+    "dependentRequired",
+    "dependentSchemas",
+)
+
+
+def _strip_keys_recursive(d: Any, keys: tuple[str, ...]) -> Any:
+    """Recursively delete a fixed set of keys from a schema."""
+    if isinstance(d, dict):
+        for key in keys:
+            d.pop(key, None)
+        for v in d.values():
+            _strip_keys_recursive(v, keys)
+    elif isinstance(d, list):
+        for i in d:
+            _strip_keys_recursive(i, keys)
+    return d
+
+
+def lift_top_level_anyof(schema: dict[str, Any]) -> dict[str, Any]:
+    """Unwrap a top-level anyOf/oneOf/allOf wrapping a single object variant.
+
+    Anthropic's strict ``input_schema`` rejects top-level union keywords. When
+    exactly one variant is an object schema, lift it so the root is a plain
+    object; otherwise leave the schema alone.
+    """
+    for key in ("anyOf", "oneOf", "allOf"):
+        variants = schema.get(key)
+        if not isinstance(variants, list):
+            continue
+        object_variants = [
+            v for v in variants if isinstance(v, dict) and v.get("type") == "object"
+        ]
+        if len(object_variants) == 1:
+            lifted = deepcopy(object_variants[0])
+            schema.pop(key)
+            schema.update(lifted)
+            break
+    return schema
+
+
+def _common_strict_pipeline(params: dict[str, Any]) -> dict[str, Any]:
+    """Shared strict sanitization: inline refs, close objects, require all properties."""
+    sanitized = resolve_refs(deepcopy(params))
+    sanitized.pop("$defs", None)
+    sanitized = convert_oneof_to_anyof(sanitized)
+    sanitized = ensure_type_in_schemas(sanitized)
+    sanitized = force_additional_properties_false(sanitized)
+    sanitized = ensure_all_properties_required(sanitized)
+    return cast(dict[str, Any], _strip_keys_recursive(sanitized, _STRICT_METADATA_KEYS))
+
+
+def sanitize_tool_params_for_openai_strict(
+    params: dict[str, Any],
+) -> dict[str, Any]:
+    """Sanitize a JSON schema for OpenAI strict function calling."""
+    if not isinstance(params, dict):
+        return params
+    return cast(
+        dict[str, Any], strip_unsupported_formats(_common_strict_pipeline(params))
+    )
+
+
+def sanitize_tool_params_for_anthropic_strict(
+    params: dict[str, Any],
+) -> dict[str, Any]:
+    """Sanitize a JSON schema for Anthropic strict tool use."""
+    if not isinstance(params, dict):
+        return params
+    sanitized = lift_top_level_anyof(_common_strict_pipeline(params))
+    sanitized = _strip_keys_recursive(sanitized, _CLAUDE_STRICT_UNSUPPORTED)
+    return cast(dict[str, Any], strip_unsupported_formats(sanitized))
+
+
+def sanitize_tool_params_for_bedrock_strict(
+    params: dict[str, Any],
+) -> dict[str, Any]:
+    """Sanitize a JSON schema for Bedrock Converse strict tool use.
+
+    Bedrock Converse uses the same grammar compiler as the underlying Claude
+    model, so the constraints match Anthropic's.
+    """
+    return sanitize_tool_params_for_anthropic_strict(params)
+
+
 def generate_model_description(
     model: type[BaseModel],
     *,

lib/crewai/src/crewai/utilities/serialization.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from datetime import date, datetime
+from enum import Enum
 import json
 from typing import Any, TypeAlias
 import uuid
@@ -20,6 +21,7 @@ def to_serializable(
     max_depth: int = 5,
     _current_depth: int = 0,
     _ancestors: set[int] | None = None,
+    context: dict[str, Any] | None = None,
 ) -> Serializable:
     """Converts a Python object into a JSON-compatible representation.
 
@@ -33,6 +35,9 @@ def to_serializable(
         max_depth: Maximum recursion depth. Defaults to 5.
         _current_depth: Current recursion depth (for internal use).
         _ancestors: Set of ancestor object ids for cycle detection (for internal use).
+        context: Optional context dict passed to Pydantic's model_dump(context=...).
+            Field serializers on the model can inspect this to customize output
+            (e.g. context={"trace": True} for lightweight trace serialization).
 
     Returns:
         Serializable: A JSON-compatible structure.
@@ -48,6 +53,15 @@ def to_serializable(
 
     if isinstance(obj, (str, int, float, bool, type(None))):
         return obj
+    if isinstance(obj, Enum):
+        return to_serializable(
+            obj.value,
+            exclude=exclude,
+            max_depth=max_depth,
+            _current_depth=_current_depth,
+            _ancestors=_ancestors,
+            context=context,
+        )
     if isinstance(obj, uuid.UUID):
         return str(obj)
     if isinstance(obj, (date, datetime)):
@@ -66,6 +80,7 @@ def to_serializable(
                 max_depth=max_depth,
                 _current_depth=_current_depth + 1,
                 _ancestors=new_ancestors,
+                context=context,
             )
             for item in obj
         ]
@@ -77,17 +92,24 @@ def to_serializable(
                 max_depth=max_depth,
                 _current_depth=_current_depth + 1,
                 _ancestors=new_ancestors,
+                context=context,
             )
             for key, value in obj.items()
             if key not in exclude
         }
     if isinstance(obj, BaseModel):
         try:
+            dump_kwargs: dict[str, Any] = {}
+            if exclude:
+                dump_kwargs["exclude"] = exclude
+            if context is not None:
+                dump_kwargs["context"] = context
             return to_serializable(
-                obj=obj.model_dump(exclude=exclude),
+                obj=obj.model_dump(**dump_kwargs),
                 max_depth=max_depth,
                 _current_depth=_current_depth + 1,
                 _ancestors=new_ancestors,
+                context=context,
             )
         except Exception:
             try:
@@ -97,12 +119,30 @@ def to_serializable(
                         max_depth=max_depth,
                         _current_depth=_current_depth + 1,
                         _ancestors=new_ancestors,
+                        context=context,
                     )
                     for k, v in obj.__dict__.items()
                     if k not in (exclude or set())
                 }
             except Exception:
                 return repr(obj)
+    if callable(obj):
+        return repr(obj)
+    if hasattr(obj, "__dict__"):
+        try:
+            return {
+                _to_serializable_key(k): to_serializable(
+                    v,
+                    max_depth=max_depth,
+                    _current_depth=_current_depth + 1,
+                    _ancestors=new_ancestors,
+                    context=context,
+                )
+                for k, v in obj.__dict__.items()
+                if not k.startswith("_")
+            }
+        except Exception:
+            return repr(obj)
     return repr(obj)
 
 

lib/crewai/src/crewai/utilities/version.py

@@ -0,0 +1,12 @@
+"""Version utilities for crewAI."""
+
+from __future__ import annotations
+
+from functools import cache
+import importlib.metadata
+
+
+@cache
+def get_crewai_version() -> str:
+    """Get the installed crewAI version string."""
+    return importlib.metadata.version("crewai")

lib/crewai/tests/agents/test_lite_agent.py

@@ -1051,7 +1051,7 @@ def test_lite_agent_verbose_false_suppresses_printer_output():
         successful_requests=1,
     )
 
-    with pytest.warns(DeprecationWarning):
+    with pytest.warns(FutureWarning):
         agent = LiteAgent(
             role="Test Agent",
             goal="Test goal",

lib/crewai/tests/cassettes/test_hierarchical_verbose_false_manager_agent.yaml

@@ -55,7 +55,7 @@ interactions:
       x-stainless-os:
       - X-STAINLESS-OS-XXX
       x-stainless-package-version:
-      - 1.83.0
+      - 2.31.0
       x-stainless-read-timeout:
       - X-STAINLESS-READ-TIMEOUT-XXX
       x-stainless-retry-count:
@@ -63,50 +63,51 @@ 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
   response:
     body:
-      string: "{\n  \"id\": \"chatcmpl-DIqxWpJbbFJoV8WlXhb9UYFbCmdPk\",\n  \"object\":
-        \"chat.completion\",\n  \"created\": 1773385850,\n  \"model\": \"gpt-4o-2024-08-06\",\n
+      string: "{\n  \"id\": \"chatcmpl-DTApYQx2LepfeRL1XcDKPgrhMFnQr\",\n  \"object\":
+        \"chat.completion\",\n  \"created\": 1775845516,\n  \"model\": \"gpt-4o-2024-08-06\",\n
         \ \"choices\": [\n    {\n      \"index\": 0,\n      \"message\": {\n        \"role\":
         \"assistant\",\n        \"content\": null,\n        \"tool_calls\": [\n          {\n
-        \           \"id\": \"call_G2i9RJGNXKVfnd8ZTaBG8Fwi\",\n            \"type\":
-        \"function\",\n            \"function\": {\n              \"name\": \"ask_question_to_coworker\",\n
-        \             \"arguments\": \"{\\\"question\\\": \\\"What are some trending
-        topics or ideas in various fields that could be explored for an article?\\\",
-        \\\"context\\\": \\\"We need to generate a list of 5 interesting ideas to
-        explore for an article. These ideas should be engaging and relevant to current
-        trends or captivating subjects.\\\", \\\"coworker\\\": \\\"Researcher\\\"}\"\n
-        \           }\n          },\n          {\n            \"id\": \"call_j4KH2SGZvNeioql0HcRQ9NTp\",\n
+        \           \"id\": \"call_BCh6lXsBTdixRuRh6OTBPoIJ\",\n            \"type\":
+        \"function\",\n            \"function\": {\n              \"name\": \"delegate_work_to_coworker\",\n
+        \             \"arguments\": \"{\\\"task\\\": \\\"Come up with a list of 5
+        interesting ideas to explore for an article.\\\", \\\"context\\\": \\\"We
+        need five intriguing ideas worth exploring for an article. Each idea should
+        have potential for in-depth exploration and appeal to a broad audience, possibly
+        touching on current trends, historical insights, future possibilities, or
+        human interest stories.\\\", \\\"coworker\\\": \\\"Researcher\\\"}\"\n            }\n
+        \         },\n          {\n            \"id\": \"call_rAQFeCrS4ogsqvIWRGAYFHGI\",\n
         \           \"type\": \"function\",\n            \"function\": {\n              \"name\":
-        \"ask_question_to_coworker\",\n              \"arguments\": \"{\\\"question\\\":
-        \\\"What unique angles or perspectives could we explore to make articles more
-        compelling and engaging?\\\", \\\"context\\\": \\\"Our task involves coming
-        up with 5 ideas for articles, each with an exciting paragraph highlight that
-        illustrates the promise and intrigue of the topic. We want them to be more
-        than generic concepts, shining for readers with fresh insights or engaging
-        twists.\\\", \\\"coworker\\\": \\\"Senior Writer\\\"}\"\n            }\n          }\n
-        \       ],\n        \"refusal\": null,\n        \"annotations\": []\n      },\n
-        \     \"logprobs\": null,\n      \"finish_reason\": \"tool_calls\"\n    }\n
-        \ ],\n  \"usage\": {\n    \"prompt_tokens\": 476,\n    \"completion_tokens\":
-        183,\n    \"total_tokens\": 659,\n    \"prompt_tokens_details\": {\n      \"cached_tokens\":
-        0,\n      \"audio_tokens\": 0\n    },\n    \"completion_tokens_details\":
+        \"delegate_work_to_coworker\",\n              \"arguments\": \"{\\\"task\\\":
+        \\\"Write one amazing paragraph highlight for each of 5 ideas that showcases
+        how good an article about this topic could be.\\\", \\\"context\\\": \\\"Upon
+        receiving five intriguing ideas from the Researcher, create a compelling paragraph
+        for each idea that highlights its potential as a fascinating article. These
+        paragraphs must capture the essence of the topic and explain why it would
+        captivate readers, incorporating possible themes and insights.\\\", \\\"coworker\\\":
+        \\\"Senior Writer\\\"}\"\n            }\n          }\n        ],\n        \"refusal\":
+        null,\n        \"annotations\": []\n      },\n      \"logprobs\": null,\n
+        \     \"finish_reason\": \"tool_calls\"\n    }\n  ],\n  \"usage\": {\n    \"prompt_tokens\":
+        476,\n    \"completion_tokens\": 201,\n    \"total_tokens\": 677,\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\": \"fp_b7c8e3f100\"\n}\n"
+        \"default\",\n  \"system_fingerprint\": \"fp_2ca5b70601\"\n}\n"
     headers:
       CF-Cache-Status:
       - DYNAMIC
       CF-Ray:
-      - 9db9389a3f9e424c-EWR
+      - 9ea3cb06ba66b301-TPE
       Connection:
       - keep-alive
       Content-Type:
       - application/json
       Date:
-      - Fri, 13 Mar 2026 07:10:53 GMT
+      - Fri, 10 Apr 2026 18:25:18 GMT
       Server:
       - cloudflare
       Strict-Transport-Security:
@@ -122,7 +123,7 @@ interactions:
       openai-organization:
       - OPENAI-ORG-XXX
       openai-processing-ms:
-      - '2402'
+      - '1981'
       openai-project:
       - OPENAI-PROJECT-XXX
       openai-version:
@@ -154,13 +155,14 @@ interactions:
       You work as a freelancer and is now working on doing research and analysis for
       a new customer.\nYour personal goal is: Make the best research and analysis
       on content about AI and AI agents"},{"role":"user","content":"\nCurrent Task:
-      What are some trending topics or ideas in various fields that could be explored
-      for an article?\n\nThis is the expected criteria for your final answer: Your
-      best answer to your coworker asking you this, accounting for the context shared.\nyou
-      MUST return the actual complete content as the final answer, not a summary.\n\nThis
-      is the context you''re working with:\nWe need to generate a list of 5 interesting
-      ideas to explore for an article. These ideas should be engaging and relevant
-      to current trends or captivating subjects.\n\nProvide your complete response:"}],"model":"gpt-4.1-mini"}'
+      Come up with a list of 5 interesting ideas to explore for an article.\n\nThis
+      is the expected criteria for your final answer: Your best answer to your coworker
+      asking you this, accounting for the context shared.\nyou MUST return the actual
+      complete content as the final answer, not a summary.\n\nThis is the context
+      you''re working with:\nWe need five intriguing ideas worth exploring for an
+      article. Each idea should have potential for in-depth exploration and appeal
+      to a broad audience, possibly touching on current trends, historical insights,
+      future possibilities, or human interest stories.\n\nProvide your complete response:"}],"model":"gpt-4.1-mini"}'
     headers:
       User-Agent:
       - X-USER-AGENT-XXX
@@ -173,7 +175,7 @@ interactions:
       connection:
       - keep-alive
       content-length:
-      - '978'
+      - '1046'
       content-type:
       - application/json
       host:
@@ -187,7 +189,7 @@ interactions:
       x-stainless-os:
       - X-STAINLESS-OS-XXX
       x-stainless-package-version:
-      - 1.83.0
+      - 2.31.0
       x-stainless-read-timeout:
       - X-STAINLESS-READ-TIMEOUT-XXX
       x-stainless-retry-count:
@@ -195,63 +197,69 @@ 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
   response:
     body:
-      string: "{\n  \"id\": \"chatcmpl-DIqxak88AexErt9PGFGHnWPIJLwNV\",\n  \"object\":
-        \"chat.completion\",\n  \"created\": 1773385854,\n  \"model\": \"gpt-4.1-mini-2025-04-14\",\n
+      string: "{\n  \"id\": \"chatcmpl-DTApalbfnYkqIc8slLS3DKwo9KXbc\",\n  \"object\":
+        \"chat.completion\",\n  \"created\": 1775845518,\n  \"model\": \"gpt-4.1-mini-2025-04-14\",\n
         \ \"choices\": [\n    {\n      \"index\": 0,\n      \"message\": {\n        \"role\":
-        \"assistant\",\n        \"content\": \"Here are five trending and engaging
-        topics across various fields that could be explored for an article:\\n\\n1.
-        **The Rise of Autonomous AI Agents and Their Impact on the Future of Work**
-        \ \\nExplore how autonomous AI agents\u2014systems capable of performing complex
-        tasks independently\u2014are transforming industries such as customer service,
-        software development, and logistics. Discuss implications for job automation,
-        human-AI collaboration, and ethical considerations surrounding decision-making
-        autonomy.\\n\\n2. **Generative AI Beyond Text: Innovations in Audio, Video,
-        and 3D Content Creation**  \\nDelve into advancements in generative AI models
-        that create not only text but also realistic audio, video content, virtual
-        environments, and 3D models. Highlight applications in gaming, entertainment,
-        education, and digital marketing, as well as challenges like misinformation
-        and deepfake detection.\\n\\n3. **AI-Driven Climate Modeling: Enhancing Predictive
-        Accuracy to Combat Climate Change**  \\nExamine how AI and machine learning
-        are improving climate models by analyzing vast datasets, uncovering patterns,
-        and simulating environmental scenarios. Discuss how these advances are aiding
-        policymakers in making informed decisions to address climate risks and sustainability
-        goals.\\n\\n4. **The Ethical Frontiers of AI in Healthcare: Balancing Innovation
-        with Patient Privacy**  \\nInvestigate ethical challenges posed by AI applications
-        in healthcare, including diagnosis, personalized treatment, and patient data
-        management. Focus on balancing rapid technological innovation with privacy,
-        bias mitigation, and regulatory frameworks to ensure equitable access and
-        trust.\\n\\n5. **Quantum Computing Meets AI: Exploring the Next Leap in Computational
-        Power**  \\nCover the intersection of quantum computing and artificial intelligence,
-        exploring how quantum algorithms could accelerate AI training processes and
-        solve problems beyond the reach of classical computers. Outline current research,
-        potential breakthroughs, and the timeline for real-world applications.\\n\\nEach
-        of these topics is timely, relevant, and has the potential to engage readers
-        interested in cutting-edge technology, societal impact, and future trends.
-        Let me know if you want me to help develop an outline or deeper research into
-        any of these areas!\",\n        \"refusal\": null,\n        \"annotations\":
-        []\n      },\n      \"logprobs\": null,\n      \"finish_reason\": \"stop\"\n
-        \   }\n  ],\n  \"usage\": {\n    \"prompt_tokens\": 178,\n    \"completion_tokens\":
-        402,\n    \"total_tokens\": 580,\n    \"prompt_tokens_details\": {\n      \"cached_tokens\":
+        \"assistant\",\n        \"content\": \"Certainly! Here are five intriguing
+        article ideas that offer rich potential for deep exploration and broad audience
+        appeal, especially aligned with current trends and human interest in AI and
+        technology:\\n\\n1. **The Evolution of AI Agents: From Rule-Based Bots to
+        Autonomous Decision Makers**  \\n   Explore the historical development of
+        AI agents, tracing the journey from simple scripted chatbots to advanced autonomous
+        systems capable of complex decision-making and learning. Dive into key technological
+        milestones, breakthroughs in machine learning, and current state-of-the-art
+        AI agents. Discuss implications for industries such as customer service, healthcare,
+        and autonomous vehicles, highlighting both opportunities and ethical concerns.\\n\\n2.
+        **AI in Daily Life: How Intelligent Agents Are Reshaping Human Routines**
+        \ \\n   Investigate the integration of AI agents in everyday life\u2014from
+        virtual assistants like Siri and Alexa to personalized recommendation systems
+        and smart home devices. Analyze how these AI tools influence productivity,
+        privacy, and social behavior. Include human interest elements through stories
+        of individuals or communities who have embraced or resisted these technologies.\\n\\n3.
+        **The Future of Work: AI Agents as Collaborative Colleagues**  \\n   Examine
+        how AI agents are transforming workplaces by acting as collaborators rather
+        than just tools. Cover applications in creative fields, data analysis, and
+        decision support, while addressing potential challenges such as job displacement,
+        new skill requirements, and the evolving definition of teamwork. Use expert
+        opinions and case studies to paint a nuanced future outlook.\\n\\n4. **Ethics
+        and Accountability in AI Agent Development**  \\n   Delve into the ethical
+        dilemmas posed by increasingly autonomous AI agents\u2014topics like bias
+        in algorithms, data privacy, and accountability for AI-driven decisions. Explore
+        measures being taken globally to regulate AI, frameworks for responsible AI
+        development, and the role of public awareness. Include historical context
+        about technology ethics to provide depth.\\n\\n5. **Human-AI Symbiosis: Stories
+        of Innovative Partnerships Shaping Our World**  \\n   Tell compelling human
+        interest stories about individuals or organizations pioneering collaborative
+        projects with AI agents that lead to breakthroughs in science, art, or social
+        good. Highlight how these partnerships transcend traditional human-machine
+        interaction and open new creative and problem-solving possibilities, inspiring
+        readers about the potential of human-AI synergy.\\n\\nThese ideas are designed
+        to be both engaging and informative, offering multiple angles\u2014technical,
+        historical, ethical, and personal\u2014to keep readers captivated while providing
+        substantial content for in-depth analysis.\",\n        \"refusal\": null,\n
+        \       \"annotations\": []\n      },\n      \"logprobs\": null,\n      \"finish_reason\":
+        \"stop\"\n    }\n  ],\n  \"usage\": {\n    \"prompt_tokens\": 189,\n    \"completion_tokens\":
+        472,\n    \"total_tokens\": 661,\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\": \"fp_e76a310957\"\n}\n"
+        \"default\",\n  \"system_fingerprint\": \"fp_fbf43a1ff3\"\n}\n"
     headers:
       CF-Cache-Status:
       - DYNAMIC
       CF-Ray:
-      - 9db938b0493c4b9f-EWR
+      - 9ea3cb1b5c943323-TPE
       Connection:
       - keep-alive
       Content-Type:
       - application/json
       Date:
-      - Fri, 13 Mar 2026 07:10:59 GMT
+      - Fri, 10 Apr 2026 18:25:25 GMT
       Server:
       - cloudflare
       Strict-Transport-Security:
@@ -267,7 +275,7 @@ interactions:
       openai-organization:
       - OPENAI-ORG-XXX
       openai-processing-ms:
-      - '5699'
+      - '6990'
       openai-project:
       - OPENAI-PROJECT-XXX
       openai-version:
@@ -298,15 +306,16 @@ interactions:
       a senior writer, specialized in technology, software engineering, AI and startups.
       You work as a freelancer and are now working on writing content for a new customer.\nYour
       personal goal is: Write the best content about AI and AI agents."},{"role":"user","content":"\nCurrent
-      Task: What unique angles or perspectives could we explore to make articles more
-      compelling and engaging?\n\nThis is the expected criteria for your final answer:
-      Your best answer to your coworker asking you this, accounting for the context
-      shared.\nyou MUST return the actual complete content as the final answer, not
-      a summary.\n\nThis is the context you''re working with:\nOur task involves coming
-      up with 5 ideas for articles, each with an exciting paragraph highlight that
-      illustrates the promise and intrigue of the topic. We want them to be more than
-      generic concepts, shining for readers with fresh insights or engaging twists.\n\nProvide
-      your complete response:"}],"model":"gpt-4.1-mini"}'
+      Task: Write one amazing paragraph highlight for each of 5 ideas that showcases
+      how good an article about this topic could be.\n\nThis is the expected criteria
+      for your final answer: Your best answer to your coworker asking you this, accounting
+      for the context shared.\nyou MUST return the actual complete content as the
+      final answer, not a summary.\n\nThis is the context you''re working with:\nUpon
+      receiving five intriguing ideas from the Researcher, create a compelling paragraph
+      for each idea that highlights its potential as a fascinating article. These
+      paragraphs must capture the essence of the topic and explain why it would captivate
+      readers, incorporating possible themes and insights.\n\nProvide your complete
+      response:"}],"model":"gpt-4.1-mini"}'
     headers:
       User-Agent:
       - X-USER-AGENT-XXX
@@ -319,7 +328,7 @@ interactions:
       connection:
       - keep-alive
       content-length:
-      - '1041'
+      - '1103'
       content-type:
       - application/json
       host:
@@ -333,7 +342,7 @@ interactions:
       x-stainless-os:
       - X-STAINLESS-OS-XXX
       x-stainless-package-version:
-      - 1.83.0
+      - 2.31.0
       x-stainless-read-timeout:
       - X-STAINLESS-READ-TIMEOUT-XXX
       x-stainless-retry-count:
@@ -341,78 +350,83 @@ 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
   response:
     body:
-      string: "{\n  \"id\": \"chatcmpl-DIqxZCl1kFIE7WXznIKow9QFNZ2QT\",\n  \"object\":
-        \"chat.completion\",\n  \"created\": 1773385853,\n  \"model\": \"gpt-4.1-mini-2025-04-14\",\n
+      string: "{\n  \"id\": \"chatcmpl-DTApbrh9Z4yFAKPHIR48ubdB1R5xK\",\n  \"object\":
+        \"chat.completion\",\n  \"created\": 1775845519,\n  \"model\": \"gpt-4.1-mini-2025-04-14\",\n
         \ \"choices\": [\n    {\n      \"index\": 0,\n      \"message\": {\n        \"role\":
-        \"assistant\",\n        \"content\": \"Absolutely! To create compelling and
-        engaging AI articles that stand out, we need to go beyond surface-level discussions
-        and deliver fresh perspectives that challenge assumptions and spark curiosity.
-        Here are five unique angles with their highlight paragraphs that could really
-        captivate our readers:\\n\\n1. **The Hidden Psychology of AI Agents: How They
-        Learn Human Biases and What That Means for Our Future**  \\n*Highlight:* AI
-        agents don\u2019t just process data\u2014they absorb the subtle nuances and
-        biases embedded in human language, behavior, and culture. This article dives
-        deep into the psychological parallels between AI learning mechanisms and human
-        cognitive biases, revealing surprising ways AI can both mirror and amplify
-        our prejudices. Understanding these dynamics is crucial for building trustworthy
-        AI systems and reshaping the future relationship between humans and machines.\\n\\n2.
-        **From Assistants to Autonomous Creators: The Rise of AI Agents as Artists,
-        Writers, and Innovators**  \\n*Highlight:* What do we lose and gain when AI
-        agents start producing original art, literature, and innovations? This piece
-        explores groundbreaking examples where AI isn\u2019t just a tool but a creative
-        partner that challenges our definition of authorship and genius. We\u2019ll
-        examine ethical dilemmas, collaborative workflows, and the exciting frontier
-        where human intuition meets algorithmic originality.\\n\\n3. **AI Agents in
-        the Wild: How Decentralized Autonomous Organizations Could Redefine Economy
-        and Governance**  \\n*Highlight:* Imagine AI agents operating autonomously
-        in decentralized networks, making real-time decisions that affect finances,
-        resource management, and governance without human intervention. This article
-        uncovers how DAOs powered by AI agents might spontaneously evolve new forms
-        of organization\u2014transparent, efficient, and resistant to traditional
-        corruption. We\u2019ll investigate early case studies and speculate on how
-        this might disrupt centuries-old societal structures.\\n\\n4. **Beyond Chatbots:
-        The Next Generation of AI Agents as Empathetic Digital Companions**  \\n*Highlight:*
-        Moving past scripted conversations, emerging AI agents simulate empathy and
-        emotional intelligence in ways that can transform mental health care, education,
-        and companionship. This article provides an insider look at the complex algorithms
-        and biofeedback mechanisms enabling AI to recognize, respond to, and foster
-        human emotions\u2014potentially filling gaps in underserved populations while
-        raising profound questions about authenticity and connection.\\n\\n5. **The
-        Environmental Toll of AI Agents: Unmasking the Ecological Cost of Intelligent
-        Automation**  \\n*Highlight:* While AI promises efficiency and innovation,
-        the environmental footprint of training and deploying millions of AI agents
-        is rarely discussed. This eye-opening article quantifies the energy demands
-        of current models, challenges the narrative of AI as an unequivocal green
-        solution, and explores emerging approaches pathing toward sustainable intelligent
-        automation\u2014an urgent conversation for an increasingly eco-conscious tech
-        landscape.\\n\\nEach of these angles opens a door to rich storytelling that
-        blends technical depth, ethical inquiry, and visionary implications\u2014perfect
-        for readers hungry for insight that\u2019s both sophisticated and accessible.
-        Let me know which ones resonate most, or if you want me to refine any into
-        full article outlines!\",\n        \"refusal\": null,\n        \"annotations\":
-        []\n      },\n      \"logprobs\": null,\n      \"finish_reason\": \"stop\"\n
-        \   }\n  ],\n  \"usage\": {\n    \"prompt_tokens\": 188,\n    \"completion_tokens\":
-        595,\n    \"total_tokens\": 783,\n    \"prompt_tokens_details\": {\n      \"cached_tokens\":
-        0,\n      \"audio_tokens\": 0\n    },\n    \"completion_tokens_details\":
+        \"assistant\",\n        \"content\": \"1. **The Rise of Autonomous AI Agents:
+        Revolutionizing Everyday Tasks**  \\nImagine a world where AI agents autonomously
+        manage your daily schedule, optimize your work routines, and even handle complex
+        decision-making with minimal human intervention. An article exploring the
+        rise of autonomous AI agents would captivate readers by diving into how advancements
+        in machine learning and natural language processing have matured these agents
+        from simple chatbots to intelligent collaborators. Themes could include practical
+        applications in industries like healthcare, finance, and personal productivity,
+        the challenges of trust and transparency, and a glimpse into the ethical questions
+        surrounding AI autonomy. This topic not only showcases cutting-edge technology
+        but also invites readers to envision the near future of human-AI synergy.\\n\\n2.
+        **Building Ethical AI Agents: Balancing Innovation with Responsibility**  \\nAs
+        AI agents become more powerful and independent, the imperative to embed ethical
+        frameworks within their design comes sharply into focus. An insightful article
+        on this theme would engage readers by unpacking the complexities of programming
+        morality, fairness, and accountability into AI systems that influence critical
+        decisions\u2014whether in hiring processes, law enforcement, or digital content
+        moderation. Exploring real-world case studies alongside philosophical and
+        regulatory perspectives, the piece could illuminate the delicate balance between
+        technological innovation and societal values, offering a nuanced discussion
+        that appeals to technologists, ethicists, and everyday users alike.\\n\\n3.
+        **AI Agents in Startups: Accelerating Growth and Disrupting Markets**  \\nStartups
+        are uniquely positioned to leverage AI agents as game-changers that turbocharge
+        growth, optimize workflows, and unlock new business models. This article could
+        enthrall readers by detailing how nimble companies integrate AI-driven agents
+        for customer engagement, market analysis, and personalized product recommendations\u2014outpacing
+        larger incumbents. It would also examine hurdles such as data privacy, scaling
+        complexities, and the human-AI collaboration dynamic, providing actionable
+        insights for entrepreneurs and investors. The story of AI agents fueling startup
+        innovation not only inspires but also outlines the practical pathways and
+        pitfalls on the frontier of modern entrepreneurship.\\n\\n4. **The Future
+        of Work with AI Agents: Redefining Roles and Skills**  \\nAI agents are redefining
+        professional landscapes by automating routine tasks and augmenting human creativity
+        and decision-making. An article on this topic could engage readers by painting
+        a vivid picture of the evolving workplace, where collaboration between humans
+        and AI agents becomes the norm. Delving into emerging roles, necessary skill
+        sets, and how education and training must adapt, the piece would offer a forward-thinking
+        analysis that resonates deeply with employees, managers, and policymakers.
+        Exploring themes of workforce transformation, productivity gains, and potential
+        socioeconomic impacts, it provides a comprehensive outlook on an AI-integrated
+        work environment.\\n\\n5. **From Reactive to Proactive: How Next-Gen AI Agents
+        Anticipate Needs**  \\nThe leap from reactive AI assistants to truly proactive
+        AI agents signifies one of the most thrilling advances in artificial intelligence.
+        An article centered on this evolution would captivate readers by illustrating
+        how these agents utilize predictive analytics, contextual understanding, and
+        continuous learning to anticipate user needs before they are expressed. By
+        showcasing pioneering applications in personalized healthcare management,
+        smart homes, and adaptive learning platforms, the article would highlight
+        the profound shift toward intuitive, anticipatory technology. This theme not
+        only excites with futuristic promise but also probes the technical and privacy
+        challenges that come with increased agency and foresight.\",\n        \"refusal\":
+        null,\n        \"annotations\": []\n      },\n      \"logprobs\": null,\n
+        \     \"finish_reason\": \"stop\"\n    }\n  ],\n  \"usage\": {\n    \"prompt_tokens\":
+        197,\n    \"completion_tokens\": 666,\n    \"total_tokens\": 863,\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\": \"fp_ae0f8c9a7b\"\n}\n"
+        \"default\",\n  \"system_fingerprint\": \"fp_d45f83c5fd\"\n}\n"
     headers:
       CF-Cache-Status:
       - DYNAMIC
       CF-Ray:
-      - 9db938b0489680d4-EWR
+      - 9ea3cb1cbfe2b312-TPE
       Connection:
       - keep-alive
       Content-Type:
       - application/json
       Date:
-      - Fri, 13 Mar 2026 07:11:02 GMT
+      - Fri, 10 Apr 2026 18:25:28 GMT
       Server:
       - cloudflare
       Strict-Transport-Security:
@@ -428,7 +442,7 @@ interactions:
       openai-organization:
       - OPENAI-ORG-XXX
       openai-processing-ms:
-      - '8310'
+      - '9479'
       openai-project:
       - OPENAI-PROJECT-XXX
       openai-version:
@@ -467,91 +481,105 @@ interactions:
       good an article about this topic could be. Return the list of ideas with their
       paragraph and your notes.\\n\\nThis is the expected criteria for your final
       answer: 5 bullet points with a paragraph for each idea.\\nyou MUST return the
-      actual complete content as the final answer, not a summary.\"},{\"role\":\"assistant\",\"content\":null,\"tool_calls\":[{\"id\":\"call_G2i9RJGNXKVfnd8ZTaBG8Fwi\",\"type\":\"function\",\"function\":{\"name\":\"ask_question_to_coworker\",\"arguments\":\"{\\\"question\\\":
-      \\\"What are some trending topics or ideas in various fields that could be explored
-      for an article?\\\", \\\"context\\\": \\\"We need to generate a list of 5 interesting
-      ideas to explore for an article. These ideas should be engaging and relevant
-      to current trends or captivating subjects.\\\", \\\"coworker\\\": \\\"Researcher\\\"}\"}},{\"id\":\"call_j4KH2SGZvNeioql0HcRQ9NTp\",\"type\":\"function\",\"function\":{\"name\":\"ask_question_to_coworker\",\"arguments\":\"{\\\"question\\\":
-      \\\"What unique angles or perspectives could we explore to make articles more
-      compelling and engaging?\\\", \\\"context\\\": \\\"Our task involves coming
-      up with 5 ideas for articles, each with an exciting paragraph highlight that
-      illustrates the promise and intrigue of the topic. We want them to be more than
-      generic concepts, shining for readers with fresh insights or engaging twists.\\\",
-      \\\"coworker\\\": \\\"Senior Writer\\\"}\"}}]},{\"role\":\"tool\",\"tool_call_id\":\"call_G2i9RJGNXKVfnd8ZTaBG8Fwi\",\"name\":\"ask_question_to_coworker\",\"content\":\"Here
-      are five trending and engaging topics across various fields that could be explored
-      for an article:\\n\\n1. **The Rise of Autonomous AI Agents and Their Impact
-      on the Future of Work**  \\nExplore how autonomous AI agents\u2014systems capable
-      of performing complex tasks independently\u2014are transforming industries such
-      as customer service, software development, and logistics. Discuss implications
-      for job automation, human-AI collaboration, and ethical considerations surrounding
-      decision-making autonomy.\\n\\n2. **Generative AI Beyond Text: Innovations in
-      Audio, Video, and 3D Content Creation**  \\nDelve into advancements in generative
-      AI models that create not only text but also realistic audio, video content,
-      virtual environments, and 3D models. Highlight applications in gaming, entertainment,
-      education, and digital marketing, as well as challenges like misinformation
-      and deepfake detection.\\n\\n3. **AI-Driven Climate Modeling: Enhancing Predictive
-      Accuracy to Combat Climate Change**  \\nExamine how AI and machine learning
-      are improving climate models by analyzing vast datasets, uncovering patterns,
-      and simulating environmental scenarios. Discuss how these advances are aiding
-      policymakers in making informed decisions to address climate risks and sustainability
-      goals.\\n\\n4. **The Ethical Frontiers of AI in Healthcare: Balancing Innovation
-      with Patient Privacy**  \\nInvestigate ethical challenges posed by AI applications
-      in healthcare, including diagnosis, personalized treatment, and patient data
-      management. Focus on balancing rapid technological innovation with privacy,
-      bias mitigation, and regulatory frameworks to ensure equitable access and trust.\\n\\n5.
-      **Quantum Computing Meets AI: Exploring the Next Leap in Computational Power**
-      \ \\nCover the intersection of quantum computing and artificial intelligence,
-      exploring how quantum algorithms could accelerate AI training processes and
-      solve problems beyond the reach of classical computers. Outline current research,
-      potential breakthroughs, and the timeline for real-world applications.\\n\\nEach
-      of these topics is timely, relevant, and has the potential to engage readers
-      interested in cutting-edge technology, societal impact, and future trends. Let
-      me know if you want me to help develop an outline or deeper research into any
-      of these areas!\"},{\"role\":\"tool\",\"tool_call_id\":\"call_j4KH2SGZvNeioql0HcRQ9NTp\",\"name\":\"ask_question_to_coworker\",\"content\":\"Absolutely!
-      To create compelling and engaging AI articles that stand out, we need to go
-      beyond surface-level discussions and deliver fresh perspectives that challenge
-      assumptions and spark curiosity. Here are five unique angles with their highlight
-      paragraphs that could really captivate our readers:\\n\\n1. **The Hidden Psychology
-      of AI Agents: How They Learn Human Biases and What That Means for Our Future**
-      \ \\n*Highlight:* AI agents don\u2019t just process data\u2014they absorb the
-      subtle nuances and biases embedded in human language, behavior, and culture.
-      This article dives deep into the psychological parallels between AI learning
-      mechanisms and human cognitive biases, revealing surprising ways AI can both
-      mirror and amplify our prejudices. Understanding these dynamics is crucial for
-      building trustworthy AI systems and reshaping the future relationship between
-      humans and machines.\\n\\n2. **From Assistants to Autonomous Creators: The Rise
-      of AI Agents as Artists, Writers, and Innovators**  \\n*Highlight:* What do
-      we lose and gain when AI agents start producing original art, literature, and
-      innovations? This piece explores groundbreaking examples where AI isn\u2019t
-      just a tool but a creative partner that challenges our definition of authorship
-      and genius. We\u2019ll examine ethical dilemmas, collaborative workflows, and
-      the exciting frontier where human intuition meets algorithmic originality.\\n\\n3.
-      **AI Agents in the Wild: How Decentralized Autonomous Organizations Could Redefine
-      Economy and Governance**  \\n*Highlight:* Imagine AI agents operating autonomously
-      in decentralized networks, making real-time decisions that affect finances,
-      resource management, and governance without human intervention. This article
-      uncovers how DAOs powered by AI agents might spontaneously evolve new forms
-      of organization\u2014transparent, efficient, and resistant to traditional corruption.
-      We\u2019ll investigate early case studies and speculate on how this might disrupt
-      centuries-old societal structures.\\n\\n4. **Beyond Chatbots: The Next Generation
-      of AI Agents as Empathetic Digital Companions**  \\n*Highlight:* Moving past
-      scripted conversations, emerging AI agents simulate empathy and emotional intelligence
-      in ways that can transform mental health care, education, and companionship.
-      This article provides an insider look at the complex algorithms and biofeedback
-      mechanisms enabling AI to recognize, respond to, and foster human emotions\u2014potentially
-      filling gaps in underserved populations while raising profound questions about
-      authenticity and connection.\\n\\n5. **The Environmental Toll of AI Agents:
-      Unmasking the Ecological Cost of Intelligent Automation**  \\n*Highlight:* While
-      AI promises efficiency and innovation, the environmental footprint of training
-      and deploying millions of AI agents is rarely discussed. This eye-opening article
-      quantifies the energy demands of current models, challenges the narrative of
-      AI as an unequivocal green solution, and explores emerging approaches pathing
-      toward sustainable intelligent automation\u2014an urgent conversation for an
-      increasingly eco-conscious tech landscape.\\n\\nEach of these angles opens a
-      door to rich storytelling that blends technical depth, ethical inquiry, and
-      visionary implications\u2014perfect for readers hungry for insight that\u2019s
-      both sophisticated and accessible. Let me know which ones resonate most, or
-      if you want me to refine any into full article outlines!\"},{\"role\":\"user\",\"content\":\"Analyze
+      actual complete content as the final answer, not a summary.\"},{\"role\":\"assistant\",\"content\":null,\"tool_calls\":[{\"id\":\"call_BCh6lXsBTdixRuRh6OTBPoIJ\",\"type\":\"function\",\"function\":{\"name\":\"delegate_work_to_coworker\",\"arguments\":\"{\\\"task\\\":
+      \\\"Come up with a list of 5 interesting ideas to explore for an article.\\\",
+      \\\"context\\\": \\\"We need five intriguing ideas worth exploring for an article.
+      Each idea should have potential for in-depth exploration and appeal to a broad
+      audience, possibly touching on current trends, historical insights, future possibilities,
+      or human interest stories.\\\", \\\"coworker\\\": \\\"Researcher\\\"}\"}},{\"id\":\"call_rAQFeCrS4ogsqvIWRGAYFHGI\",\"type\":\"function\",\"function\":{\"name\":\"delegate_work_to_coworker\",\"arguments\":\"{\\\"task\\\":
+      \\\"Write one amazing paragraph highlight for each of 5 ideas that showcases
+      how good an article about this topic could be.\\\", \\\"context\\\": \\\"Upon
+      receiving five intriguing ideas from the Researcher, create a compelling paragraph
+      for each idea that highlights its potential as a fascinating article. These
+      paragraphs must capture the essence of the topic and explain why it would captivate
+      readers, incorporating possible themes and insights.\\\", \\\"coworker\\\":
+      \\\"Senior Writer\\\"}\"}}]},{\"role\":\"tool\",\"tool_call_id\":\"call_BCh6lXsBTdixRuRh6OTBPoIJ\",\"name\":\"delegate_work_to_coworker\",\"content\":\"Certainly!
+      Here are five intriguing article ideas that offer rich potential for deep exploration
+      and broad audience appeal, especially aligned with current trends and human
+      interest in AI and technology:\\n\\n1. **The Evolution of AI Agents: From Rule-Based
+      Bots to Autonomous Decision Makers**  \\n   Explore the historical development
+      of AI agents, tracing the journey from simple scripted chatbots to advanced
+      autonomous systems capable of complex decision-making and learning. Dive into
+      key technological milestones, breakthroughs in machine learning, and current
+      state-of-the-art AI agents. Discuss implications for industries such as customer
+      service, healthcare, and autonomous vehicles, highlighting both opportunities
+      and ethical concerns.\\n\\n2. **AI in Daily Life: How Intelligent Agents Are
+      Reshaping Human Routines**  \\n   Investigate the integration of AI agents in
+      everyday life\u2014from virtual assistants like Siri and Alexa to personalized
+      recommendation systems and smart home devices. Analyze how these AI tools influence
+      productivity, privacy, and social behavior. Include human interest elements
+      through stories of individuals or communities who have embraced or resisted
+      these technologies.\\n\\n3. **The Future of Work: AI Agents as Collaborative
+      Colleagues**  \\n   Examine how AI agents are transforming workplaces by acting
+      as collaborators rather than just tools. Cover applications in creative fields,
+      data analysis, and decision support, while addressing potential challenges such
+      as job displacement, new skill requirements, and the evolving definition of
+      teamwork. Use expert opinions and case studies to paint a nuanced future outlook.\\n\\n4.
+      **Ethics and Accountability in AI Agent Development**  \\n   Delve into the
+      ethical dilemmas posed by increasingly autonomous AI agents\u2014topics like
+      bias in algorithms, data privacy, and accountability for AI-driven decisions.
+      Explore measures being taken globally to regulate AI, frameworks for responsible
+      AI development, and the role of public awareness. Include historical context
+      about technology ethics to provide depth.\\n\\n5. **Human-AI Symbiosis: Stories
+      of Innovative Partnerships Shaping Our World**  \\n   Tell compelling human
+      interest stories about individuals or organizations pioneering collaborative
+      projects with AI agents that lead to breakthroughs in science, art, or social
+      good. Highlight how these partnerships transcend traditional human-machine interaction
+      and open new creative and problem-solving possibilities, inspiring readers about
+      the potential of human-AI synergy.\\n\\nThese ideas are designed to be both
+      engaging and informative, offering multiple angles\u2014technical, historical,
+      ethical, and personal\u2014to keep readers captivated while providing substantial
+      content for in-depth analysis.\"},{\"role\":\"tool\",\"tool_call_id\":\"call_rAQFeCrS4ogsqvIWRGAYFHGI\",\"name\":\"delegate_work_to_coworker\",\"content\":\"1.
+      **The Rise of Autonomous AI Agents: Revolutionizing Everyday Tasks**  \\nImagine
+      a world where AI agents autonomously manage your daily schedule, optimize your
+      work routines, and even handle complex decision-making with minimal human intervention.
+      An article exploring the rise of autonomous AI agents would captivate readers
+      by diving into how advancements in machine learning and natural language processing
+      have matured these agents from simple chatbots to intelligent collaborators.
+      Themes could include practical applications in industries like healthcare, finance,
+      and personal productivity, the challenges of trust and transparency, and a glimpse
+      into the ethical questions surrounding AI autonomy. This topic not only showcases
+      cutting-edge technology but also invites readers to envision the near future
+      of human-AI synergy.\\n\\n2. **Building Ethical AI Agents: Balancing Innovation
+      with Responsibility**  \\nAs AI agents become more powerful and independent,
+      the imperative to embed ethical frameworks within their design comes sharply
+      into focus. An insightful article on this theme would engage readers by unpacking
+      the complexities of programming morality, fairness, and accountability into
+      AI systems that influence critical decisions\u2014whether in hiring processes,
+      law enforcement, or digital content moderation. Exploring real-world case studies
+      alongside philosophical and regulatory perspectives, the piece could illuminate
+      the delicate balance between technological innovation and societal values, offering
+      a nuanced discussion that appeals to technologists, ethicists, and everyday
+      users alike.\\n\\n3. **AI Agents in Startups: Accelerating Growth and Disrupting
+      Markets**  \\nStartups are uniquely positioned to leverage AI agents as game-changers
+      that turbocharge growth, optimize workflows, and unlock new business models.
+      This article could enthrall readers by detailing how nimble companies integrate
+      AI-driven agents for customer engagement, market analysis, and personalized
+      product recommendations\u2014outpacing larger incumbents. It would also examine
+      hurdles such as data privacy, scaling complexities, and the human-AI collaboration
+      dynamic, providing actionable insights for entrepreneurs and investors. The
+      story of AI agents fueling startup innovation not only inspires but also outlines
+      the practical pathways and pitfalls on the frontier of modern entrepreneurship.\\n\\n4.
+      **The Future of Work with AI Agents: Redefining Roles and Skills**  \\nAI agents
+      are redefining professional landscapes by automating routine tasks and augmenting
+      human creativity and decision-making. An article on this topic could engage
+      readers by painting a vivid picture of the evolving workplace, where collaboration
+      between humans and AI agents becomes the norm. Delving into emerging roles,
+      necessary skill sets, and how education and training must adapt, the piece would
+      offer a forward-thinking analysis that resonates deeply with employees, managers,
+      and policymakers. Exploring themes of workforce transformation, productivity
+      gains, and potential socioeconomic impacts, it provides a comprehensive outlook
+      on an AI-integrated work environment.\\n\\n5. **From Reactive to Proactive:
+      How Next-Gen AI Agents Anticipate Needs**  \\nThe leap from reactive AI assistants
+      to truly proactive AI agents signifies one of the most thrilling advances in
+      artificial intelligence. An article centered on this evolution would captivate
+      readers by illustrating how these agents utilize predictive analytics, contextual
+      understanding, and continuous learning to anticipate user needs before they
+      are expressed. By showcasing pioneering applications in personalized healthcare
+      management, smart homes, and adaptive learning platforms, the article would
+      highlight the profound shift toward intuitive, anticipatory technology. This
+      theme not only excites with futuristic promise but also probes the technical
+      and privacy challenges that come with increased agency and foresight.\"},{\"role\":\"user\",\"content\":\"Analyze
       the tool result. If requirements are met, provide the Final Answer. Otherwise,
       call the next tool. Deliver only the answer without meta-commentary.\"}],\"model\":\"gpt-4o\",\"tool_choice\":\"auto\",\"tools\":[{\"type\":\"function\",\"function\":{\"name\":\"delegate_work_to_coworker\",\"description\":\"Delegate
       a specific task to one of the following coworkers: Researcher, Senior Writer\\nThe
@@ -582,7 +610,7 @@ interactions:
       connection:
       - keep-alive
       content-length:
-      - '9923'
+      - '11056'
       content-type:
       - application/json
       cookie:
@@ -598,7 +626,7 @@ interactions:
       x-stainless-os:
       - X-STAINLESS-OS-XXX
       x-stainless-package-version:
-      - 1.83.0
+      - 2.31.0
       x-stainless-read-timeout:
       - X-STAINLESS-READ-TIMEOUT-XXX
       x-stainless-retry-count:
@@ -606,58 +634,64 @@ 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
   response:
     body:
-      string: "{\n  \"id\": \"chatcmpl-DIqxidsfoqQl7qXSIVHfSCyETUwlU\",\n  \"object\":
-        \"chat.completion\",\n  \"created\": 1773385862,\n  \"model\": \"gpt-4o-2024-08-06\",\n
+      string: "{\n  \"id\": \"chatcmpl-DTApljTaq8nDgNMS21B319i56seCn\",\n  \"object\":
+        \"chat.completion\",\n  \"created\": 1775845529,\n  \"model\": \"gpt-4o-2024-08-06\",\n
         \ \"choices\": [\n    {\n      \"index\": 0,\n      \"message\": {\n        \"role\":
-        \"assistant\",\n        \"content\": \"1. **The Rise of Autonomous AI Agents
-        and Their Impact on the Future of Work**  \\nExplore how autonomous AI agents\u2014systems
-        capable of performing complex tasks independently\u2014are transforming industries
-        such as customer service, software development, and logistics. Discuss implications
-        for job automation, human-AI collaboration, and ethical considerations surrounding
-        decision-making autonomy.\\n\\n2. **Generative AI Beyond Text: Innovations
-        in Audio, Video, and 3D Content Creation**  \\nDelve into advancements in
-        generative AI models that create not only text but also realistic audio, video
-        content, virtual environments, and 3D models. Highlight applications in gaming,
-        entertainment, education, and digital marketing, as well as challenges like
-        misinformation and deepfake detection.\\n\\n3. **AI-Driven Climate Modeling:
-        Enhancing Predictive Accuracy to Combat Climate Change**  \\nExamine how AI
-        and machine learning are improving climate models by analyzing vast datasets,
-        uncovering patterns, and simulating environmental scenarios. Discuss how these
-        advances are aiding policymakers in making informed decisions to address climate
-        risks and sustainability goals.\\n\\n4. **The Ethical Frontiers of AI in Healthcare:
-        Balancing Innovation with Patient Privacy**  \\nInvestigate ethical challenges
-        posed by AI applications in healthcare, including diagnosis, personalized
-        treatment, and patient data management. Focus on balancing rapid technological
-        innovation with privacy, bias mitigation, and regulatory frameworks to ensure
-        equitable access and trust.\\n\\n5. **Quantum Computing Meets AI: Exploring
-        the Next Leap in Computational Power**  \\nCover the intersection of quantum
-        computing and artificial intelligence, exploring how quantum algorithms could
-        accelerate AI training processes and solve problems beyond the reach of classical
-        computers. Outline current research, potential breakthroughs, and the timeline
-        for real-world applications.\",\n        \"refusal\": null,\n        \"annotations\":
-        []\n      },\n      \"logprobs\": null,\n      \"finish_reason\": \"stop\"\n
-        \   }\n  ],\n  \"usage\": {\n    \"prompt_tokens\": 1748,\n    \"completion_tokens\":
-        335,\n    \"total_tokens\": 2083,\n    \"prompt_tokens_details\": {\n      \"cached_tokens\":
+        \"assistant\",\n        \"content\": \"- **The Evolution of AI Agents: From
+        Rule-Based Bots to Autonomous Decision Makers**  \\n   Explore the historical
+        development of AI agents, tracing the journey from simple scripted chatbots
+        to advanced autonomous systems capable of complex decision-making and learning.
+        Dive into key technological milestones, breakthroughs in machine learning,
+        and current state-of-the-art AI agents. Discuss implications for industries
+        such as customer service, healthcare, and autonomous vehicles, highlighting
+        both opportunities and ethical concerns.\\n\\n- **AI in Daily Life: How Intelligent
+        Agents Are Reshaping Human Routines**  \\n   Investigate the integration of
+        AI agents in everyday life\u2014from virtual assistants like Siri and Alexa
+        to personalized recommendation systems and smart home devices. Analyze how
+        these AI tools influence productivity, privacy, and social behavior. Include
+        human interest elements through stories of individuals or communities who
+        have embraced or resisted these technologies.\\n\\n- **The Future of Work:
+        AI Agents as Collaborative Colleagues**  \\n   Examine how AI agents are transforming
+        workplaces by acting as collaborators rather than just tools. Cover applications
+        in creative fields, data analysis, and decision support, while addressing
+        potential challenges such as job displacement, new skill requirements, and
+        the evolving definition of teamwork. Use expert opinions and case studies
+        to paint a nuanced future outlook.\\n\\n- **Ethics and Accountability in AI
+        Agent Development**  \\n   Delve into the ethical dilemmas posed by increasingly
+        autonomous AI agents\u2014topics like bias in algorithms, data privacy, and
+        accountability for AI-driven decisions. Explore measures being taken globally
+        to regulate AI, frameworks for responsible AI development, and the role of
+        public awareness. Include historical context about technology ethics to provide
+        depth.\\n\\n- **Human-AI Symbiosis: Stories of Innovative Partnerships Shaping
+        Our World**  \\n   Tell compelling human interest stories about individuals
+        or organizations pioneering collaborative projects with AI agents that lead
+        to breakthroughs in science, art, or social good. Highlight how these partnerships
+        transcend traditional human-machine interaction and open new creative and
+        problem-solving possibilities, inspiring readers about the potential of human-AI
+        synergy.\",\n        \"refusal\": null,\n        \"annotations\": []\n      },\n
+        \     \"logprobs\": null,\n      \"finish_reason\": \"stop\"\n    }\n  ],\n
+        \ \"usage\": {\n    \"prompt_tokens\": 1903,\n    \"completion_tokens\": 399,\n
+        \   \"total_tokens\": 2302,\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\": \"fp_b7c8e3f100\"\n}\n"
+        \"default\",\n  \"system_fingerprint\": \"fp_df40ab6c25\"\n}\n"
     headers:
       CF-Cache-Status:
       - DYNAMIC
       CF-Ray:
-      - 9db938e60d5bc5e7-EWR
+      - 9ea3cb5a6957b301-TPE
       Connection:
       - keep-alive
       Content-Type:
       - application/json
       Date:
-      - Fri, 13 Mar 2026 07:11:04 GMT
+      - Fri, 10 Apr 2026 18:25:31 GMT
       Server:
       - cloudflare
       Strict-Transport-Security:
@@ -673,7 +707,7 @@ interactions:
       openai-organization:
       - OPENAI-ORG-XXX
       openai-processing-ms:
-      - '2009'
+      - '2183'
       openai-project:
       - OPENAI-PROJECT-XXX
       openai-version:

lib/crewai/tests/cli/deploy/test_deploy_main.py

@@ -125,7 +125,7 @@ class TestDeployCommand(unittest.TestCase):
         mock_response.json.return_value = {"uuid": "test-uuid"}
         self.mock_client.deploy_by_uuid.return_value = mock_response
 
-        self.deploy_command.deploy(uuid="test-uuid")
+        self.deploy_command.deploy(uuid="test-uuid", skip_validate=True)
 
         self.mock_client.deploy_by_uuid.assert_called_once_with("test-uuid")
         mock_display.assert_called_once_with({"uuid": "test-uuid"})
@@ -137,7 +137,7 @@ class TestDeployCommand(unittest.TestCase):
         mock_response.json.return_value = {"uuid": "test-uuid"}
         self.mock_client.deploy_by_name.return_value = mock_response
 
-        self.deploy_command.deploy()
+        self.deploy_command.deploy(skip_validate=True)
 
         self.mock_client.deploy_by_name.assert_called_once_with("test_project")
         mock_display.assert_called_once_with({"uuid": "test-uuid"})
@@ -156,7 +156,7 @@ class TestDeployCommand(unittest.TestCase):
         self.mock_client.create_crew.return_value = mock_response
 
         with patch("sys.stdout", new=StringIO()) as fake_out:
-            self.deploy_command.create_crew()
+            self.deploy_command.create_crew(skip_validate=True)
             self.assertIn("Deployment created successfully!", fake_out.getvalue())
             self.assertIn("new-uuid", fake_out.getvalue())
 

lib/crewai/tests/cli/deploy/test_validate.py

@@ -0,0 +1,430 @@
+"""Tests for `crewai.cli.deploy.validate`.
+
+The fixtures here correspond 1:1 to the deployment-failure patterns observed
+in the #crewai-deployment-failures Slack channel that motivated this work.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from textwrap import dedent
+from typing import Iterable
+from unittest.mock import patch
+
+import pytest
+
+from crewai.cli.deploy.validate import (
+    DeployValidator,
+    Severity,
+    normalize_package_name,
+)
+
+
+def _make_pyproject(
+    name: str = "my_crew",
+    dependencies: Iterable[str] = ("crewai>=1.14.0",),
+    *,
+    hatchling: bool = False,
+    flow: bool = False,
+    extra: str = "",
+) -> str:
+    deps = ", ".join(f'"{d}"' for d in dependencies)
+    lines = [
+        "[project]",
+        f'name = "{name}"',
+        'version = "0.1.0"',
+        f"dependencies = [{deps}]",
+    ]
+    if hatchling:
+        lines += [
+            "",
+            "[build-system]",
+            'requires = ["hatchling"]',
+            'build-backend = "hatchling.build"',
+        ]
+    if flow:
+        lines += ["", "[tool.crewai]", 'type = "flow"']
+    if extra:
+        lines += ["", extra]
+    return "\n".join(lines) + "\n"
+
+
+def _scaffold_standard_crew(
+    root: Path,
+    *,
+    name: str = "my_crew",
+    include_crew_py: bool = True,
+    include_agents_yaml: bool = True,
+    include_tasks_yaml: bool = True,
+    include_lockfile: bool = True,
+    pyproject: str | None = None,
+) -> Path:
+    (root / "pyproject.toml").write_text(pyproject or _make_pyproject(name=name))
+    if include_lockfile:
+        (root / "uv.lock").write_text("# dummy uv lockfile\n")
+
+    pkg_dir = root / "src" / normalize_package_name(name)
+    pkg_dir.mkdir(parents=True)
+    (pkg_dir / "__init__.py").write_text("")
+
+    if include_crew_py:
+        (pkg_dir / "crew.py").write_text(
+            dedent(
+                """
+                from crewai.project import CrewBase, crew
+
+                @CrewBase
+                class MyCrew:
+                    agents_config = "config/agents.yaml"
+                    tasks_config = "config/tasks.yaml"
+
+                    @crew
+                    def crew(self):
+                        from crewai import Crew
+                        return Crew(agents=[], tasks=[])
+                """
+            ).strip()
+            + "\n"
+        )
+
+    config_dir = pkg_dir / "config"
+    config_dir.mkdir()
+    if include_agents_yaml:
+        (config_dir / "agents.yaml").write_text("{}\n")
+    if include_tasks_yaml:
+        (config_dir / "tasks.yaml").write_text("{}\n")
+
+    return pkg_dir
+
+
+def _codes(validator: DeployValidator) -> set[str]:
+    return {r.code for r in validator.results}
+
+
+def _run_without_import_check(root: Path) -> DeployValidator:
+    """Run validation with the subprocess-based import check stubbed out;
+    the classifier is exercised directly in its own tests below."""
+    with patch.object(DeployValidator, "_check_module_imports", lambda self: None):
+        v = DeployValidator(project_root=root)
+        v.run()
+    return v
+
+
+@pytest.mark.parametrize(
+    "project_name, expected",
+    [
+        ("my-crew", "my_crew"),
+        ("My Cool-Project", "my_cool_project"),
+        ("crew123", "crew123"),
+        ("crew.name!with$chars", "crewnamewithchars"),
+    ],
+)
+def test_normalize_package_name(project_name: str, expected: str) -> None:
+    assert normalize_package_name(project_name) == expected
+
+
+def test_valid_standard_crew_project_passes(tmp_path: Path) -> None:
+    _scaffold_standard_crew(tmp_path)
+    v = _run_without_import_check(tmp_path)
+    assert v.ok, f"expected clean run, got {v.results}"
+
+
+def test_missing_pyproject_errors(tmp_path: Path) -> None:
+    v = _run_without_import_check(tmp_path)
+    assert "missing_pyproject" in _codes(v)
+    assert not v.ok
+
+
+def test_invalid_pyproject_errors(tmp_path: Path) -> None:
+    (tmp_path / "pyproject.toml").write_text("this is not valid toml ====\n")
+    v = _run_without_import_check(tmp_path)
+    assert "invalid_pyproject" in _codes(v)
+
+
+def test_missing_project_name_errors(tmp_path: Path) -> None:
+    (tmp_path / "pyproject.toml").write_text(
+        '[project]\nversion = "0.1.0"\ndependencies = ["crewai>=1.14.0"]\n'
+    )
+    v = _run_without_import_check(tmp_path)
+    assert "missing_project_name" in _codes(v)
+
+
+def test_missing_lockfile_errors(tmp_path: Path) -> None:
+    _scaffold_standard_crew(tmp_path, include_lockfile=False)
+    v = _run_without_import_check(tmp_path)
+    assert "missing_lockfile" in _codes(v)
+
+
+def test_poetry_lock_is_accepted(tmp_path: Path) -> None:
+    _scaffold_standard_crew(tmp_path, include_lockfile=False)
+    (tmp_path / "poetry.lock").write_text("# poetry lockfile\n")
+    v = _run_without_import_check(tmp_path)
+    assert "missing_lockfile" not in _codes(v)
+
+
+def test_stale_lockfile_warns(tmp_path: Path) -> None:
+    _scaffold_standard_crew(tmp_path)
+    # Make lockfile older than pyproject.
+    lock = tmp_path / "uv.lock"
+    pyproject = tmp_path / "pyproject.toml"
+    old_time = pyproject.stat().st_mtime - 60
+    import os
+
+    os.utime(lock, (old_time, old_time))
+    v = _run_without_import_check(tmp_path)
+    assert "stale_lockfile" in _codes(v)
+    # Stale is a warning, so the run can still be ok (no errors).
+    assert v.ok
+
+
+def test_missing_package_dir_errors(tmp_path: Path) -> None:
+    # pyproject says name=my_crew but we only create src/other_pkg/
+    (tmp_path / "pyproject.toml").write_text(_make_pyproject(name="my_crew"))
+    (tmp_path / "uv.lock").write_text("")
+    (tmp_path / "src" / "other_pkg").mkdir(parents=True)
+    v = _run_without_import_check(tmp_path)
+    codes = _codes(v)
+    assert "missing_package_dir" in codes
+    finding = next(r for r in v.results if r.code == "missing_package_dir")
+    assert "other_pkg" in finding.hint
+
+
+def test_egg_info_only_errors_with_targeted_hint(tmp_path: Path) -> None:
+    """Regression for the case where only src/<name>.egg-info/ exists."""
+    (tmp_path / "pyproject.toml").write_text(_make_pyproject(name="odoo_pm_agents"))
+    (tmp_path / "uv.lock").write_text("")
+    (tmp_path / "src" / "odoo_pm_agents.egg-info").mkdir(parents=True)
+    v = _run_without_import_check(tmp_path)
+    finding = next(r for r in v.results if r.code == "missing_package_dir")
+    assert "egg-info" in finding.hint
+
+
+def test_stale_egg_info_sibling_warns(tmp_path: Path) -> None:
+    _scaffold_standard_crew(tmp_path)
+    (tmp_path / "src" / "my_crew.egg-info").mkdir()
+    v = _run_without_import_check(tmp_path)
+    assert "stale_egg_info" in _codes(v)
+
+
+def test_missing_crew_py_errors(tmp_path: Path) -> None:
+    _scaffold_standard_crew(tmp_path, include_crew_py=False)
+    v = _run_without_import_check(tmp_path)
+    assert "missing_crew_py" in _codes(v)
+
+
+def test_missing_agents_yaml_errors(tmp_path: Path) -> None:
+    _scaffold_standard_crew(tmp_path, include_agents_yaml=False)
+    v = _run_without_import_check(tmp_path)
+    assert "missing_agents_yaml" in _codes(v)
+
+
+def test_missing_tasks_yaml_errors(tmp_path: Path) -> None:
+    _scaffold_standard_crew(tmp_path, include_tasks_yaml=False)
+    v = _run_without_import_check(tmp_path)
+    assert "missing_tasks_yaml" in _codes(v)
+
+
+def test_flow_project_requires_main_py(tmp_path: Path) -> None:
+    (tmp_path / "pyproject.toml").write_text(
+        _make_pyproject(name="my_flow", flow=True)
+    )
+    (tmp_path / "uv.lock").write_text("")
+    (tmp_path / "src" / "my_flow").mkdir(parents=True)
+    v = _run_without_import_check(tmp_path)
+    assert "missing_flow_main" in _codes(v)
+
+
+def test_flow_project_with_main_py_passes(tmp_path: Path) -> None:
+    (tmp_path / "pyproject.toml").write_text(
+        _make_pyproject(name="my_flow", flow=True)
+    )
+    (tmp_path / "uv.lock").write_text("")
+    pkg = tmp_path / "src" / "my_flow"
+    pkg.mkdir(parents=True)
+    (pkg / "main.py").write_text("# flow entrypoint\n")
+    v = _run_without_import_check(tmp_path)
+    assert "missing_flow_main" not in _codes(v)
+
+
+def test_hatchling_without_wheel_config_passes_when_pkg_dir_matches(
+    tmp_path: Path,
+) -> None:
+    _scaffold_standard_crew(
+        tmp_path, pyproject=_make_pyproject(name="my_crew", hatchling=True)
+    )
+    v = _run_without_import_check(tmp_path)
+    # src/my_crew/ exists, so hatch default should find it — no wheel error.
+    assert "hatch_wheel_target_missing" not in _codes(v)
+
+
+def test_hatchling_with_explicit_wheel_config_passes(tmp_path: Path) -> None:
+    extra = (
+        "[tool.hatch.build.targets.wheel]\n"
+        'packages = ["src/my_crew"]'
+    )
+    _scaffold_standard_crew(
+        tmp_path,
+        pyproject=_make_pyproject(name="my_crew", hatchling=True, extra=extra),
+    )
+    v = _run_without_import_check(tmp_path)
+    assert "hatch_wheel_target_missing" not in _codes(v)
+
+
+def test_classify_missing_openai_key_is_warning(tmp_path: Path) -> None:
+    v = DeployValidator(project_root=tmp_path)
+    v._classify_import_error(
+        "ImportError",
+        "Error importing native provider: 1 validation error for OpenAICompletion\n"
+        "  Value error, OPENAI_API_KEY is required",
+        tb="",
+    )
+    assert len(v.results) == 1
+    result = v.results[0]
+    assert result.code == "llm_init_missing_key"
+    assert result.severity is Severity.WARNING
+    assert "OPENAI_API_KEY" in result.title
+
+
+def test_classify_azure_extra_missing_is_error(tmp_path: Path) -> None:
+    """The real message raised by the Azure provider module uses plain
+    double quotes around the install command (no backticks). Match the
+    exact string that ships in the provider source so this test actually
+    guards the regex used in production."""
+    v = DeployValidator(project_root=tmp_path)
+    v._classify_import_error(
+        "ImportError",
+        'Azure AI Inference native provider not available, to install: uv add "crewai[azure-ai-inference]"',
+        tb="",
+    )
+    assert "missing_provider_extra" in _codes(v)
+    finding = next(r for r in v.results if r.code == "missing_provider_extra")
+    assert finding.title.startswith("Azure AI Inference")
+    assert 'uv add "crewai[azure-ai-inference]"' in finding.hint
+
+
+@pytest.mark.parametrize(
+    "pkg_label, install_cmd",
+    [
+        ("Anthropic", 'uv add "crewai[anthropic]"'),
+        ("AWS Bedrock", 'uv add "crewai[bedrock]"'),
+        ("Google Gen AI", 'uv add "crewai[google-genai]"'),
+    ],
+)
+def test_classify_missing_provider_extra_matches_real_messages(
+    tmp_path: Path, pkg_label: str, install_cmd: str
+) -> None:
+    """Regression for the four provider error strings verbatim."""
+    v = DeployValidator(project_root=tmp_path)
+    v._classify_import_error(
+        "ImportError",
+        f"{pkg_label} native provider not available, to install: {install_cmd}",
+        tb="",
+    )
+    assert "missing_provider_extra" in _codes(v)
+    finding = next(r for r in v.results if r.code == "missing_provider_extra")
+    assert install_cmd in finding.hint
+
+
+def test_classify_keyerror_at_import_is_warning(tmp_path: Path) -> None:
+    """Regression for `KeyError: 'SERPLY_API_KEY'` raised at import time."""
+    v = DeployValidator(project_root=tmp_path)
+    v._classify_import_error("KeyError", "'SERPLY_API_KEY'", tb="")
+    codes = _codes(v)
+    assert "env_var_read_at_import" in codes
+
+
+def test_classify_no_crewbase_class_is_error(tmp_path: Path) -> None:
+    v = DeployValidator(project_root=tmp_path)
+    v._classify_import_error(
+        "ValueError",
+        "Crew class annotated with @CrewBase not found.",
+        tb="",
+    )
+    assert "no_crewbase_class" in _codes(v)
+
+
+def test_classify_no_flow_subclass_is_error(tmp_path: Path) -> None:
+    v = DeployValidator(project_root=tmp_path)
+    v._classify_import_error("ValueError", "No Flow subclass found in the module.", tb="")
+    assert "no_flow_subclass" in _codes(v)
+
+
+def test_classify_stale_crewai_pin_attribute_error(tmp_path: Path) -> None:
+    """Regression for a stale crewai pin missing `_load_response_format`."""
+    v = DeployValidator(project_root=tmp_path)
+    v._classify_import_error(
+        "AttributeError",
+        "'EmploymentServiceDecisionSupportSystemCrew' object has no attribute '_load_response_format'",
+        tb="",
+    )
+    assert "stale_crewai_pin" in _codes(v)
+
+
+def test_classify_unknown_error_is_fallback(tmp_path: Path) -> None:
+    v = DeployValidator(project_root=tmp_path)
+    v._classify_import_error("RuntimeError", "something weird happened", tb="")
+    assert "import_failed" in _codes(v)
+
+
+def test_env_var_referenced_but_missing_warns(tmp_path: Path) -> None:
+    pkg = _scaffold_standard_crew(tmp_path)
+    (pkg / "tools.py").write_text(
+        'import os\nkey = os.getenv("TAVILY_API_KEY")\n'
+    )
+    import os
+
+    # Make sure the test doesn't inherit the key from the host environment.
+    with patch.dict(os.environ, {}, clear=False):
+        os.environ.pop("TAVILY_API_KEY", None)
+        v = _run_without_import_check(tmp_path)
+    codes = _codes(v)
+    assert "env_vars_not_in_dotenv" in codes
+
+
+def test_env_var_in_dotenv_does_not_warn(tmp_path: Path) -> None:
+    pkg = _scaffold_standard_crew(tmp_path)
+    (pkg / "tools.py").write_text(
+        'import os\nkey = os.getenv("TAVILY_API_KEY")\n'
+    )
+    (tmp_path / ".env").write_text("TAVILY_API_KEY=abc\n")
+    v = _run_without_import_check(tmp_path)
+    assert "env_vars_not_in_dotenv" not in _codes(v)
+
+
+def test_old_crewai_pin_in_uv_lock_warns(tmp_path: Path) -> None:
+    _scaffold_standard_crew(tmp_path)
+    (tmp_path / "uv.lock").write_text(
+        'name = "crewai"\nversion = "1.10.0"\nsource = { registry = "..." }\n'
+    )
+    v = _run_without_import_check(tmp_path)
+    assert "old_crewai_pin" in _codes(v)
+
+
+def test_modern_crewai_pin_does_not_warn(tmp_path: Path) -> None:
+    _scaffold_standard_crew(tmp_path)
+    (tmp_path / "uv.lock").write_text(
+        'name = "crewai"\nversion = "1.14.1"\nsource = { registry = "..." }\n'
+    )
+    v = _run_without_import_check(tmp_path)
+    assert "old_crewai_pin" not in _codes(v)
+
+
+def test_create_crew_aborts_on_validation_error(tmp_path: Path) -> None:
+    """`crewai deploy create` must not contact the API when validation fails."""
+    from unittest.mock import MagicMock, patch as mock_patch
+
+    from crewai.cli.deploy.main import DeployCommand
+
+    with (
+        mock_patch("crewai.cli.command.get_auth_token", return_value="tok"),
+        mock_patch("crewai.cli.deploy.main.get_project_name", return_value="p"),
+        mock_patch("crewai.cli.command.PlusAPI") as mock_api,
+        mock_patch(
+            "crewai.cli.deploy.main.validate_project"
+        ) as mock_validate,
+    ):
+        mock_validate.return_value = MagicMock(ok=False)
+        cmd = DeployCommand()
+        cmd.create_crew()
+        assert not cmd.plus_api_client.create_crew.called
+        del mock_api  # silence unused-var lint

lib/crewai/tests/cli/test_cli.py

@@ -367,7 +367,7 @@ def test_deploy_push(command, runner):
     result = runner.invoke(deploy_push, ["-u", uuid])
 
     assert result.exit_code == 0
-    mock_deploy.deploy.assert_called_once_with(uuid=uuid)
+    mock_deploy.deploy.assert_called_once_with(uuid=uuid, skip_validate=False)
 
 
 @mock.patch("crewai.cli.cli.DeployCommand")
@@ -376,7 +376,7 @@ def test_deploy_push_no_uuid(command, runner):
     result = runner.invoke(deploy_push)
 
     assert result.exit_code == 0
-    mock_deploy.deploy.assert_called_once_with(uuid=None)
+    mock_deploy.deploy.assert_called_once_with(uuid=None, skip_validate=False)
 
 
 @mock.patch("crewai.cli.cli.DeployCommand")

lib/crewai/tests/events/test_llm_usage_event.py

@@ -174,3 +174,51 @@ class TestEmitCallCompletedEventPassesUsage:
         event = mock_emit.call_args[1]["event"]
         assert isinstance(event, LLMCallCompletedEvent)
         assert event.usage is None
+
+class TestUsageMetricsNewFields:
+    def test_add_usage_metrics_aggregates_reasoning_and_cache_creation(self):
+        from crewai.types.usage_metrics import UsageMetrics
+
+        metrics1 = UsageMetrics(
+            total_tokens=100,
+            prompt_tokens=60,
+            completion_tokens=40,
+            cached_prompt_tokens=10,
+            reasoning_tokens=15,
+            cache_creation_tokens=5,
+            successful_requests=1,
+        )
+        metrics2 = UsageMetrics(
+            total_tokens=200,
+            prompt_tokens=120,
+            completion_tokens=80,
+            cached_prompt_tokens=20,
+            reasoning_tokens=25,
+            cache_creation_tokens=10,
+            successful_requests=1,
+        )
+
+        metrics1.add_usage_metrics(metrics2)
+
+        assert metrics1.total_tokens == 300
+        assert metrics1.prompt_tokens == 180
+        assert metrics1.completion_tokens == 120
+        assert metrics1.cached_prompt_tokens == 30
+        assert metrics1.reasoning_tokens == 40
+        assert metrics1.cache_creation_tokens == 15
+        assert metrics1.successful_requests == 2
+
+    def test_new_fields_default_to_zero(self):
+        from crewai.types.usage_metrics import UsageMetrics
+
+        metrics = UsageMetrics()
+        assert metrics.reasoning_tokens == 0
+        assert metrics.cache_creation_tokens == 0
+
+    def test_model_dump_includes_new_fields(self):
+        from crewai.types.usage_metrics import UsageMetrics
+
+        metrics = UsageMetrics(reasoning_tokens=10, cache_creation_tokens=5)
+        dumped = metrics.model_dump()
+        assert dumped["reasoning_tokens"] == 10
+        assert dumped["cache_creation_tokens"] == 5

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

@@ -1463,3 +1463,45 @@ def test_tool_search_saves_input_tokens():
         f"Expected tool_search ({usage_search.prompt_tokens}) to use fewer input tokens "
         f"than no search ({usage_no_search.prompt_tokens})"
     )
+
+
+def test_anthropic_cache_creation_tokens_extraction():
+    """Test that cache_creation_input_tokens are extracted from Anthropic responses."""
+    llm = LLM(model="anthropic/claude-3-5-sonnet-20241022")
+
+    mock_response = MagicMock()
+    mock_response.content = [MagicMock(text="test response")]
+    mock_response.usage = MagicMock(
+        input_tokens=100,
+        output_tokens=50,
+        cache_read_input_tokens=30,
+        cache_creation_input_tokens=20,
+    )
+    mock_response.stop_reason = None
+    mock_response.model = None
+
+    usage = llm._extract_anthropic_token_usage(mock_response)
+    assert usage["input_tokens"] == 100
+    assert usage["output_tokens"] == 50
+    assert usage["total_tokens"] == 150
+    assert usage["cached_prompt_tokens"] == 30
+    assert usage["cache_creation_tokens"] == 20
+
+
+def test_anthropic_missing_cache_fields_default_to_zero():
+    """Test that missing cache fields default to zero."""
+    llm = LLM(model="anthropic/claude-3-5-sonnet-20241022")
+
+    mock_response = MagicMock()
+    mock_response.content = [MagicMock(text="test response")]
+    mock_response.usage = MagicMock(
+        input_tokens=40,
+        output_tokens=20,
+        spec=["input_tokens", "output_tokens"],
+    )
+    mock_response.usage.cache_read_input_tokens = None
+    mock_response.usage.cache_creation_input_tokens = None
+
+    usage = llm._extract_anthropic_token_usage(mock_response)
+    assert usage["cached_prompt_tokens"] == 0
+    assert usage["cache_creation_tokens"] == 0

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

@@ -3,13 +3,9 @@ import json
 import logging
 
 import pytest
-import tiktoken
 from pydantic import BaseModel
 
 from crewai.llm import LLM
-
-# Pre-cache tiktoken encoding so VCR doesn't intercept the download request
-tiktoken.get_encoding("cl100k_base")
 from crewai.llms.providers.anthropic.completion import AnthropicCompletion
 
 
@@ -48,9 +44,7 @@ async def test_anthropic_async_with_max_tokens():
 
     assert result is not None
     assert isinstance(result, str)
-    encoder = tiktoken.get_encoding("cl100k_base")
-    token_count = len(encoder.encode(result))
-    assert token_count <= 10
+    assert len(result.split()) <= 10
 
 
 @pytest.mark.vcr()

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

@@ -2,6 +2,7 @@ import os
 import sys
 import types
 from unittest.mock import patch, MagicMock, Mock
+from urllib.parse import urlparse
 import pytest
 
 from crewai.llm import LLM
@@ -378,23 +379,72 @@ def test_azure_completion_with_tools():
 
 
 def test_azure_raises_error_when_endpoint_missing():
-    """Test that AzureCompletion raises ValueError when endpoint is missing"""
+    """Credentials are validated lazily: construction succeeds, first
+    client build raises the descriptive error."""
     from crewai.llms.providers.azure.completion import AzureCompletion
 
-    # Clear environment variables
     with patch.dict(os.environ, {}, clear=True):
+        llm = AzureCompletion(model="gpt-4", api_key="test-key")
         with pytest.raises(ValueError, match="Azure endpoint is required"):
-            AzureCompletion(model="gpt-4", api_key="test-key")
+            llm._get_sync_client()
 
 
 def test_azure_raises_error_when_api_key_missing():
-    """Test that AzureCompletion raises ValueError when API key is missing"""
+    """Credentials are validated lazily: construction succeeds, first
+    client build raises the descriptive error."""
     from crewai.llms.providers.azure.completion import AzureCompletion
 
-    # Clear environment variables
     with patch.dict(os.environ, {}, clear=True):
+        llm = AzureCompletion(
+            model="gpt-4", endpoint="https://test.openai.azure.com"
+        )
         with pytest.raises(ValueError, match="Azure API key is required"):
-            AzureCompletion(model="gpt-4", endpoint="https://test.openai.azure.com")
+            llm._get_sync_client()
+
+
+@pytest.mark.asyncio
+async def test_azure_aclose_is_noop_when_uninitialized():
+    """`aclose` (and `async with`) on an uninstantiated-client LLM must be
+    a harmless no-op, not force lazy construction that then raises for
+    missing credentials."""
+    from crewai.llms.providers.azure.completion import AzureCompletion
+
+    with patch.dict(os.environ, {}, clear=True):
+        llm = AzureCompletion(model="gpt-4")
+        assert llm._async_client is None
+        await llm.aclose()
+        async with llm:
+            pass
+
+
+def test_azure_lazy_build_reads_env_vars_set_after_construction():
+    """When `LLM(model="azure/...")` is constructed before env vars are set,
+    the lazy client builder must re-read `AZURE_API_KEY` / `AZURE_ENDPOINT`
+    so the LLM actually works once credentials become available, and the
+    `is_azure_openai_endpoint` routing flag must be recomputed off the
+    newly-resolved endpoint."""
+    from crewai.llms.providers.azure.completion import AzureCompletion
+
+    with patch.dict(os.environ, {}, clear=True):
+        llm = AzureCompletion(model="gpt-4")
+        assert llm.api_key is None
+        assert llm.endpoint is None
+        assert llm.is_azure_openai_endpoint is False
+
+    with patch.dict(
+        os.environ,
+        {
+            "AZURE_API_KEY": "late-key",
+            "AZURE_ENDPOINT": "https://test.openai.azure.com/openai/deployments/gpt-4",
+        },
+        clear=True,
+    ):
+        client = llm._get_sync_client()
+        assert client is not None
+        assert llm.api_key == "late-key"
+        assert llm.endpoint is not None
+        assert urlparse(llm.endpoint).hostname == "test.openai.azure.com"
+        assert llm.is_azure_openai_endpoint is True
 
 
 def test_azure_endpoint_configuration():
@@ -1403,3 +1453,44 @@ def test_azure_stop_words_still_applied_to_regular_responses():
         assert "Observation:" not in result
         assert "Found results" not in result
         assert "I need to search for more information" in result
+
+
+def test_azure_reasoning_tokens_and_cached_tokens():
+    """Test that reasoning_tokens and cached_tokens are extracted from Azure responses."""
+    llm = LLM(model="azure/gpt-4")
+
+    mock_response = MagicMock()
+    mock_response.usage = MagicMock(
+        prompt_tokens=100,
+        completion_tokens=200,
+        total_tokens=300,
+    )
+    mock_response.usage.prompt_tokens_details = MagicMock(cached_tokens=40)
+    mock_response.usage.completion_tokens_details = MagicMock(reasoning_tokens=60)
+
+    usage = llm._extract_azure_token_usage(mock_response)
+    assert usage["prompt_tokens"] == 100
+    assert usage["completion_tokens"] == 200
+    assert usage["total_tokens"] == 300
+    assert usage["cached_prompt_tokens"] == 40
+    assert usage["reasoning_tokens"] == 60
+
+
+def test_azure_no_detail_fields():
+    """Test Azure extraction without detail fields."""
+    llm = LLM(model="azure/gpt-4")
+
+    mock_response = MagicMock()
+    mock_response.usage = MagicMock(
+        prompt_tokens=50,
+        completion_tokens=30,
+        total_tokens=80,
+    )
+    mock_response.usage.prompt_tokens_details = None
+    mock_response.usage.completion_tokens_details = None
+
+    usage = llm._extract_azure_token_usage(mock_response)
+    assert usage["prompt_tokens"] == 50
+    assert usage["completion_tokens"] == 30
+    assert usage["cached_prompt_tokens"] == 0
+    assert usage["reasoning_tokens"] == 0

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

@@ -1,7 +1,6 @@
 """Tests for Azure async completion functionality."""
 
 import pytest
-import tiktoken
 
 from crewai import Agent, Task, Crew
 from crewai.llm import LLM
@@ -57,9 +56,7 @@ async def test_azure_async_with_max_tokens():
 
     assert result is not None
     assert isinstance(result, str)
-    encoder = tiktoken.get_encoding("cl100k_base")
-    token_count = len(encoder.encode(result))
-    assert token_count <= 10
+    assert len(result.split()) <= 10
 
 
 @pytest.mark.vcr()

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

@@ -1175,3 +1175,81 @@ def test_bedrock_tool_results_not_merged_across_assistant_messages():
     )
     assert tool_result_messages[0]["content"][0]["toolResult"]["toolUseId"] == "call_a"
     assert tool_result_messages[1]["content"][0]["toolResult"]["toolUseId"] == "call_b"
+
+
+def test_bedrock_cached_token_tracking():
+    """Test that cached tokens (cacheReadInputTokenCount) are tracked for Bedrock."""
+    llm = LLM(model="bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0")
+
+    with patch.object(llm._client, 'converse') as mock_converse:
+        mock_response = {
+            'output': {
+                'message': {
+                    'role': 'assistant',
+                    'content': [{'text': 'test response'}]
+                }
+            },
+            'usage': {
+                'inputTokens': 100,
+                'outputTokens': 50,
+                'totalTokens': 150,
+                'cacheReadInputTokenCount': 30,
+            }
+        }
+        mock_converse.return_value = mock_response
+
+        result = llm.call("Hello")
+        assert result == "test response"
+        assert llm._token_usage['prompt_tokens'] == 100
+        assert llm._token_usage['completion_tokens'] == 50
+        assert llm._token_usage['total_tokens'] == 150
+        assert llm._token_usage['cached_prompt_tokens'] == 30
+
+
+def test_bedrock_cached_token_alternate_key():
+    """Test that the alternate key cacheReadInputTokens also works."""
+    llm = LLM(model="bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0")
+
+    with patch.object(llm._client, 'converse') as mock_converse:
+        mock_response = {
+            'output': {
+                'message': {
+                    'role': 'assistant',
+                    'content': [{'text': 'test response'}]
+                }
+            },
+            'usage': {
+                'inputTokens': 80,
+                'outputTokens': 40,
+                'totalTokens': 120,
+                'cacheReadInputTokens': 25,
+            }
+        }
+        mock_converse.return_value = mock_response
+
+        llm.call("Hello")
+        assert llm._token_usage['cached_prompt_tokens'] == 25
+
+
+def test_bedrock_no_cache_tokens_defaults_to_zero():
+    """Test that missing cache token keys default to zero."""
+    llm = LLM(model="bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0")
+
+    with patch.object(llm._client, 'converse') as mock_converse:
+        mock_response = {
+            'output': {
+                'message': {
+                    'role': 'assistant',
+                    'content': [{'text': 'test response'}]
+                }
+            },
+            'usage': {
+                'inputTokens': 60,
+                'outputTokens': 30,
+                'totalTokens': 90,
+            }
+        }
+        mock_converse.return_value = mock_response
+
+        llm.call("Hello")
+        assert llm._token_usage['cached_prompt_tokens'] == 0

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

@@ -6,7 +6,6 @@ cannot be played back properly in CI.
 """
 
 import pytest
-import tiktoken
 
 from crewai.llm import LLM
 
@@ -51,9 +50,7 @@ async def test_bedrock_async_with_max_tokens():
 
     assert result is not None
     assert isinstance(result, str)
-    encoder = tiktoken.get_encoding("cl100k_base")
-    token_count = len(encoder.encode(result))
-    assert token_count <= 10
+    assert len(result.split()) <= 10
 
 
 @pytest.mark.vcr()

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

@@ -64,6 +64,23 @@ def test_gemini_completion_module_is_imported():
     assert hasattr(completion_mod, 'GeminiCompletion')
 
 
+def test_gemini_lazy_build_reads_env_vars_set_after_construction():
+    """When `LLM(model="gemini/...")` is constructed before env vars are set,
+    the lazy client builder must re-read `GOOGLE_API_KEY` / `GEMINI_API_KEY`
+    so the LLM works once credentials become available."""
+    from crewai.llms.providers.gemini.completion import GeminiCompletion
+
+    with patch.dict(os.environ, {}, clear=True):
+        llm = GeminiCompletion(model="gemini-1.5-pro")
+        assert llm.api_key is None
+        assert llm._client is None
+
+    with patch.dict(os.environ, {"GEMINI_API_KEY": "late-key"}, clear=True):
+        client = llm._get_sync_client()
+        assert client is not None
+        assert llm.api_key == "late-key"
+
+
 def test_native_gemini_raises_error_when_initialization_fails():
     """
     Test that LLM raises ImportError when native Gemini completion fails.
@@ -1190,3 +1207,42 @@ def test_gemini_cached_prompt_tokens_with_tools():
     # cached_prompt_tokens should be populated (may be 0 if Gemini
     # doesn't cache for this particular request, but the field should exist)
     assert usage.cached_prompt_tokens >= 0
+
+
+def test_gemini_reasoning_tokens_extraction():
+    """Test that thoughts_token_count is extracted as reasoning_tokens from Gemini."""
+    llm = LLM(model="google/gemini-2.0-flash-001")
+
+    mock_response = MagicMock()
+    mock_response.usage_metadata = MagicMock(
+        prompt_token_count=100,
+        candidates_token_count=50,
+        total_token_count=150,
+        cached_content_token_count=10,
+        thoughts_token_count=30,
+    )
+    usage = llm._extract_token_usage(mock_response)
+    assert usage["prompt_token_count"] == 100
+    assert usage["candidates_token_count"] == 50
+    assert usage["total_tokens"] == 150
+    assert usage["cached_prompt_tokens"] == 10
+    assert usage["reasoning_tokens"] == 30
+
+
+def test_gemini_no_thinking_tokens_defaults_to_zero():
+    """Test that missing thoughts_token_count defaults to zero."""
+    llm = LLM(model="google/gemini-2.0-flash-001")
+
+    mock_response = MagicMock()
+    mock_response.usage_metadata = MagicMock(
+        prompt_token_count=80,
+        candidates_token_count=40,
+        total_token_count=120,
+        cached_content_token_count=0,
+        thoughts_token_count=None,
+    )
+    mock_response.candidates = []
+
+    usage = llm._extract_token_usage(mock_response)
+    assert usage["reasoning_tokens"] == 0
+    assert usage["cached_prompt_tokens"] == 0

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

@@ -1,7 +1,6 @@
 """Tests for Google (Gemini) async completion functionality."""
 
 import pytest
-import tiktoken
 
 from crewai import Agent, Task, Crew
 from crewai.llm import LLM
@@ -43,9 +42,7 @@ async def test_gemini_async_with_max_tokens():
 
     assert result is not None
     assert isinstance(result, str)
-    encoder = tiktoken.get_encoding("cl100k_base")
-    token_count = len(encoder.encode(result))
-    assert token_count <= 1000
+    assert len(result.split()) <= 1000
 
 
 @pytest.mark.vcr()

lib/crewai/tests/llms/litellm/test_litellm_async.py

@@ -1,7 +1,6 @@
 """Tests for LiteLLM fallback async completion functionality."""
 
 import pytest
-import tiktoken
 
 from crewai.llm import LLM
 
@@ -44,9 +43,7 @@ async def test_litellm_async_with_max_tokens():
 
     assert result is not None
     assert isinstance(result, str)
-    encoder = tiktoken.get_encoding("cl100k_base")
-    token_count = len(encoder.encode(result))
-    assert token_count <= 10
+    assert len(result.split()) <= 10
 
 
 @pytest.mark.asyncio

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

@@ -1929,6 +1929,47 @@ def test_openai_streaming_returns_tool_calls_without_available_functions():
     assert result[0]["type"] == "function"
 
 
+def test_openai_responses_api_reasoning_tokens_extraction():
+    """Test that reasoning_tokens are extracted from Responses API responses."""
+    llm = LLM(model="openai/gpt-4o")
+
+    mock_response = MagicMock()
+    mock_response.usage = MagicMock(
+        input_tokens=100,
+        output_tokens=200,
+        total_tokens=300,
+    )
+    mock_response.usage.input_tokens_details = MagicMock(cached_tokens=25)
+    mock_response.usage.output_tokens_details = MagicMock(reasoning_tokens=80)
+
+    usage = llm._extract_responses_token_usage(mock_response)
+    assert usage["prompt_tokens"] == 100
+    assert usage["completion_tokens"] == 200
+    assert usage["total_tokens"] == 300
+    assert usage["cached_prompt_tokens"] == 25
+    assert usage["reasoning_tokens"] == 80
+
+
+def test_openai_responses_api_no_detail_fields_omitted():
+    """Test that reasoning/cached fields are omitted when Responses API details are absent."""
+    llm = LLM(model="openai/gpt-4o")
+
+    mock_response = MagicMock()
+    mock_response.usage = MagicMock(
+        input_tokens=50,
+        output_tokens=30,
+        total_tokens=80,
+    )
+    mock_response.usage.input_tokens_details = None
+    mock_response.usage.output_tokens_details = None
+
+    usage = llm._extract_responses_token_usage(mock_response)
+    assert usage["prompt_tokens"] == 50
+    assert usage["completion_tokens"] == 30
+    assert "cached_prompt_tokens" not in usage
+    assert "reasoning_tokens" not in usage
+
+
 @pytest.mark.asyncio
 async def test_openai_async_streaming_returns_tool_calls_without_available_functions():
     """Test that async streaming returns tool calls list when available_functions is None.
@@ -2018,3 +2059,44 @@ async def test_openai_async_streaming_returns_tool_calls_without_available_funct
     assert result[0]["function"]["arguments"] == '{"expression": "1+1"}'
     assert result[0]["id"] == "call_abc123"
     assert result[0]["type"] == "function"
+
+
+def test_openai_reasoning_tokens_extraction():
+    """Test that reasoning_tokens are extracted from OpenAI o-series responses."""
+    llm = LLM(model="openai/gpt-4o")
+
+    mock_response = MagicMock()
+    mock_response.usage = MagicMock(
+        prompt_tokens=100,
+        completion_tokens=200,
+        total_tokens=300,
+    )
+    mock_response.usage.prompt_tokens_details = MagicMock(cached_tokens=25)
+    mock_response.usage.completion_tokens_details = MagicMock(reasoning_tokens=80)
+
+    usage = llm._extract_openai_token_usage(mock_response)
+    assert usage["prompt_tokens"] == 100
+    assert usage["completion_tokens"] == 200
+    assert usage["total_tokens"] == 300
+    assert usage["cached_prompt_tokens"] == 25
+    assert usage["reasoning_tokens"] == 80
+
+
+def test_openai_no_detail_fields_omitted():
+    """Test that reasoning/cached fields are omitted when details are absent."""
+    llm = LLM(model="openai/gpt-4o")
+
+    mock_response = MagicMock()
+    mock_response.usage = MagicMock(
+        prompt_tokens=50,
+        completion_tokens=30,
+        total_tokens=80,
+    )
+    mock_response.usage.prompt_tokens_details = None
+    mock_response.usage.completion_tokens_details = None
+
+    usage = llm._extract_openai_token_usage(mock_response)
+    assert usage["prompt_tokens"] == 50
+    assert usage["completion_tokens"] == 30
+    assert "cached_prompt_tokens" not in usage
+    assert "reasoning_tokens" not in usage

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

@@ -1,7 +1,6 @@
 """Tests for OpenAI async completion functionality."""
 
 import pytest
-import tiktoken
 
 from crewai import Agent, Task, Crew
 from crewai.llm import LLM
@@ -42,9 +41,7 @@ async def test_openai_async_with_max_tokens():
 
     assert result is not None
     assert isinstance(result, str)
-    encoder = tiktoken.get_encoding("cl100k_base")
-    token_count = len(encoder.encode(result))
-    assert token_count <= 10
+    assert len(result.split()) <= 10
 
 
 @pytest.mark.vcr()

lib/crewai/tests/memory/test_unified_memory.py

@@ -51,14 +51,13 @@ def test_memory_record_embedding_excluded_from_serialization() -> None:
     dumped = r.model_dump()
     assert "embedding" not in dumped
     assert dumped["content"] == "hello"
-
-    # model_dump_json excludes embedding
     json_str = r.model_dump_json()
-    assert "0.1" not in json_str
     assert "embedding" not in json_str
+    rehydrated = MemoryRecord.model_validate_json(json_str)
+    assert rehydrated.embedding is None
 
     # repr excludes embedding
-    assert "0.1" not in repr(r)
+    assert "embedding=" not in repr(r)
 
     # Direct attribute access still works for storage layer
     assert r.embedding is not None

lib/crewai/tests/test_checkpoint.py

@@ -1,8 +1,10 @@
-"""Tests for CheckpointConfig, checkpoint listener, and pruning."""
+"""Tests for CheckpointConfig, checkpoint listener, pruning, and forking."""
 
 from __future__ import annotations
 
+import json
 import os
+import sqlite3
 import tempfile
 import time
 from typing import Any
@@ -21,6 +23,8 @@ from crewai.state.checkpoint_listener import (
     _SENTINEL,
 )
 from crewai.state.provider.json_provider import JsonProvider
+from crewai.state.provider.sqlite_provider import SqliteProvider
+from crewai.state.runtime import RuntimeState
 from crewai.task import Task
 
 
@@ -116,35 +120,41 @@ class TestFindCheckpoint:
 class TestPrune:
     def test_prune_keeps_newest(self) -> None:
         with tempfile.TemporaryDirectory() as d:
+            branch_dir = os.path.join(d, "main")
+            os.makedirs(branch_dir)
             for i in range(5):
-                path = os.path.join(d, f"cp_{i}.json")
+                path = os.path.join(branch_dir, f"cp_{i}.json")
                 with open(path, "w") as f:
                     f.write("{}")
                 # Ensure distinct mtime
                 time.sleep(0.01)
 
-            JsonProvider().prune(d, max_keep=2)
-            remaining = os.listdir(d)
+            JsonProvider().prune(d, max_keep=2, branch="main")
+            remaining = os.listdir(branch_dir)
             assert len(remaining) == 2
             assert "cp_3.json" in remaining
             assert "cp_4.json" in remaining
 
     def test_prune_zero_removes_all(self) -> None:
         with tempfile.TemporaryDirectory() as d:
+            branch_dir = os.path.join(d, "main")
+            os.makedirs(branch_dir)
             for i in range(3):
-                with open(os.path.join(d, f"cp_{i}.json"), "w") as f:
+                with open(os.path.join(branch_dir, f"cp_{i}.json"), "w") as f:
                     f.write("{}")
 
-            JsonProvider().prune(d, max_keep=0)
-            assert os.listdir(d) == []
+            JsonProvider().prune(d, max_keep=0, branch="main")
+            assert os.listdir(branch_dir) == []
 
     def test_prune_more_than_existing(self) -> None:
         with tempfile.TemporaryDirectory() as d:
-            with open(os.path.join(d, "cp.json"), "w") as f:
+            branch_dir = os.path.join(d, "main")
+            os.makedirs(branch_dir)
+            with open(os.path.join(branch_dir, "cp.json"), "w") as f:
                 f.write("{}")
 
-            JsonProvider().prune(d, max_keep=10)
-            assert len(os.listdir(d)) == 1
+            JsonProvider().prune(d, max_keep=10, branch="main")
+            assert len(os.listdir(branch_dir)) == 1
 
 
 # ---------- CheckpointConfig ----------
@@ -162,8 +172,368 @@ class TestCheckpointConfig:
         cfg = CheckpointConfig(on_events=["*"])
         assert cfg.trigger_all
 
+    def test_restore_from_field(self) -> None:
+        cfg = CheckpointConfig(restore_from="/path/to/checkpoint.json")
+        assert cfg.restore_from == "/path/to/checkpoint.json"
+
+    def test_restore_from_default_none(self) -> None:
+        cfg = CheckpointConfig()
+        assert cfg.restore_from is None
+
     def test_trigger_events(self) -> None:
         cfg = CheckpointConfig(
             on_events=["task_completed", "crew_kickoff_completed"]
         )
         assert cfg.trigger_events == {"task_completed", "crew_kickoff_completed"}
+
+
+# ---------- RuntimeState lineage ----------
+
+
+class TestRuntimeStateLineage:
+    def _make_state(self) -> RuntimeState:
+        from crewai import Agent, Crew
+
+        agent = Agent(role="r", goal="g", backstory="b", llm="gpt-4o-mini")
+        crew = Crew(agents=[agent], tasks=[], verbose=False)
+        return RuntimeState(root=[crew])
+
+    def test_default_lineage_fields(self) -> None:
+        state = self._make_state()
+        assert state._checkpoint_id is None
+        assert state._parent_id is None
+        assert state._branch == "main"
+
+    def test_serialize_includes_version(self) -> None:
+        from crewai.utilities.version import get_crewai_version
+
+        state = self._make_state()
+        dumped = json.loads(state.model_dump_json())
+        assert dumped["crewai_version"] == get_crewai_version()
+
+    def test_deserialize_migrates_on_version_mismatch(self, caplog: Any) -> None:
+        import logging
+
+        state = self._make_state()
+        raw = state.model_dump_json()
+        data = json.loads(raw)
+        data["crewai_version"] = "0.1.0"
+        with caplog.at_level(logging.DEBUG):
+            RuntimeState.model_validate_json(
+                json.dumps(data), context={"from_checkpoint": True}
+            )
+        assert "Migrating checkpoint from crewAI 0.1.0" in caplog.text
+
+    def test_deserialize_warns_on_missing_version(self, caplog: Any) -> None:
+        import logging
+
+        state = self._make_state()
+        raw = state.model_dump_json()
+        data = json.loads(raw)
+        data.pop("crewai_version", None)
+        with caplog.at_level(logging.WARNING):
+            RuntimeState.model_validate_json(
+                json.dumps(data), context={"from_checkpoint": True}
+            )
+        assert "treating as 0.0.0" in caplog.text
+
+    def test_serialize_includes_lineage(self) -> None:
+        state = self._make_state()
+        state._parent_id = "parent456"
+        state._branch = "experiment"
+        dumped = json.loads(state.model_dump_json())
+        assert dumped["parent_id"] == "parent456"
+        assert dumped["branch"] == "experiment"
+        assert "checkpoint_id" not in dumped
+
+    def test_deserialize_restores_lineage(self) -> None:
+        state = self._make_state()
+        state._parent_id = "parent456"
+        state._branch = "experiment"
+        raw = state.model_dump_json()
+        restored = RuntimeState.model_validate_json(
+            raw, context={"from_checkpoint": True}
+        )
+        assert restored._parent_id == "parent456"
+        assert restored._branch == "experiment"
+
+    def test_deserialize_defaults_missing_lineage(self) -> None:
+        state = self._make_state()
+        raw = state.model_dump_json()
+        data = json.loads(raw)
+        data.pop("parent_id", None)
+        data.pop("branch", None)
+        restored = RuntimeState.model_validate_json(
+            json.dumps(data), context={"from_checkpoint": True}
+        )
+        assert restored._parent_id is None
+        assert restored._branch == "main"
+
+    def test_from_checkpoint_sets_checkpoint_id(self) -> None:
+        """from_checkpoint sets _checkpoint_id from the location, not the blob."""
+        state = self._make_state()
+        state._provider = JsonProvider()
+        with tempfile.TemporaryDirectory() as d:
+            loc = state.checkpoint(d)
+            written_id = state._checkpoint_id
+
+            cfg = CheckpointConfig(restore_from=loc)
+            restored = RuntimeState.from_checkpoint(
+                cfg, context={"from_checkpoint": True}
+            )
+            assert restored._checkpoint_id == written_id
+            assert restored._parent_id == written_id
+
+    def test_fork_sets_branch(self) -> None:
+        state = self._make_state()
+        state._checkpoint_id = "abc12345"
+        state._parent_id = "abc12345"
+        state.fork("my-experiment")
+        assert state._branch == "my-experiment"
+        assert state._parent_id == "abc12345"
+
+    def test_fork_auto_branch(self) -> None:
+        state = self._make_state()
+        state._checkpoint_id = "20260409T120000_abc12345"
+        state.fork()
+        assert state._branch.startswith("fork/20260409T120000_abc12345_")
+        assert len(state._branch) == len("fork/20260409T120000_abc12345_") + 6
+
+    def test_fork_no_checkpoint_id_unique(self) -> None:
+        state = self._make_state()
+        state.fork()
+        assert state._branch.startswith("fork/")
+        assert len(state._branch) == len("fork/") + 8
+        # Two forks without checkpoint_id produce different branches
+        first = state._branch
+        state.fork()
+        assert state._branch != first
+
+
+# ---------- JsonProvider forking ----------
+
+
+class TestJsonProviderFork:
+    def test_checkpoint_writes_to_branch_subdir(self) -> None:
+        provider = JsonProvider()
+        with tempfile.TemporaryDirectory() as d:
+            path = provider.checkpoint("{}", d, branch="main")
+            assert "/main/" in path
+            assert path.endswith(".json")
+            assert os.path.isfile(path)
+
+    def test_checkpoint_fork_branch_subdir(self) -> None:
+        provider = JsonProvider()
+        with tempfile.TemporaryDirectory() as d:
+            path = provider.checkpoint("{}", d, branch="fork/exp1")
+            assert "/fork/exp1/" in path
+            assert os.path.isfile(path)
+
+    def test_prune_branch_aware(self) -> None:
+        provider = JsonProvider()
+        with tempfile.TemporaryDirectory() as d:
+            # Write 3 checkpoints on main, 2 on fork
+            for _ in range(3):
+                provider.checkpoint("{}", d, branch="main")
+                time.sleep(0.01)
+            for _ in range(2):
+                provider.checkpoint("{}", d, branch="fork/a")
+                time.sleep(0.01)
+
+            # Prune main to 1
+            provider.prune(d, max_keep=1, branch="main")
+
+            main_dir = os.path.join(d, "main")
+            fork_dir = os.path.join(d, "fork", "a")
+            assert len(os.listdir(main_dir)) == 1
+            assert len(os.listdir(fork_dir)) == 2  # untouched
+
+    def test_extract_id(self) -> None:
+        provider = JsonProvider()
+        assert provider.extract_id("/dir/main/20260409T120000_abc12345_p-none.json") == "20260409T120000_abc12345"
+        assert provider.extract_id("/dir/main/20260409T120000_abc12345_p-20260409T115900_def67890.json") == "20260409T120000_abc12345"
+
+    def test_branch_traversal_rejected(self) -> None:
+        provider = JsonProvider()
+        with tempfile.TemporaryDirectory() as d:
+            with pytest.raises(ValueError, match="escapes checkpoint directory"):
+                provider.checkpoint("{}", d, branch="../../etc")
+            with pytest.raises(ValueError, match="escapes checkpoint directory"):
+                provider.prune(d, max_keep=1, branch="../../etc")
+
+    def test_filename_encodes_parent_id(self) -> None:
+        provider = JsonProvider()
+        with tempfile.TemporaryDirectory() as d:
+            # First checkpoint — no parent
+            path1 = provider.checkpoint("{}", d, branch="main")
+            assert "_p-none.json" in path1
+
+            # Second checkpoint — with parent
+            id1 = provider.extract_id(path1)
+            path2 = provider.checkpoint("{}", d, parent_id=id1, branch="main")
+            assert f"_p-{id1}.json" in path2
+
+    def test_checkpoint_chaining(self) -> None:
+        """RuntimeState.checkpoint() chains parent_id after each write."""
+        state = self._make_state()
+        state._provider = JsonProvider()
+        with tempfile.TemporaryDirectory() as d:
+            state.checkpoint(d)
+            id1 = state._checkpoint_id
+            assert id1 is not None
+            assert state._parent_id == id1
+
+            loc2 = state.checkpoint(d)
+            id2 = state._checkpoint_id
+            assert id2 is not None
+            assert id2 != id1
+            assert state._parent_id == id2
+
+            # Verify the second checkpoint blob has parent_id == id1
+            with open(loc2) as f:
+                data2 = json.loads(f.read())
+            assert data2["parent_id"] == id1
+
+    @pytest.mark.asyncio
+    async def test_acheckpoint_chaining(self) -> None:
+        """Async checkpoint path chains lineage identically to sync."""
+        state = self._make_state()
+        state._provider = JsonProvider()
+        with tempfile.TemporaryDirectory() as d:
+            await state.acheckpoint(d)
+            id1 = state._checkpoint_id
+            assert id1 is not None
+
+            loc2 = await state.acheckpoint(d)
+            id2 = state._checkpoint_id
+            assert id2 != id1
+            assert state._parent_id == id2
+
+            with open(loc2) as f:
+                data2 = json.loads(f.read())
+            assert data2["parent_id"] == id1
+
+    def _make_state(self) -> RuntimeState:
+        from crewai import Agent, Crew
+
+        agent = Agent(role="r", goal="g", backstory="b", llm="gpt-4o-mini")
+        crew = Crew(agents=[agent], tasks=[], verbose=False)
+        return RuntimeState(root=[crew])
+
+
+# ---------- SqliteProvider forking ----------
+
+
+class TestSqliteProviderFork:
+    def test_checkpoint_stores_branch_and_parent(self) -> None:
+        provider = SqliteProvider()
+        with tempfile.TemporaryDirectory() as d:
+            db = os.path.join(d, "cp.db")
+            loc = provider.checkpoint("{}", db, parent_id="p1", branch="exp")
+            cid = provider.extract_id(loc)
+
+            with sqlite3.connect(db) as conn:
+                row = conn.execute(
+                    "SELECT parent_id, branch FROM checkpoints WHERE id = ?",
+                    (cid,),
+                ).fetchone()
+            assert row == ("p1", "exp")
+
+    def test_prune_branch_aware(self) -> None:
+        provider = SqliteProvider()
+        with tempfile.TemporaryDirectory() as d:
+            db = os.path.join(d, "cp.db")
+            for _ in range(3):
+                provider.checkpoint("{}", db, branch="main")
+            for _ in range(2):
+                provider.checkpoint("{}", db, branch="fork/a")
+
+            provider.prune(db, max_keep=1, branch="main")
+
+            with sqlite3.connect(db) as conn:
+                main_count = conn.execute(
+                    "SELECT COUNT(*) FROM checkpoints WHERE branch = 'main'"
+                ).fetchone()[0]
+                fork_count = conn.execute(
+                    "SELECT COUNT(*) FROM checkpoints WHERE branch = 'fork/a'"
+                ).fetchone()[0]
+            assert main_count == 1
+            assert fork_count == 2
+
+    def test_extract_id(self) -> None:
+        provider = SqliteProvider()
+        assert provider.extract_id("/path/to/db#abc123") == "abc123"
+
+    def test_checkpoint_chaining_sqlite(self) -> None:
+        state = self._make_state()
+        state._provider = SqliteProvider()
+        with tempfile.TemporaryDirectory() as d:
+            db = os.path.join(d, "cp.db")
+            state.checkpoint(db)
+            id1 = state._checkpoint_id
+
+            state.checkpoint(db)
+            id2 = state._checkpoint_id
+            assert id2 != id1
+
+            # Second row should have parent_id == id1
+            with sqlite3.connect(db) as conn:
+                row = conn.execute(
+                    "SELECT parent_id FROM checkpoints WHERE id = ?", (id2,)
+                ).fetchone()
+            assert row[0] == id1
+
+    def _make_state(self) -> RuntimeState:
+        from crewai import Agent, Crew
+
+        agent = Agent(role="r", goal="g", backstory="b", llm="gpt-4o-mini")
+        crew = Crew(agents=[agent], tasks=[], verbose=False)
+        return RuntimeState(root=[crew])
+
+
+# ---------- Kickoff from_checkpoint parameter ----------
+
+
+class TestKickoffFromCheckpoint:
+    def test_crew_kickoff_delegates_to_from_checkpoint(self) -> None:
+        mock_restored = MagicMock(spec=Crew)
+        mock_restored.kickoff.return_value = "result"
+
+        cfg = CheckpointConfig(restore_from="/path/to/cp.json")
+        with patch.object(Crew, "from_checkpoint", return_value=mock_restored):
+            agent = Agent(role="r", goal="g", backstory="b", llm="gpt-4o-mini")
+            crew = Crew(agents=[agent], tasks=[], verbose=False)
+            result = crew.kickoff(inputs={"k": "v"}, from_checkpoint=cfg)
+
+        mock_restored.kickoff.assert_called_once_with(
+            inputs={"k": "v"}, input_files=None
+        )
+        assert mock_restored.checkpoint.restore_from is None
+        assert result == "result"
+
+    def test_crew_kickoff_config_only_sets_checkpoint(self) -> None:
+        cfg = CheckpointConfig(on_events=["task_completed"])
+        agent = Agent(role="r", goal="g", backstory="b", llm="gpt-4o-mini")
+        crew = Crew(agents=[agent], tasks=[], verbose=False)
+        assert crew.checkpoint is None
+        with patch("crewai.crew.get_env_context"), \
+             patch("crewai.crew.prepare_kickoff", side_effect=RuntimeError("stop")):
+            with pytest.raises(RuntimeError, match="stop"):
+                crew.kickoff(from_checkpoint=cfg)
+        assert isinstance(crew.checkpoint, CheckpointConfig)
+        assert crew.checkpoint.on_events == ["task_completed"]
+
+    def test_flow_kickoff_delegates_to_from_checkpoint(self) -> None:
+        mock_restored = MagicMock(spec=Flow)
+        mock_restored.kickoff.return_value = "flow_result"
+
+        cfg = CheckpointConfig(restore_from="/path/to/flow_cp.json")
+        with patch.object(Flow, "from_checkpoint", return_value=mock_restored):
+            flow = Flow()
+            result = flow.kickoff(from_checkpoint=cfg)
+
+        mock_restored.kickoff.assert_called_once_with(
+            inputs=None, input_files=None
+        )
+        assert mock_restored.checkpoint.restore_from is None
+        assert result == "flow_result"

lib/crewai/tests/test_llm.py

@@ -1001,6 +1001,8 @@ def test_usage_info_non_streaming_with_call():
         "completion_tokens": 0,
         "successful_requests": 0,
         "cached_prompt_tokens": 0,
+        "reasoning_tokens": 0,
+        "cache_creation_tokens": 0,
     }
     assert llm.stream is False
 
@@ -1025,6 +1027,8 @@ def test_usage_info_streaming_with_call():
         "completion_tokens": 0,
         "successful_requests": 0,
         "cached_prompt_tokens": 0,
+        "reasoning_tokens": 0,
+        "cache_creation_tokens": 0,
     }
     assert llm.stream is True
 
@@ -1056,6 +1060,8 @@ async def test_usage_info_non_streaming_with_acall():
         "completion_tokens": 0,
         "successful_requests": 0,
         "cached_prompt_tokens": 0,
+        "reasoning_tokens": 0,
+        "cache_creation_tokens": 0,
     }
 
     with patch.object(
@@ -1089,6 +1095,8 @@ async def test_usage_info_non_streaming_with_acall_and_stop():
         "completion_tokens": 0,
         "successful_requests": 0,
         "cached_prompt_tokens": 0,
+        "reasoning_tokens": 0,
+        "cache_creation_tokens": 0,
     }
 
     with patch.object(
@@ -1121,6 +1129,8 @@ async def test_usage_info_streaming_with_acall():
         "completion_tokens": 0,
         "successful_requests": 0,
         "cached_prompt_tokens": 0,
+        "reasoning_tokens": 0,
+        "cache_creation_tokens": 0,
     }
 
     with patch.object(

lib/crewai/tests/tracing/test_trace_serialization.py

@@ -0,0 +1,612 @@
+"""Tests for trace serialization optimization using Pydantic v2 context-based serialization.
+
+These tests verify that trace events use @field_serializer with SerializationInfo.context
+to produce lightweight representations, reducing event sizes from 50-100KB to a few KB.
+"""
+
+import json
+import uuid
+from typing import Any
+from unittest.mock import MagicMock
+
+import pytest
+from pydantic import ConfigDict
+
+from crewai.agents.agent_builder.base_agent import BaseAgent
+from crewai.events.base_events import _trace_agent_ref, _trace_task_ref, _trace_tool_names
+from crewai.events.listeners.tracing.utils import safe_serialize_to_dict
+from crewai.utilities.serialization import to_serializable
+
+
+# ---------------------------------------------------------------------------
+# Lightweight BaseAgent subclass for tests (avoids heavy dependencies)
+# ---------------------------------------------------------------------------
+
+class _StubAgent(BaseAgent):
+    """Minimal BaseAgent subclass that satisfies validation without heavy deps."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    def execute_task(self, *a: Any, **kw: Any) -> str:
+        return ""
+
+    def create_agent_executor(self, *a: Any, **kw: Any) -> None:
+        pass
+
+    def _parse_tools(self, *a: Any, **kw: Any) -> list:
+        return []
+
+    def get_delegation_tools(self, *a: Any, **kw: Any) -> list:
+        return []
+
+    def get_output_converter(self, *a: Any, **kw: Any) -> Any:
+        return None
+
+    def get_multimodal_tools(self, *a: Any, **kw: Any) -> list:
+        return []
+
+    async def aexecute_task(self, *a: Any, **kw: Any) -> str:
+        return ""
+
+    def get_mcp_tools(self, *a: Any, **kw: Any) -> list:
+        return []
+
+    def get_platform_tools(self, *a: Any, **kw: Any) -> list:
+        return []
+
+
+def _make_stub_agent(**overrides) -> _StubAgent:
+    """Create a minimal BaseAgent instance for testing."""
+    defaults = {
+        "role": "Researcher",
+        "goal": "Research things",
+        "backstory": "Expert researcher",
+        "tools": [],
+    }
+    defaults.update(overrides)
+    return _StubAgent(**defaults)
+
+
+# ---------------------------------------------------------------------------
+# Helpers to build realistic mock objects for event fields
+# ---------------------------------------------------------------------------
+
+def _make_mock_task(**overrides):
+    task = MagicMock()
+    task.id = overrides.get("id", uuid.uuid4())
+    task.name = overrides.get("name", "Research Task")
+    task.description = overrides.get("description", "Do research")
+    task.expected_output = overrides.get("expected_output", "Research results")
+    task.async_execution = overrides.get("async_execution", False)
+    task.human_input = overrides.get("human_input", False)
+    task.agent = overrides.get("agent", _make_stub_agent())
+    task.context = overrides.get("context", None)
+    task.crew = MagicMock()
+    task.tools = overrides.get("tools", [MagicMock(), MagicMock()])
+
+    fp = MagicMock()
+    fp.uuid_str = str(uuid.uuid4())
+    fp.metadata = {"name": task.name}
+    task.fingerprint = fp
+
+    return task
+
+
+def _make_stub_tool(tool_name="web_search") -> Any:
+    """Create a minimal BaseTool instance for testing."""
+    from crewai.tools.base_tool import BaseTool
+
+    class _StubTool(BaseTool):
+        name: str = "stub"
+        description: str = "stub tool"
+
+        def _run(self, *a: Any, **kw: Any) -> str:
+            return ""
+
+    return _StubTool(name=tool_name, description=f"{tool_name} tool")
+
+
+# ---------------------------------------------------------------------------
+# Unit tests: trace ref helpers
+# ---------------------------------------------------------------------------
+
+class TestTraceRefHelpers:
+    def test_trace_agent_ref(self):
+        agent = _make_stub_agent(role="Analyst")
+        ref = _trace_agent_ref(agent)
+        assert ref["role"] == "Analyst"
+        assert "id" in ref
+        assert len(ref) == 2  # only id and role
+
+    def test_trace_agent_ref_none(self):
+        assert _trace_agent_ref(None) is None
+
+    def test_trace_task_ref(self):
+        task = _make_mock_task(name="Write Report")
+        ref = _trace_task_ref(task)
+        assert ref["name"] == "Write Report"
+        assert "id" in ref
+        assert len(ref) == 2
+
+    def test_trace_task_ref_falls_back_to_description(self):
+        task = _make_mock_task(name=None, description="Describe the report")
+        ref = _trace_task_ref(task)
+        assert ref["name"] == "Describe the report"
+
+    def test_trace_task_ref_none(self):
+        assert _trace_task_ref(None) is None
+
+    def test_trace_tool_names(self):
+        tools = [_make_stub_tool("search"), _make_stub_tool("read")]
+        names = _trace_tool_names(tools)
+        assert names == ["search", "read"]
+
+    def test_trace_tool_names_empty(self):
+        assert _trace_tool_names([]) is None
+        assert _trace_tool_names(None) is None
+
+
+# ---------------------------------------------------------------------------
+# Integration tests: field serializers on real event classes
+# ---------------------------------------------------------------------------
+
+class TestAgentEventFieldSerializers:
+    """Test that agent event field serializers respond to trace context."""
+
+    def test_agent_execution_started_trace_context(self):
+        from crewai.events.types.agent_events import AgentExecutionStartedEvent
+
+        agent = _make_stub_agent(role="Researcher")
+        task = _make_mock_task(name="Research Task")
+        tools = [_make_stub_tool("search"), _make_stub_tool("read")]
+
+        event = AgentExecutionStartedEvent(
+            agent=agent, task=task, tools=tools, task_prompt="Do research"
+        )
+
+        # With trace context: lightweight refs
+        trace_dump = event.model_dump(context={"trace": True})
+        assert trace_dump["agent"] == {"id": str(agent.id), "role": "Researcher"}
+        assert trace_dump["task"] == {"id": str(task.id), "name": "Research Task"}
+        assert trace_dump["tools"] == ["search", "read"]
+
+    def test_agent_execution_started_no_context(self):
+        from crewai.events.types.agent_events import AgentExecutionStartedEvent
+
+        agent = _make_stub_agent(role="SpecificRole")
+        task = _make_mock_task()
+
+        event = AgentExecutionStartedEvent(
+            agent=agent, task=task, tools=None, task_prompt="Do research"
+        )
+
+        # Without context: full agent dict (Pydantic model_dump expands it)
+        normal_dump = event.model_dump()
+        assert isinstance(normal_dump["agent"], dict)
+        assert normal_dump["agent"]["role"] == "SpecificRole"
+        # Should have ALL agent fields, not just the lightweight ref
+        assert "goal" in normal_dump["agent"]
+        assert "backstory" in normal_dump["agent"]
+        assert "max_iter" in normal_dump["agent"]
+
+    def test_agent_execution_error_preserves_identification(self):
+        from crewai.events.types.agent_events import AgentExecutionErrorEvent
+
+        agent = _make_stub_agent(role="Analyst")
+        task = _make_mock_task(name="Analysis Task")
+
+        event = AgentExecutionErrorEvent(
+            agent=agent, task=task, error="Something went wrong"
+        )
+
+        trace_dump = event.model_dump(context={"trace": True})
+        # Error events should still have agent/task identification as refs
+        assert trace_dump["agent"]["role"] == "Analyst"
+        assert trace_dump["task"]["name"] == "Analysis Task"
+        assert trace_dump["error"] == "Something went wrong"
+
+    def test_agent_execution_completed_trace_context(self):
+        from crewai.events.types.agent_events import AgentExecutionCompletedEvent
+
+        agent = _make_stub_agent(role="Writer")
+        task = _make_mock_task(name="Writing Task")
+
+        event = AgentExecutionCompletedEvent(
+            agent=agent, task=task, output="Final output"
+        )
+
+        trace_dump = event.model_dump(context={"trace": True})
+        assert trace_dump["agent"]["role"] == "Writer"
+        assert trace_dump["task"]["name"] == "Writing Task"
+        assert trace_dump["output"] == "Final output"
+
+
+class TestTaskEventFieldSerializers:
+    """Test that task event field serializers respond to trace context."""
+
+    def test_task_started_trace_context(self):
+        from crewai.events.types.task_events import TaskStartedEvent
+
+        task = _make_mock_task(name="Test Task")
+        event = TaskStartedEvent(task=task, context="some context")
+
+        trace_dump = event.model_dump(context={"trace": True})
+        assert trace_dump["task"] == {"id": str(task.id), "name": "Test Task"}
+        assert trace_dump["context"] == "some context"
+
+    def test_task_failed_trace_context(self):
+        from crewai.events.types.task_events import TaskFailedEvent
+
+        task = _make_mock_task(name="Failing Task")
+        event = TaskFailedEvent(task=task, error="Task failed")
+
+        trace_dump = event.model_dump(context={"trace": True})
+        assert trace_dump["task"]["name"] == "Failing Task"
+        assert trace_dump["error"] == "Task failed"
+
+
+class TestCrewEventFieldSerializers:
+    """Test that crew event field serializers respond to trace context."""
+
+    def test_crew_kickoff_started_excludes_crew_in_trace(self):
+        from crewai.events.types.crew_events import CrewKickoffStartedEvent
+
+        crew = MagicMock()
+        crew.fingerprint = MagicMock()
+        crew.fingerprint.uuid_str = str(uuid.uuid4())
+        crew.fingerprint.metadata = {}
+
+        event = CrewKickoffStartedEvent(
+            crew=crew, crew_name="TestCrew", inputs={"key": "value"}
+        )
+
+        trace_dump = event.model_dump(context={"trace": True})
+        # crew field should be None in trace context
+        assert trace_dump["crew"] is None
+        # scalar fields preserved
+        assert trace_dump["crew_name"] == "TestCrew"
+        assert trace_dump["inputs"] == {"key": "value"}
+
+    def test_crew_event_no_context_preserves_crew(self):
+        from crewai.events.types.crew_events import CrewKickoffStartedEvent
+
+        crew = MagicMock()
+        crew.fingerprint = MagicMock()
+        crew.fingerprint.uuid_str = str(uuid.uuid4())
+        crew.fingerprint.metadata = {}
+
+        event = CrewKickoffStartedEvent(
+            crew=crew, crew_name="TestCrew", inputs=None
+        )
+
+        normal_dump = event.model_dump()
+        # Without trace context, crew should NOT be None (field serializer didn't fire)
+        assert normal_dump["crew"] is not None
+
+
+class TestLLMEventFieldSerializers:
+    """Test that LLM event field serializers respond to trace context."""
+
+    def test_llm_call_started_excludes_callbacks_in_trace(self):
+        from crewai.events.types.llm_events import LLMCallStartedEvent
+
+        event = LLMCallStartedEvent(
+            call_id="test-call",
+            messages=[{"role": "user", "content": "Hello"}],
+            tools=[{"name": "search", "description": "Search tool"}],
+            callbacks=[MagicMock(), MagicMock()],
+            available_functions={"search": MagicMock()},
+        )
+
+        trace_dump = event.model_dump(context={"trace": True})
+        # callbacks and available_functions excluded
+        assert trace_dump["callbacks"] is None
+        assert trace_dump["available_functions"] is None
+        # tools preserved (lightweight list of dicts)
+        assert trace_dump["tools"] == [{"name": "search", "description": "Search tool"}]
+        # messages preserved
+        assert trace_dump["messages"] == [{"role": "user", "content": "Hello"}]
+
+
+# ---------------------------------------------------------------------------
+# Integration tests: safe_serialize_to_dict with context
+# ---------------------------------------------------------------------------
+
+class TestSafeSerializeWithContext:
+    """Test that safe_serialize_to_dict properly passes context through."""
+
+    def test_context_flows_through_to_field_serializers(self):
+        from crewai.events.types.agent_events import AgentExecutionErrorEvent
+
+        agent = _make_stub_agent(role="Worker")
+        task = _make_mock_task(name="Work Task")
+
+        event = AgentExecutionErrorEvent(
+            agent=agent, task=task, error="error msg"
+        )
+
+        result = safe_serialize_to_dict(event, context={"trace": True})
+        # Field serializers should have fired
+        assert result["agent"] == {"id": str(agent.id), "role": "Worker"}
+        assert result["task"] == {"id": str(task.id), "name": "Work Task"}
+        assert result["error"] == "error msg"
+
+    def test_no_context_preserves_full_serialization(self):
+        from crewai.events.types.task_events import TaskFailedEvent
+
+        task = _make_mock_task(name="Test")
+        event = TaskFailedEvent(task=task, error="fail")
+
+        result = safe_serialize_to_dict(event)
+        # Without context, task should not be a lightweight ref
+        assert result.get("task") is not None
+        # It should be the raw object (model_dump returns it as-is for Any fields)
+        # to_serializable will then repr() or process it further
+
+
+# ---------------------------------------------------------------------------
+# Integration tests: TraceCollectionListener._build_event_data
+# ---------------------------------------------------------------------------
+
+class TestBuildEventData:
+    @pytest.fixture
+    def listener(self):
+        from crewai.events.listeners.tracing.trace_listener import (
+            TraceCollectionListener,
+        )
+        TraceCollectionListener._instance = None
+        TraceCollectionListener._initialized = False
+        TraceCollectionListener._listeners_setup = False
+        return TraceCollectionListener()
+
+    def test_crew_kickoff_started_has_crew_structure(self, listener):
+        agent = _make_stub_agent(role="Researcher")
+        agent.tools = [_make_stub_tool("search"), _make_stub_tool("read")]
+
+        task = _make_mock_task(name="Research Task", agent=agent)
+        task.context = None
+
+        crew = MagicMock()
+        crew.agents = [agent]
+        crew.tasks = [task]
+        crew.process = "sequential"
+        crew.verbose = True
+        crew.memory = False
+        crew.fingerprint = MagicMock()
+        crew.fingerprint.uuid_str = str(uuid.uuid4())
+        crew.fingerprint.metadata = {}
+
+        from crewai.events.types.crew_events import CrewKickoffStartedEvent
+        event = CrewKickoffStartedEvent(
+            crew=crew, crew_name="TestCrew", inputs={"key": "value"}
+        )
+
+        result = listener._build_event_data("crew_kickoff_started", event, None)
+
+        assert "crew_structure" in result
+        cs = result["crew_structure"]
+        assert len(cs["agents"]) == 1
+        assert cs["agents"][0]["role"] == "Researcher"
+        assert cs["agents"][0]["tool_names"] == ["search", "read"]
+        assert len(cs["tasks"]) == 1
+        assert cs["tasks"][0]["name"] == "Research Task"
+        assert "agent_ref" in cs["tasks"][0]
+        assert cs["tasks"][0]["agent_ref"]["role"] == "Researcher"
+
+    def test_crew_kickoff_started_context_task_ids(self, listener):
+        agent = _make_stub_agent()
+        task1 = _make_mock_task(name="Task 1", agent=agent)
+        task1.context = None
+        task2 = _make_mock_task(name="Task 2", agent=agent)
+        task2.context = [task1]
+
+        crew = MagicMock()
+        crew.agents = [agent]
+        crew.tasks = [task1, task2]
+        crew.process = "sequential"
+        crew.verbose = False
+        crew.memory = False
+        crew.fingerprint = MagicMock()
+        crew.fingerprint.uuid_str = str(uuid.uuid4())
+        crew.fingerprint.metadata = {}
+
+        from crewai.events.types.crew_events import CrewKickoffStartedEvent
+        event = CrewKickoffStartedEvent(
+            crew=crew, crew_name="TestCrew", inputs=None
+        )
+
+        result = listener._build_event_data("crew_kickoff_started", event, None)
+        task2_data = result["crew_structure"]["tasks"][1]
+        assert "context_task_ids" in task2_data
+        assert str(task1.id) in task2_data["context_task_ids"]
+
+    def test_generic_event_uses_trace_context(self, listener):
+        """Non-complex events should use context-based serialization."""
+        from crewai.events.types.crew_events import CrewKickoffCompletedEvent
+
+        crew = MagicMock()
+        crew.fingerprint = MagicMock()
+        crew.fingerprint.uuid_str = str(uuid.uuid4())
+        crew.fingerprint.metadata = {}
+
+        event = CrewKickoffCompletedEvent(
+            crew=crew, crew_name="TestCrew", output="Final result", total_tokens=5000
+        )
+
+        result = listener._build_event_data("crew_kickoff_completed", event, None)
+
+        # Scalar fields preserved
+        assert result.get("crew_name") == "TestCrew"
+        assert result.get("total_tokens") == 5000
+        # crew excluded by field serializer
+        assert result.get("crew") is None
+        # No crew_structure (that's only for kickoff_started)
+        assert "crew_structure" not in result
+
+    def test_task_started_custom_projection(self, listener):
+        task = _make_mock_task(name="Test Task")
+        from crewai.events.types.task_events import TaskStartedEvent
+        event = TaskStartedEvent(task=task, context="test context")
+        source = MagicMock()
+        source.agent = _make_stub_agent(role="Worker")
+
+        result = listener._build_event_data("task_started", event, source)
+
+        assert result["task_name"] == "Test Task"
+        assert result["agent_role"] == "Worker"
+        assert result["task_id"] == str(task.id)
+        assert result["context"] == "test context"
+
+    def test_llm_call_started_uses_trace_context(self, listener):
+        from crewai.events.types.llm_events import LLMCallStartedEvent
+
+        event = LLMCallStartedEvent(
+            call_id="test",
+            messages=[{"role": "user", "content": "Hello"}],
+            tools=[{"name": "search"}],
+            callbacks=[MagicMock()],
+            available_functions={"fn": MagicMock()},
+        )
+
+        result = listener._build_event_data("llm_call_started", event, None)
+
+        # callbacks and available_functions excluded via field serializer
+        assert result.get("callbacks") is None
+        assert result.get("available_functions") is None
+        # tools preserved (lightweight schemas)
+        assert result.get("tools") == [{"name": "search"}]
+
+    def test_agent_execution_error_preserves_identification(self, listener):
+        """Error events should preserve agent/task identification via field serializers."""
+        from crewai.events.types.agent_events import AgentExecutionErrorEvent
+
+        agent = _make_stub_agent(role="Analyst")
+        task = _make_mock_task(name="Analysis")
+
+        event = AgentExecutionErrorEvent(
+            agent=agent, task=task, error="Something broke"
+        )
+
+        result = listener._build_event_data("agent_execution_error", event, None)
+
+        # Field serializers return lightweight refs, not None
+        assert result["agent"] == {"id": str(agent.id), "role": "Analyst"}
+        assert result["task"] == {"id": str(task.id), "name": "Analysis"}
+        assert result["error"] == "Something broke"
+
+    def test_task_failed_preserves_identification(self, listener):
+        from crewai.events.types.task_events import TaskFailedEvent
+
+        task = _make_mock_task(name="Failed Task")
+        event = TaskFailedEvent(task=task, error="Task failed")
+
+        result = listener._build_event_data("task_failed", event, None)
+
+        assert result["task"] == {"id": str(task.id), "name": "Failed Task"}
+        assert result["error"] == "Task failed"
+
+
+# ---------------------------------------------------------------------------
+# Size reduction verification
+# ---------------------------------------------------------------------------
+
+class TestSizeReduction:
+    @pytest.fixture
+    def listener(self):
+        from crewai.events.listeners.tracing.trace_listener import (
+            TraceCollectionListener,
+        )
+        TraceCollectionListener._instance = None
+        TraceCollectionListener._initialized = False
+        TraceCollectionListener._listeners_setup = False
+        return TraceCollectionListener()
+
+    def test_task_started_event_size(self, listener):
+        """task_started event data should be well under 2KB."""
+        agent = _make_stub_agent(
+            role="Researcher",
+            goal="Research" * 50,
+            backstory="Expert" * 100,
+        )
+        agent.tools = [_make_stub_tool(f"tool_{i}") for i in range(5)]
+
+        task = _make_mock_task(
+            name="Research Task",
+            description="Detailed description" * 20,
+            expected_output="Expected" * 10,
+            agent=agent,
+        )
+        task.context = [_make_mock_task() for _ in range(3)]
+        task.tools = [_make_stub_tool(f"t_{i}") for i in range(3)]
+
+        from crewai.events.types.task_events import TaskStartedEvent
+        event = TaskStartedEvent(task=task, context="test context")
+        source = MagicMock()
+        source.agent = agent
+
+        result = listener._build_event_data("task_started", event, source)
+        serialized = json.dumps(result, default=str)
+
+        assert len(serialized) < 2000, f"task_started too large: {len(serialized)} bytes"
+        assert "task_name" in result
+        assert "agent_role" in result
+
+    def test_error_event_size(self, listener):
+        """Error events should be small despite having agent/task refs."""
+        from crewai.events.types.agent_events import AgentExecutionErrorEvent
+
+        agent = _make_stub_agent(
+            goal="Very long goal " * 100,
+            backstory="Very long backstory " * 100,
+        )
+        task = _make_mock_task(description="Very long description " * 100)
+
+        event = AgentExecutionErrorEvent(
+            agent=agent, task=task, error="error"
+        )
+
+        result = listener._build_event_data("agent_execution_error", event, None)
+        serialized = json.dumps(result, default=str)
+
+        # Should be small - agent/task are just {id, role/name} refs
+        assert len(serialized) < 5000, f"error event too large: {len(serialized)} bytes"
+
+
+# ---------------------------------------------------------------------------
+# to_serializable context threading
+# ---------------------------------------------------------------------------
+
+class TestToSerializableContext:
+    """Test that context parameter flows through to_serializable correctly."""
+
+    def test_context_passed_to_model_dump(self):
+        from crewai.events.types.agent_events import AgentExecutionErrorEvent
+
+        agent = _make_stub_agent(role="Tester")
+        task = _make_mock_task(name="Test Task")
+
+        event = AgentExecutionErrorEvent(
+            agent=agent, task=task, error="test error"
+        )
+
+        # Directly use to_serializable with context
+        result = to_serializable(event, context={"trace": True})
+        assert isinstance(result, dict)
+        assert result["agent"] == {"id": str(agent.id), "role": "Tester"}
+        assert result["task"] == {"id": str(task.id), "name": "Test Task"}
+
+    def test_no_context_does_not_trigger_serializers(self):
+        from crewai.events.types.crew_events import CrewKickoffStartedEvent
+
+        crew = MagicMock()
+        crew.fingerprint = MagicMock()
+        crew.fingerprint.uuid_str = str(uuid.uuid4())
+        crew.fingerprint.metadata = {}
+
+        event = CrewKickoffStartedEvent(
+            crew=crew, crew_name="Test", inputs=None
+        )
+
+        # Without context, crew should NOT be None
+        result = event.model_dump()
+        assert result["crew"] is not None