docs: document FileWriterTool path confinement and CREWAI_TOOLS_ALLOWED_DIRS

Document the deny-by-default allow-list behavior, the new
CREWAI_TOOLS_ALLOWED_DIRS env var for extending allowed roots, the
fail-closed behavior when cwd is the filesystem root, and the
CREWAI_TOOLS_ALLOW_UNSAFE_PATHS escape hatch.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/docs.json

@@ -398,6 +398,7 @@
                     "pages": [
                       "edge/en/enterprise/features/automations",
                       "edge/en/enterprise/features/crew-studio",
+                      "edge/en/enterprise/features/merged-step-card",
                       "edge/en/enterprise/features/marketplace",
                       "edge/en/enterprise/features/agent-repositories",
                       "edge/en/enterprise/features/tools-and-integrations",
@@ -515,6 +516,7 @@
                       "edge/en/enterprise/guides/update-crew",
                       "edge/en/enterprise/guides/enable-crew-studio",
                       "edge/en/enterprise/guides/capture_telemetry_logs",
+                      "edge/en/enterprise/guides/datadog",
                       "edge/en/enterprise/guides/azure-openai-setup",
                       "edge/en/enterprise/guides/vertex-ai-workload-identity-setup",
                       "edge/en/enterprise/guides/tool-repository",
@@ -921,6 +923,7 @@
                     "pages": [
                       "v1.14.7/en/enterprise/features/automations",
                       "v1.14.7/en/enterprise/features/crew-studio",
+                      "v1.14.7/en/enterprise/features/merged-step-card",
                       "v1.14.7/en/enterprise/features/marketplace",
                       "v1.14.7/en/enterprise/features/agent-repositories",
                       "v1.14.7/en/enterprise/features/tools-and-integrations",
@@ -8547,6 +8550,7 @@
                     "pages": [
                       "edge/pt-BR/enterprise/features/automations",
                       "edge/pt-BR/enterprise/features/crew-studio",
+                      "edge/pt-BR/enterprise/features/merged-step-card",
                       "edge/pt-BR/enterprise/features/marketplace",
                       "edge/pt-BR/enterprise/features/agent-repositories",
                       "edge/pt-BR/enterprise/features/tools-and-integrations",
@@ -8647,6 +8651,7 @@
                       "edge/pt-BR/enterprise/guides/update-crew",
                       "edge/pt-BR/enterprise/guides/enable-crew-studio",
                       "edge/pt-BR/enterprise/guides/capture_telemetry_logs",
+                      "edge/pt-BR/enterprise/guides/datadog",
                       "edge/pt-BR/enterprise/guides/azure-openai-setup",
                       "edge/pt-BR/enterprise/guides/tool-repository",
                       "edge/pt-BR/enterprise/guides/custom-mcp-server",
@@ -9047,6 +9052,7 @@
                     "pages": [
                       "v1.14.7/pt-BR/enterprise/features/automations",
                       "v1.14.7/pt-BR/enterprise/features/crew-studio",
+                      "v1.14.7/pt-BR/enterprise/features/merged-step-card",
                       "v1.14.7/pt-BR/enterprise/features/marketplace",
                       "v1.14.7/pt-BR/enterprise/features/agent-repositories",
                       "v1.14.7/pt-BR/enterprise/features/tools-and-integrations",
@@ -16410,6 +16416,7 @@
                     "pages": [
                       "edge/ko/enterprise/features/automations",
                       "edge/ko/enterprise/features/crew-studio",
+                      "edge/ko/enterprise/features/merged-step-card",
                       "edge/ko/enterprise/features/marketplace",
                       "edge/ko/enterprise/features/agent-repositories",
                       "edge/ko/enterprise/features/tools-and-integrations",
@@ -16510,6 +16517,7 @@
                       "edge/ko/enterprise/guides/update-crew",
                       "edge/ko/enterprise/guides/enable-crew-studio",
                       "edge/ko/enterprise/guides/capture_telemetry_logs",
+                      "edge/ko/enterprise/guides/datadog",
                       "edge/ko/enterprise/guides/azure-openai-setup",
                       "edge/ko/enterprise/guides/tool-repository",
                       "edge/ko/enterprise/guides/custom-mcp-server",
@@ -16922,6 +16930,7 @@
                     "pages": [
                       "v1.14.7/ko/enterprise/features/automations",
                       "v1.14.7/ko/enterprise/features/crew-studio",
+                      "v1.14.7/ko/enterprise/features/merged-step-card",
                       "v1.14.7/ko/enterprise/features/marketplace",
                       "v1.14.7/ko/enterprise/features/agent-repositories",
                       "v1.14.7/ko/enterprise/features/tools-and-integrations",
@@ -24465,6 +24474,7 @@
                     "pages": [
                       "edge/ar/enterprise/features/automations",
                       "edge/ar/enterprise/features/crew-studio",
+                      "edge/ar/enterprise/features/merged-step-card",
                       "edge/ar/enterprise/features/marketplace",
                       "edge/ar/enterprise/features/agent-repositories",
                       "edge/ar/enterprise/features/tools-and-integrations",
@@ -24565,6 +24575,7 @@
                       "edge/ar/enterprise/guides/update-crew",
                       "edge/ar/enterprise/guides/enable-crew-studio",
                       "edge/ar/enterprise/guides/capture_telemetry_logs",
+                      "edge/ar/enterprise/guides/datadog",
                       "edge/ar/enterprise/guides/azure-openai-setup",
                       "edge/ar/enterprise/guides/tool-repository",
                       "edge/ar/enterprise/guides/custom-mcp-server",
@@ -24977,6 +24988,7 @@
                     "pages": [
                       "v1.14.7/ar/enterprise/features/automations",
                       "v1.14.7/ar/enterprise/features/crew-studio",
+                      "v1.14.7/ar/enterprise/features/merged-step-card",
                       "v1.14.7/ar/enterprise/features/marketplace",
                       "v1.14.7/ar/enterprise/features/agent-repositories",
                       "v1.14.7/ar/enterprise/features/tools-and-integrations",

docs/edge/ar/changelog.mdx

@@ -4,6 +4,27 @@ description: "تحديثات المنتج والتحسينات وإصلاحات
 icon: "clock"
 mode: "wide"
 ---
+<Update label="18 يونيو 2026">
+  ## v1.14.8a2
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.8a2)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - إضافة إجراء عميل واحد إلى تعريفات التدفق
+  - التحقق من تعبيرات CEL للتدفق عند تحميل التعريف
+
+  ### الوثائق
+  - إضافة دليل تكامل Datadog مع لوحة عمليات قابلة للاستيراد
+  - تحديث اللقطة وسجل التغييرات للإصدار v1.14.8a1
+
+  ## المساهمون
+
+  @joaomdmoura, @lucasgomide, @vinibrsl
+
+</Update>
+
 <Update label="18 يونيو 2026">
   ## v1.14.8a1
 

docs/edge/ar/enterprise/features/merged-step-card.mdx

@@ -0,0 +1,87 @@
+---
+title: بطاقة واحدة لكل خطوة
+description: "كل خطوة على لوحة Studio هي بطاقة واحدة تجمع بين المهمة والوكيل الذي ينفّذها."
+icon: "layer-group"
+mode: "wide"
+---
+
+{/* CLEANUP: This <Note> banner is the only time-bound content on the page. After the feature ships (Wednesday, June 24th 2026), delete the banner below — the rest of the page is evergreen present-tense docs and needs no other edits. */}
+<Note>
+  **الإطلاق يوم الأربعاء 24 يونيو.** تنتقل لوحة Studio إلى بطاقة واحدة لكل خطوة بدلاً من عُقد منفصلة للمهمة والوكيل، وذلك لتبسيط اللوحة مع إضافتنا لوظائف جديدة قريبًا. تستمر أتمتتك الحالية في العمل دون أي تغييرات مطلوبة — تبقى جميع إعدادات المهمة والوكيل متاحة، ولكن منظّمة في بطاقة واحدة.
+</Note>
+
+## نظرة عامة
+
+على لوحة Studio، تُمثَّل كل خطوة عمل بـ **بطاقة واحدة**. تجمع البطاقة بين عنصرين كانا في السابق في عُقد منفصلة:
+
+- **المهمة** — ماذا تفعل (الاسم، الوصف، المخرجات المتوقعة، وتنسيق الاستجابة).
+- **الوكيل** — من ينفّذها (الوكيل المُعيَّن ونموذجه وأدواته).
+
+الوكيل ليس مشاركًا مستقلاً في سير العمل لديك — بل هو سمة من سمات المهمة: *أي وكيل ينفّذ هذا العمل.* وضع المهمة والوكيل في بطاقة واحدة يجعل هذه العلاقة واضحة، ويحوّل أتمتتك إلى سلسلة واحدة من وحدات العمل من اليسار إلى اليمين يسهل قراءتها بنظرة واحدة.
+
+<Frame caption="بطاقة واحدة لكل خطوة: المهمة مع ملخص للوكيل المُعيَّن في التذييل.">
+  ![بطاقات الخطوات الموحّدة على اللوحة](/images/enterprise/merged-step-card-canvas.png)
+</Frame>
+
+## على اللوحة
+
+تعرض كل بطاقة مطوية ما يلي:
+
+- **اسم المهمة ووصفها** في الأعلى.
+- **تذييل يلخّص الوكيل المُعيَّن** — الصورة الرمزية والاسم والنموذج والأدوات.
+
+لا توجد عقدة وكيل منفصلة ولا حافة عمودية من الوكيل ← المهمة. تتصل خطواتك مباشرةً ببعضها البعض بالترتيب الذي تُنفَّذ به.
+
+## في المحرّر
+
+افتح بطاقة لتحريرها. العرض الموسّع هو البطاقة نفسها في حالة مفصّلة — وليس شاشة مختلفة — منظّمة في قسمين موسومين بوضوح.
+
+<Frame caption="المحرّر الموسّع: قسم المهمة مفتوح، والوكيل ملخّص أسفله.">
+  ![محرّر الخطوة الموسّع](/images/enterprise/merged-step-card-editor.png)
+</Frame>
+
+### المهمة — ماذا تفعل
+
+مفتوحة افتراضيًا، لأنها ما تحرّره عادةً:
+
+- **الاسم**
+- **الوصف**
+- **المخرجات المتوقعة**
+- **تنسيق الاستجابة** — يظهر هنا لأنه يتحكم تحديدًا في ما تقرأه الخطوات اللاحقة (مثل التوجيه) من هذه الخطوة.
+
+### الوكيل — من ينفّذها
+
+يُعرض الوكيل المُعيَّن كملخّص — **الاسم والنموذج والأدوات في سطر واحد**. ويُحفَظ إعداده الأعمق خلف قسمين قابلين للطي:
+
+- **الدور والهدف والخلفية**
+- **إعدادات الوكيل** — الاستدلال، الحد الأقصى لمحاولات الاستدلال، السماح بالتفويض، الحد الأقصى للتكرارات، وإعدادات LLM.
+
+<Tip>
+  الإعداد الكامل للوكيل — الدور، الهدف، الخلفية، النموذج، الأدوات، إعدادات LLM، وكامل كتلة إعدادات الوكيل — موجود خلف القسمين القابلين للطي **الدور والهدف والخلفية** و**إعدادات الوكيل**، منظّمًا حسب عدد مرّات تحريرك له.
+</Tip>
+
+## التبديل مقابل تحرير الوكيل
+
+هناك طريقتان متمايزتان للتعامل مع الوكيل في البطاقة، وكل منهما تؤدي وظيفة مختلفة:
+
+- **التبديل (Swap)** يعيد تعيين *أي* وكيل ينفّذ هذه المهمة. استخدم عنصر التحكم **تبديل** لاختيار وكيل مختلف من هذا المشروع، أو اختيار واحد من مستودع الوكلاء، أو إنشاء وكيل جديد. هذا مقصور على نطاق المهمة.
+- **تحرير** الوكيل — بفتح **الدور والهدف والخلفية** أو **إعدادات الوكيل** — يغيّر الوكيل *نفسه*.
+
+<Frame caption="التبديل يغيّر الوكيل الذي ينفّذ المهمة.">
+  ![لوحة تبديل الوكيل](/images/enterprise/merged-step-card-swap-agent.png)
+</Frame>
+
+<Warning>
+  **الوكلاء قابلون لإعادة الاستخدام ومشتركون.** يمكن للوكيل نفسه تنفيذ أكثر من مهمة عبر مشروعك. تحرير دور الوكيل أو خلفيته أو إعداداته يحدّث ذلك الوكيل **في كل مكان يُستخدم فيه** — وليس فقط في البطاقة التي فتحتها. إذا أردت تطبيق تغيير على خطوة واحدة فقط، فقم **بالتبديل** إلى وكيل مختلف بدلاً من تحرير الوكيل المشترك.
+</Warning>
+
+## ذات صلة
+
+<CardGroup cols={2}>
+  <Card title="Crew Studio" href="/ar/enterprise/features/crew-studio" icon="pencil">
+    أنشئ الأتمتة بمساعدة الذكاء الاصطناعي ومحرّر مرئي.
+  </Card>
+  <Card title="مستودعات الوكلاء" href="/ar/enterprise/features/agent-repositories" icon="users">
+    إدارة الوكلاء وإعادة استخدامهم عبر أتمتتك.
+  </Card>
+</CardGroup>

docs/edge/ar/enterprise/guides/capture_telemetry_logs.mdx

@@ -9,6 +9,10 @@ mode: "wide"
 
 تتبع بيانات القياس [اتفاقيات OpenTelemetry GenAI الدلالية](https://opentelemetry.io/docs/specs/semconv/gen-ai/) بالإضافة إلى سمات خاصة بـ CrewAI.
 
+<Tip>
+تُعدّ OpenTelemetry **مسار المراقبة الموصى به** — محايدة تجاه الموردين، وتعمل مع أي خلفية متوافقة مع OTLP (Grafana, Honeycomb, NewRelic، أو مجمّعك الخاص). إذا كنت تستخدم Datadog تحديدًا، فراجع دليل [تكامل Datadog](./datadog) المخصص، الذي يغطي كلًا من مسار وكيل Datadog واستيعاب OTLP من Datadog.
+</Tip>
+
 ## المتطلبات المسبقة
 
 <CardGroup cols={2}>
@@ -41,17 +45,7 @@ mode: "wide"
     <Frame>![تهيئة مجمّع OpenTelemetry](/images/crewai-otel-collector-opentelemetry.png)</Frame>
   </Tab>
   <Tab title="Datadog">
-    - **Datadog Site Domain** — مضيف OTLP لموقع Datadog الخاص بك فقط، دون بروتوكول أو مسار. يقوم CrewAI ببناء نقطة نهاية HTTPS OTLP الكاملة نيابةً عنك. استخدم المضيف المطابق لـ [موقع Datadog](https://docs.datadoghq.com/getting_started/site/) الخاص بك:
-      - `otlp.datadoghq.com` (US1)
-      - `otlp.us3.datadoghq.com` (US3)
-      - `otlp.us5.datadoghq.com` (US5)
-      - `otlp.datadoghq.eu` (EU1)
-      - `otlp.ap1.datadoghq.com` (AP1)
-    - **API Key** — مفتاح واجهة برمجة تطبيقات Datadog الخاص بك. راجع [كيفية إنشاء واحد](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys).
-
-    يصدّر تكامل Datadog **التتبعات**.
-
-    <Frame>![تهيئة مجمّع Datadog](/images/crewai-otel-collector-datadog.png)</Frame>
+    لإعداد Datadog، راجع دليل [تكامل Datadog](./datadog) المخصص — فهو يغطي كلًا من مسار وكيل Datadog (الموصى به، أرخص لحجم السجلات الكبير) واستيعاب OTLP من Datadog، مع خطوات تهيئة كاملة للمجمّع.
   </Tab>
 </Tabs>
 

docs/edge/ar/enterprise/guides/datadog.mdx

@@ -0,0 +1,295 @@
+---
+title: "تكامل Datadog"
+description: "راقب عمليات نشر CrewAI AMP المُستضافة ذاتيًا في Datadog عبر وكيل Datadog أو استيعاب OTLP من Datadog — يوفر كلا المسارين نفس الواجهات المهيكلة لاستيراد لوحة معلومات العمليات الجاهزة."
+icon: "dog"
+mode: "wide"
+---
+
+<Note>
+**الترجمة قيد التقدم** — يتم عرض المحتوى باللغة الإنجليزية.
+</Note>
+
+CrewAI ships first-class support for Datadog: two log-ingestion paths, a JSON log schema designed for cheap indexing, and a ready-made operations dashboard you can import in under five minutes.
+
+<Note>
+For vendor-neutral observability via any OTLP backend (Grafana, Honeycomb, your own collector), see [OpenTelemetry Export](./capture_telemetry_logs).
+</Note>
+
+## Choose a path
+
+CrewAI supports two log-ingestion paths to Datadog — both are first-class and produce the same structured facets that power the dashboard. Pick the one that fits your infrastructure.
+
+<Tabs>
+  <Tab title="Datadog Agent">
+    The Datadog Agent runs alongside your CrewAI containers (typically as a DaemonSet on Kubernetes) and tails their stdout. With `CREWAI_LOG_FORMAT=json` set, each log event ships as a single billable line with structured attributes.
+
+    **Setup:**
+    1. Run the Datadog Agent next to your CrewAI containers — see [Datadog's deployment docs](https://docs.datadoghq.com/agent/) for Kubernetes, ECS, or VM setup. Enable log collection (`logs_enabled: true`) and container log collection (`logs_config.container_collect_all: true`).
+    2. Set `CREWAI_LOG_FORMAT=json` as an **automation environment variable** in CrewAI AMP (open your automation → **Settings → Environment Variables**) so each log event is a single line instead of a multi-line traceback. AMP propagates the value to every container in the deployment (API + workers) — don't set it on the container or host directly. See [Enabling JSON output](#enabling-json-output) below for the AMP UI walkthrough and the [log schema reference](#log-schema-reference) for the full field contract.
+    3. Confirm logs arrive in Datadog Logs with the JSON fields parsed — see [Verify ingestion](#verify-ingestion).
+
+    **Pick this path if** you already operate Datadog Agents (e.g. for infrastructure metrics), or your log volume makes per-event ingestion cost a real concern — collapsing tracebacks into single events keeps Agent ingestion cheap at scale.
+  </Tab>
+  <Tab title="Datadog OTLP intake">
+    CrewAI AMP exports OpenTelemetry traffic directly to Datadog's OTLP endpoint with no Agent required. Logs and traces ride a single export pipeline configured in AMP's UI, using the same protocol you'd use for any other OTLP backend.
+
+    **Setup:**
+    1. In CrewAI AMP, go to **Settings → OpenTelemetry Collectors → Add Collector** and pick **Datadog**.
+    2. Configure the connection:
+       - **Datadog Site Domain** — your Datadog site's OTLP host only, no protocol or path. CrewAI builds the full HTTPS OTLP endpoint for you. Use the host that matches your [Datadog site](https://docs.datadoghq.com/getting_started/site/):
+         - `otlp.datadoghq.com` (US1)
+         - `otlp.us3.datadoghq.com` (US3)
+         - `otlp.us5.datadoghq.com` (US5)
+         - `otlp.datadoghq.eu` (EU1)
+         - `otlp.ap1.datadoghq.com` (AP1)
+       - **API Key** — your Datadog API key. See [how to create one](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys).
+    3. The Datadog template provisions **both signals at once** — when you save, AMP creates a traces collector at `/v1/traces` and a logs collector at `/v1/logs`, both sharing the same Datadog OTLP host and API key. You'll see them as two separate rows in your OTel collectors list.
+    4. *(optional)* Click **Test Connection** to verify CrewAI can reach the endpoint with the credentials you provided. Then click **Save** — both collectors are created in one step.
+
+    <Frame>![Datadog collector configuration](/images/crewai-otel-collector-datadog.png)</Frame>
+
+    **Pick this path if** you'd rather not operate a Datadog Agent, you already use OTLP for traces and want one export pipeline, or you may later want to fan out the same telemetry to other backends (Grafana, Honeycomb, etc.) without changing your application setup.
+  </Tab>
+</Tabs>
+
+Either path lands the same structured facets in Datadog (`@automation_id`, `@kickoff_id`, `@execution_id`, `@automation_name`, `@crewai_version`, `@exception.type`, `@gen_ai.*`), so the dashboard works identically with either choice.
+
+## Log schema reference
+
+<Info>
+This schema applies to the **Datadog Agent path** — stdout JSON logs produced when `CREWAI_LOG_FORMAT=json` is set. Logs delivered via the **Datadog OTLP intake** use OpenTelemetry attribute names and may differ; see [OpenTelemetry Export](./capture_telemetry_logs).
+</Info>
+
+When `CREWAI_LOG_FORMAT=json` is set, every log event is emitted as a **single JSON object per line** to stdout, with internal newlines escaped. The format is plain JSON — Datadog parses it natively, and the same payload is also consumable by Splunk, Loki, Elasticsearch, and CloudWatch without custom log pipelines.
+
+### Why JSON output
+
+<CardGroup cols={2}>
+  <Card title="Lower ingestion cost" icon="dollar-sign">
+    Most managed log backends bill per event. A Python traceback in text format is counted as one event per line — 30+ events for a single error. JSON output collapses each traceback into a single event with the stack trace as an escaped string field.
+  </Card>
+  <Card title="Structured search" icon="magnifying-glass">
+    Search by `@automation_id`, `@exception.type`, `@kickoff_id` instead of grepping free-text. Build dashboards on typed facets without parser configuration.
+  </Card>
+  <Card title="APM ↔ logs correlation" icon="link">
+    Every event carries `trace_id` and `span_id` when fired inside a recording span, so backends auto-link logs to traces.
+  </Card>
+  <Card title="Stable contract" icon="file-shield">
+    The `schema` field gates compatibility — within `v1`, fields are added but never renamed or removed.
+  </Card>
+</CardGroup>
+
+### Enabling JSON output
+
+`CREWAI_LOG_FORMAT=json` must be set as an **automation environment variable** in CrewAI AMP — it is **not** a container, host, or Docker setting. Open your automation in AMP, click the **Settings** icon, and add the variable under the **Environment Variables** section. AMP applies the value to every container in the deployment (API + workers) on the next restart. See [Update Your Crew](./update-crew) for the full UI walkthrough with screenshots.
+
+```shell
+CREWAI_LOG_FORMAT=json
+```
+
+Restart the deployment to pick up the change. Every log line on stdout from that point on is a single JSON object.
+
+<Note>
+  The default value is `text`, which preserves the legacy human-readable line format byte-for-byte. Setting any value other than `json` falls back to text mode. There is no migration step — the variable is read at process start and the format switches immediately.
+</Note>
+
+### Example events
+
+A single info-level log inside an active automation kickoff:
+
+```json
+{
+  "schema": "v1",
+  "ts": "2026-06-17T16:14:23.482914Z",
+  "level": "INFO",
+  "logger": "crewai_enterprise.utilities.pii_redaction",
+  "crewai_version": "1.14.7",
+  "msg": "PII tracking state reset (engines preserved)",
+  "automation_id": "12",
+  "task_id": "0843a930-b306-464b-89c8-bfafa78cc711",
+  "kickoff_id": "0843a930-b306-464b-89c8-bfafa78cc711",
+  "execution_id": "0843a930-b306-464b-89c8-bfafa78cc711",
+  "automation_name": "research_flow"
+}
+```
+
+An error with a Python exception is collapsed into a single event with the traceback as a string:
+
+```json
+{
+  "schema": "v1",
+  "ts": "2026-06-17T16:14:31.218450Z",
+  "level": "ERROR",
+  "logger": "api.tasks.flow_run_task",
+  "crewai_version": "1.14.7",
+  "msg": "Flow execution failed",
+  "automation_id": "12",
+  "kickoff_id": "0843a930-b306-464b-89c8-bfafa78cc711",
+  "execution_id": "0843a930-b306-464b-89c8-bfafa78cc711",
+  "automation_name": "research_flow",
+  "exception": {
+    "type": "ValueError",
+    "message": "Topic cannot be empty",
+    "stacktrace": "Traceback (most recent call last):\n  File \"/app/flow.py\", line 42, in summarize\n    ...\nValueError: Topic cannot be empty\n"
+  }
+}
+```
+
+The same error in legacy text mode would have produced ~25 separate log events (one per traceback line) — all of which the backend would bill and index individually.
+
+### Schema v1 fields
+
+Within the `v1` schema, fields are only added, never renamed or removed. New fields will appear as soon as a deployment is upgraded.
+
+| Field | Type | Always present | Source |
+|-------|------|----------------|--------|
+| `schema` | string | Yes | Constant `"v1"`. Increment indicates a breaking schema change. |
+| `ts` | string (ISO-8601 UTC, microseconds) | Yes | Record creation time, e.g. `2026-06-17T16:14:23.482914Z`. |
+| `level` | string | Yes | Python log level name: `DEBUG` / `INFO` / `WARNING` / `ERROR` / `CRITICAL`. |
+| `logger` | string | Yes | Dotted logger name, e.g. `api.tasks.flow_run_task`. |
+| `crewai_version` | string | Yes (when `crewai` package metadata is resolvable) | Installed `crewai` package version, e.g. `"1.14.7"`. |
+| `msg` | string | Yes | Rendered log message (after `%`-formatting / `{}`-formatting). |
+| `automation_id` | string | When `CREWAI_PLUS_ID` env var is set | Numeric deployment ID (AMP provisions this on every container). |
+| `task_id` | string | On Celery worker logs | Celery task UUID, or `"no-task"` for non-task contexts. |
+| `kickoff_id` | string | Inside an automation kickoff | UUID of the current kickoff. |
+| `execution_id` | string | Inside an automation kickoff | UUID of the current sub-execution. Equal to `kickoff_id` at the top level; differs for nested flow methods that spawn sub-executions. |
+| `automation_name` | string | Inside an automation kickoff | Human-readable automation/flow name, e.g. `"research_flow"`. |
+| `trace_id` | string (32-hex) | Inside a recording OpenTelemetry span | Hex trace ID. Omitted when no span is active. |
+| `span_id` | string (16-hex) | Inside a recording OpenTelemetry span | Hex span ID. Omitted when no span is active. |
+| `exception` | object | When the log record has `exc_info` | `{type, message, stacktrace}` — full traceback as a single escaped string. |
+
+<Tip>
+  Any additional `extra={...}` kwargs passed to a logger call appear as top-level JSON fields verbatim. Reserved field names above always win to keep the schema stable.
+</Tip>
+
+### Stability promise
+
+The `schema` field declares the contract. Within `v1`, CrewAI commits to:
+
+- **Never removing a field** that customers may have built queries or dashboards against.
+- **Never renaming a field** in place — renames happen via a schema bump (e.g. `v2`), with the old name kept as a deprecated alias for at least one release cycle.
+- **Adding new fields** at any time. Consumers should ignore unknown top-level keys.
+
+When a `v2` is introduced, both the `schema` field and the migration guide will be published in advance, and `v1` will continue to be emitted for one release cycle so dashboards and queries have time to migrate.
+
+## Prerequisite: promote facets
+
+Datadog auto-discovers fields the first time it sees them but doesn't make them queryable in widgets until they're promoted to **facets**. This is a one-time setup in your Datadog account.
+
+<Steps>
+  <Step title="Search for a CrewAI log">
+    Open [Logs Explorer](https://app.datadoghq.com/logs) and search `service:crewai*`. You should see at least one log event.
+  </Step>
+  <Step title="Promote each field">
+    Click any log entry to open the right-hand details panel. For each field below, hover the field name → click the gear icon → **Create facet**.
+
+    - `automation_id`, `automation_name`, `execution_id`, `kickoff_id`, `task_id`
+    - `crewai_version`, `model_id`
+    - `exception.type`, `exception.message`
+
+    Skip any field that already shows a star icon next to its name — that means it's already a facet. The `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, and `gen_ai.request.model` facets are typically promoted automatically by Datadog's LLM Observability auto-discovery, but verify they exist before importing the dashboard.
+  </Step>
+</Steps>
+
+## Import the dashboard
+
+<Steps>
+  <Step title="Download the dashboard JSON">
+    Save [`datadog_dashboard.json`](https://raw.githubusercontent.com/crewAIInc/crewAI/main/docs/edge/en/enterprise/guides/datadog_dashboard.json) to your machine.
+  </Step>
+  <Step title="Open the import dialog in Datadog">
+    Navigate to **Dashboards → New Dashboard**. Click the **gear icon** in the top right of the empty dashboard and select **Import Dashboard JSON**.
+  </Step>
+  <Step title="Paste or upload the JSON">
+    Paste the contents of `datadog_dashboard.json` into the import dialog (or drag the file in). Click **Import**.
+
+    Datadog creates the dashboard immediately and lands you on it. The first load may show empty widgets for a few seconds while queries execute against the time range.
+  </Step>
+</Steps>
+
+<Tip>
+  Datadog's [Dashboard API](https://docs.datadoghq.com/api/latest/dashboards/#create-a-new-dashboard) accepts the same JSON via `POST /api/v1/dashboard`. Use it if you manage dashboards through Terraform, Pulumi, or CI.
+</Tip>
+
+## What you get
+
+The dashboard is organized into four sections plus a placeholder for a custom drill-down widget:
+
+| Section | Widgets | Useful for |
+|---------|---------|------------|
+| **Header** | Total Executions · Error Rate (%) · Active Automations · CrewAI Versions in Use | At-a-glance health for the last hour. Error Rate is conditionally formatted (green ≤ 5%, yellow ≤ 10%, red > 10%). |
+| **Throughput** | Executions per Hour by Automation (top 10, stacked bars) | Spotting traffic shifts, surfacing busy automations, validating that a rollout didn't change baseline volume. |
+| **Errors** | Errors by Exception Type (top 5, stacked bars) · Top Exception Types by Count (toplist) | Triaging failures — which exception types are spiking, which automations they're hitting. |
+| **Cost** | Total Tokens per Hour by Model (input + output, stacked area) | Tracking LLM token spend by model. Useful for catching cost regressions when an automation switches model or starts looping. |
+| **Drill-Down** | _(empty placeholder)_ | See [Customization](#customize) for adding a recent-errors log stream here. |
+
+Three template variables at the top of the dashboard re-scope every widget at once:
+
+- **`$automation`** — filter to a single automation by name.
+- **`$version`** — filter to a single `crewai` SDK version (useful for comparing pre- and post-upgrade behavior).
+- **`$service`** — filter to a specific Datadog `service` tag (useful when multiple CrewAI deployments share one Datadog account).
+
+## Verify ingestion
+
+Open [Logs Explorer](https://app.datadoghq.com/logs) and run a query that matches your ingestion path:
+
+<Tabs>
+  <Tab title="Datadog Agent">
+    Search `service:crewai* @schema:v1`. You should see structured logs with the JSON fields parsed into Datadog facets. Pick a recent event and verify it has `@automation_id`, `@kickoff_id`, `@execution_id`, `@crewai_version`, and (when running inside a span) `@trace_id` / `@span_id` populated.
+
+    If nothing appears, confirm `CREWAI_LOG_FORMAT=json` is set under your automation's **Environment Variables** in AMP, the deployment was restarted after the change, and the Datadog Agent is tailing container stdout.
+  </Tab>
+  <Tab title="Datadog OTLP intake">
+    Search `source:otlp service:crewai*`. OTLP attributes land with their OpenTelemetry names (`automation_id`, `crewai.kickoff.id`, etc.) rather than the stdout JSON keys, but they map to the same dashboard facets after [facet promotion](#prerequisite-promote-facets).
+
+    If nothing appears, verify the collector endpoint is correct (`/v1/logs` for logs, `/v1/traces` for traces) and **Test Connection** succeeded when the collector was saved.
+  </Tab>
+</Tabs>
+
+## Customize
+
+The dashboard ships with deliberate gaps so you can extend it without uninstalling and re-importing.
+
+### Add a Recent Errors log stream
+
+The **Drill-Down** section is intentionally empty. Add a Log Stream widget to it for an inline view of recent failures:
+
+1. Edit the dashboard and click **+ Add Widgets** inside the Drill-Down group.
+2. Drag in a **Log Stream** widget.
+3. Set the filter query to `status:error $automation $version $service`.
+4. Choose columns: `@timestamp`, `@automation_name`, `@exception.type`, `@exception.message`, `@execution_id`.
+5. Sort by most recent, limit to 25 entries.
+
+Clicking any row jumps to Logs Explorer with the same filter pre-applied.
+
+### Add p95 latency
+
+Logs don't include execution duration by default. Two ways to add a latency widget:
+
+- **From APM traces** — if you also export OTLP traces to Datadog, add a Timeseries widget with data source **Traces**, query `service:crewai*`, aggregation `p95 of @duration`. Datadog APM auto-tracks span duration.
+- **From metric extraction** — extract a `flow.duration_ms` metric from logs via [Datadog's log-to-metric pipeline](https://docs.datadoghq.com/logs/log_configuration/logs_to_metrics/), then chart it like any other metric. Useful if you don't run APM.
+
+### Re-scope to multiple deployments
+
+The `$service` template variable defaults to `*` and will catch every CrewAI deployment in your Datadog account. Change the default to a specific service name in **Configure → Template Variables** if you want the dashboard to focus on one deployment by default.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| All widgets show "No data" | Facets aren't promoted | Re-do the [Promote facets](#prerequisite-promote-facets) step. Datadog won't query against an un-promoted field. |
+| Error Rate widget shows `NaN` | No executions in the time window | Either no traffic, or `@execution_id` isn't faceted. Expand the time range and re-check facets. |
+| Throughput chart is flat at the same value | Logs aren't reaching Datadog | Search `service:crewai*` in Logs Explorer. If nothing shows, verify the Datadog Agent is running (Agent path) or the OTel collector endpoint is correct (OTLP path). |
+| `crewai_version` shows fewer values than expected | Some containers predate the structured-logs work | The `crewai_version` field was added alongside JSON output. Older deployments running text mode (or older AMP builds) won't emit it. Upgrade those deployments to pick up the field. See the [log schema reference](#log-schema-reference) for the full field contract. |
+| Template variables don't filter widgets | The widget's filter line doesn't reference the template variable | Edit the widget and confirm the search includes `$automation $version $service`. |
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="OpenTelemetry Export" icon="magnifying-glass-chart" href="./capture_telemetry_logs">
+    Vendor-neutral observability for non-Datadog stacks (Grafana, Honeycomb, your own collector) — or as a Datadog complement when you want to fan out telemetry to multiple backends.
+  </Card>
+  <Card title="Datadog Log Search Syntax" icon="magnifying-glass" href="https://docs.datadoghq.com/logs/explorer/search_syntax/">
+    Reference for customizing widget queries against the structured facets above.
+  </Card>
+</CardGroup>

docs/edge/en/changelog.mdx

@@ -4,6 +4,27 @@ description: "Product updates, improvements, and bug fixes for CrewAI"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="Jun 18, 2026">
+  ## v1.14.8a2
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.8a2)
+
+  ## What's Changed
+
+  ### Features
+  - Add single agent action to Flow definitions
+  - Validate flow CEL expressions at definition load time
+
+  ### Documentation
+  - Add Datadog integration guide with importable operations dashboard
+  - Update snapshot and changelog for v1.14.8a1
+
+  ## Contributors
+
+  @joaomdmoura, @lucasgomide, @vinibrsl
+
+</Update>
+
 <Update label="Jun 18, 2026">
   ## v1.14.8a1
 

docs/edge/en/concepts/tools.mdx

@@ -39,6 +39,7 @@ The Enterprise Tools Repository includes:
 - **Error Handling**: Incorporates robust error handling mechanisms to ensure smooth operation.
 - **Caching Mechanism**: Features intelligent caching to optimize performance and reduce redundant operations.
 - **Asynchronous Support**: Handles both synchronous and asynchronous tools, enabling non-blocking operations.
+- **Typed Outputs**: Uses optional Pydantic models to give agents clear JSON fields while direct Python calls still receive the tool's normal return value.
 
 ## Using CrewAI Tools
 
@@ -184,6 +185,55 @@ class MyCustomTool(BaseTool):
         return "Tool's result"
 ```
 
+### Typed Tool Outputs
+
+When a tool returns structured data, define a Pydantic output model. This gives the agent field names it can trust, such as `sku`, `quantity`, or `needs_reorder`.
+
+Direct Python calls still receive the value your tool returns. When an agent uses the tool, CrewAI sends the agent a JSON string based on the output model.
+
+```python Code
+from crewai.tools import BaseTool
+from pydantic import BaseModel
+
+class InventoryResult(BaseModel):
+    sku: str
+    quantity: int
+    needs_reorder: bool
+
+class InventoryTool(BaseTool):
+    name: str = "Inventory Check"
+    description: str = "Checks current stock for a product SKU."
+
+    def _run(self, sku: str) -> InventoryResult:
+        quantity = {"SKU-123": 14, "SKU-456": 0}.get(sku, 0)
+        return InventoryResult(sku=sku, quantity=quantity, needs_reorder=quantity < 5)
+
+tool = InventoryTool()
+
+# Direct calls receive the raw Pydantic object.
+result = tool.run(sku="SKU-123")
+print(result.quantity)
+```
+
+To send Markdown or another short text format to the agent, override `format_output_for_agent`. Direct calls to `tool.run(...)` still return the normal Python value.
+
+```python Code
+class InventoryTool(BaseTool):
+    name: str = "Inventory Check"
+    description: str = "Checks current stock for a product SKU."
+
+    def _run(self, sku: str) -> InventoryResult:
+        quantity = {"SKU-123": 14, "SKU-456": 0}.get(sku, 0)
+        return InventoryResult(sku=sku, quantity=quantity, needs_reorder=quantity < 5)
+
+    def format_output_for_agent(self, raw_result: object) -> str:
+        result = InventoryResult.model_validate(raw_result)
+        status = "reorder needed" if result.needs_reorder else "stock is healthy"
+        return f"{result.sku}: {result.quantity} units. {status}."
+```
+
+If you do not override `format_output_for_agent`, typed outputs are sent to the agent as JSON. Plain string results work as before.
+
 ## Asynchronous Tool Support
 
 CrewAI supports asynchronous tools, allowing you to implement tools that perform non-blocking operations like network requests, file I/O, or other async operations without blocking the main execution thread.

docs/edge/en/enterprise/features/merged-step-card.mdx

@@ -0,0 +1,87 @@
+---
+title: One Card per Step
+description: "Each step on the Studio canvas is a single card that combines the task and the agent that performs it."
+icon: "layer-group"
+mode: "wide"
+---
+
+{/* CLEANUP: This <Note> banner is the only time-bound content on the page. After the feature ships (Wednesday, June 24th 2026), delete the banner below — the rest of the page is evergreen present-tense docs and needs no other edits. */}
+<Note>
+  **Rolling out Wednesday, June 24th.** The Studio canvas is moving to one card per step instead of separate task and agent nodes, to streamline the canvas as we add new functionality soon. Your existing automations keep working with no changes needed — every task and agent setting is still available, just organized onto a single card.
+</Note>
+
+## Overview
+
+On the Studio canvas, each step of work is represented by a **single card**. The card combines two things that used to live in separate nodes:
+
+- **The task** — what to do (name, description, expected output, and response format).
+- **The agent** — who does it (the assigned agent, its model, and its tools).
+
+An agent isn't an independent participant in your workflow — it's an attribute of the task: *which agent performs this work.* Putting the task and its agent on one card makes that relationship explicit and turns your automation into a single, left-to-right chain of work units that's easier to read at a glance.
+
+<Frame caption="One card per step: the task with its assigned agent summarized in the footer.">
+  ![Merged step cards on the canvas](/images/enterprise/merged-step-card-canvas.png)
+</Frame>
+
+## On the canvas
+
+Each collapsed card shows:
+
+- The **task name and description** at the top.
+- A **footer summarizing the assigned agent** — avatar, name, model, and tools.
+
+There's no separate agent node and no vertical agent → task edge. Your steps connect directly to one another in the order they run.
+
+## In the editor
+
+Open a card to edit it. The expanded view is the same card in a detailed state — not a different screen — organized into two clearly labeled sections.
+
+<Frame caption="The expanded editor: the task section open, the agent summarized below it.">
+  ![Expanded step editor](/images/enterprise/merged-step-card-editor.png)
+</Frame>
+
+### The task — what to do
+
+Open by default, since this is what you usually edit:
+
+- **Name**
+- **Description**
+- **Expected Output**
+- **Response Format** — surfaced here because it controls exactly what downstream steps (such as routing) read from this step.
+
+### The agent — who does it
+
+The assigned agent is shown as a summary — **name, model, and tools inline**. Its deeper configuration is preserved behind two disclosures:
+
+- **Role, goal & backstory**
+- **Agent settings** — reasoning, max reasoning attempts, allow delegation, max iterations, and LLM settings.
+
+<Tip>
+  An agent's full configuration — Role, Goal, Backstory, Model, Tools, LLM Settings, and the complete Agent Settings block — lives behind the **Role, goal & backstory** and **Agent settings** disclosures, organized by how often you edit it.
+</Tip>
+
+## Swapping vs. editing the agent
+
+There are two distinct ways to work with the agent on a card, and they do different things:
+
+- **Swap** reassigns *which* agent performs this task. Use the **Swap** control to pick a different agent from this project, choose one from your Agent Repository, or create a new agent. This is scoped to the task.
+- **Editing** the agent — opening **Role, goal & backstory** or **Agent settings** — changes the agent *itself*.
+
+<Frame caption="Swap changes which agent performs the task.">
+  ![Swap agent panel](/images/enterprise/merged-step-card-swap-agent.png)
+</Frame>
+
+<Warning>
+  **Agents are reusable and shared.** The same agent can perform more than one task across your project. Editing an agent's role, backstory, or settings updates that agent **everywhere it's used** — not just on the card you opened. If you want a change to apply to only one step, **Swap** in a different agent instead of editing the shared one.
+</Warning>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Crew Studio" href="/en/enterprise/features/crew-studio" icon="pencil">
+    Build automations with AI assistance and a visual editor.
+  </Card>
+  <Card title="Agent Repositories" href="/en/enterprise/features/agent-repositories" icon="users">
+    Manage and reuse agents across your automations.
+  </Card>
+</CardGroup>

docs/edge/en/enterprise/guides/capture_telemetry_logs.mdx

@@ -9,6 +9,10 @@ CrewAI AMP can export OpenTelemetry **traces** and **logs** from your deployment
 
 Telemetry data follows the [OpenTelemetry GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) plus additional CrewAI-specific attributes.
 
+<Tip>
+OpenTelemetry is the **recommended observability path** — vendor-neutral, works with any OTLP-compatible backend (Grafana, Honeycomb, NewRelic, your own collector). If you specifically use Datadog, see the dedicated [Datadog Integration](./datadog) guide which covers both the Datadog Agent path and Datadog's OTLP intake.
+</Tip>
+
 ## Prerequisites
 
 <CardGroup cols={2}>
@@ -41,17 +45,7 @@ Telemetry data follows the [OpenTelemetry GenAI semantic conventions](https://op
     <Frame>![OpenTelemetry collector configuration](/images/crewai-otel-collector-opentelemetry.png)</Frame>
   </Tab>
   <Tab title="Datadog">
-    - **Datadog Site Domain** — Your Datadog site's OTLP host only, with no protocol or path. CrewAI builds the full HTTPS OTLP endpoint for you. Use the host that matches your [Datadog site](https://docs.datadoghq.com/getting_started/site/):
-      - `otlp.datadoghq.com` (US1)
-      - `otlp.us3.datadoghq.com` (US3)
-      - `otlp.us5.datadoghq.com` (US5)
-      - `otlp.datadoghq.eu` (EU1)
-      - `otlp.ap1.datadoghq.com` (AP1)
-    - **API Key** — Your Datadog API key. See [how to create one](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys).
-
-    The Datadog integration exports **traces**.
-
-    <Frame>![Datadog collector configuration](/images/crewai-otel-collector-datadog.png)</Frame>
+    For Datadog setup, see the dedicated [Datadog Integration](./datadog) guide — it covers both the Datadog Agent path (recommended, cheaper for log volume) and Datadog's OTLP intake with full collector configuration steps.
   </Tab>
 </Tabs>
 

docs/edge/en/enterprise/guides/datadog.mdx

@@ -0,0 +1,291 @@
+---
+title: "Datadog Integration"
+description: "Monitor self-hosted CrewAI AMP deployments in Datadog via the Datadog Agent or Datadog's OTLP intake — either path lands the same structured facets so you can import the ready-made operations dashboard."
+icon: "dog"
+mode: "wide"
+---
+
+CrewAI ships first-class support for Datadog: two log-ingestion paths, a JSON log schema designed for cheap indexing, and a ready-made operations dashboard you can import in under five minutes.
+
+<Note>
+For vendor-neutral observability via any OTLP backend (Grafana, Honeycomb, your own collector), see [OpenTelemetry Export](./capture_telemetry_logs).
+</Note>
+
+## Choose a path
+
+CrewAI supports two log-ingestion paths to Datadog — both are first-class and produce the same structured facets that power the dashboard. Pick the one that fits your infrastructure.
+
+<Tabs>
+  <Tab title="Datadog Agent">
+    The Datadog Agent runs alongside your CrewAI containers (typically as a DaemonSet on Kubernetes) and tails their stdout. With `CREWAI_LOG_FORMAT=json` set, each log event ships as a single billable line with structured attributes.
+
+    **Setup:**
+    1. Run the Datadog Agent next to your CrewAI containers — see [Datadog's deployment docs](https://docs.datadoghq.com/agent/) for Kubernetes, ECS, or VM setup. Enable log collection (`logs_enabled: true`) and container log collection (`logs_config.container_collect_all: true`).
+    2. Set `CREWAI_LOG_FORMAT=json` as an **automation environment variable** in CrewAI AMP (open your automation → **Settings → Environment Variables**) so each log event is a single line instead of a multi-line traceback. AMP propagates the value to every container in the deployment (API + workers) — don't set it on the container or host directly. See [Enabling JSON output](#enabling-json-output) below for the AMP UI walkthrough and the [log schema reference](#log-schema-reference) for the full field contract.
+    3. Confirm logs arrive in Datadog Logs with the JSON fields parsed — see [Verify ingestion](#verify-ingestion).
+
+    **Pick this path if** you already operate Datadog Agents (e.g. for infrastructure metrics), or your log volume makes per-event ingestion cost a real concern — collapsing tracebacks into single events keeps Agent ingestion cheap at scale.
+  </Tab>
+  <Tab title="Datadog OTLP intake">
+    CrewAI AMP exports OpenTelemetry traffic directly to Datadog's OTLP endpoint with no Agent required. Logs and traces ride a single export pipeline configured in AMP's UI, using the same protocol you'd use for any other OTLP backend.
+
+    **Setup:**
+    1. In CrewAI AMP, go to **Settings → OpenTelemetry Collectors → Add Collector** and pick **Datadog**.
+    2. Configure the connection:
+       - **Datadog Site Domain** — your Datadog site's OTLP host only, no protocol or path. CrewAI builds the full HTTPS OTLP endpoint for you. Use the host that matches your [Datadog site](https://docs.datadoghq.com/getting_started/site/):
+         - `otlp.datadoghq.com` (US1)
+         - `otlp.us3.datadoghq.com` (US3)
+         - `otlp.us5.datadoghq.com` (US5)
+         - `otlp.datadoghq.eu` (EU1)
+         - `otlp.ap1.datadoghq.com` (AP1)
+       - **API Key** — your Datadog API key. See [how to create one](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys).
+    3. The Datadog template provisions **both signals at once** — when you save, AMP creates a traces collector at `/v1/traces` and a logs collector at `/v1/logs`, both sharing the same Datadog OTLP host and API key. You'll see them as two separate rows in your OTel collectors list.
+    4. *(optional)* Click **Test Connection** to verify CrewAI can reach the endpoint with the credentials you provided. Then click **Save** — both collectors are created in one step.
+
+    <Frame>![Datadog collector configuration](/images/crewai-otel-collector-datadog.png)</Frame>
+
+    **Pick this path if** you'd rather not operate a Datadog Agent, you already use OTLP for traces and want one export pipeline, or you may later want to fan out the same telemetry to other backends (Grafana, Honeycomb, etc.) without changing your application setup.
+  </Tab>
+</Tabs>
+
+Either path lands the same structured facets in Datadog (`@automation_id`, `@kickoff_id`, `@execution_id`, `@automation_name`, `@crewai_version`, `@exception.type`, `@gen_ai.*`), so the dashboard works identically with either choice.
+
+## Log schema reference
+
+<Info>
+This schema applies to the **Datadog Agent path** — stdout JSON logs produced when `CREWAI_LOG_FORMAT=json` is set. Logs delivered via the **Datadog OTLP intake** use OpenTelemetry attribute names and may differ; see [OpenTelemetry Export](./capture_telemetry_logs).
+</Info>
+
+When `CREWAI_LOG_FORMAT=json` is set, every log event is emitted as a **single JSON object per line** to stdout, with internal newlines escaped. The format is plain JSON — Datadog parses it natively, and the same payload is also consumable by Splunk, Loki, Elasticsearch, and CloudWatch without custom log pipelines.
+
+### Why JSON output
+
+<CardGroup cols={2}>
+  <Card title="Lower ingestion cost" icon="dollar-sign">
+    Most managed log backends bill per event. A Python traceback in text format is counted as one event per line — 30+ events for a single error. JSON output collapses each traceback into a single event with the stack trace as an escaped string field.
+  </Card>
+  <Card title="Structured search" icon="magnifying-glass">
+    Search by `@automation_id`, `@exception.type`, `@kickoff_id` instead of grepping free-text. Build dashboards on typed facets without parser configuration.
+  </Card>
+  <Card title="APM ↔ logs correlation" icon="link">
+    Every event carries `trace_id` and `span_id` when fired inside a recording span, so backends auto-link logs to traces.
+  </Card>
+  <Card title="Stable contract" icon="file-shield">
+    The `schema` field gates compatibility — within `v1`, fields are added but never renamed or removed.
+  </Card>
+</CardGroup>
+
+### Enabling JSON output
+
+`CREWAI_LOG_FORMAT=json` must be set as an **automation environment variable** in CrewAI AMP — it is **not** a container, host, or Docker setting. Open your automation in AMP, click the **Settings** icon, and add the variable under the **Environment Variables** section. AMP applies the value to every container in the deployment (API + workers) on the next restart. See [Update Your Crew](./update-crew) for the full UI walkthrough with screenshots.
+
+```shell
+CREWAI_LOG_FORMAT=json
+```
+
+Restart the deployment to pick up the change. Every log line on stdout from that point on is a single JSON object.
+
+<Note>
+  The default value is `text`, which preserves the legacy human-readable line format byte-for-byte. Setting any value other than `json` falls back to text mode. There is no migration step — the variable is read at process start and the format switches immediately.
+</Note>
+
+### Example events
+
+A single info-level log inside an active automation kickoff:
+
+```json
+{
+  "schema": "v1",
+  "ts": "2026-06-17T16:14:23.482914Z",
+  "level": "INFO",
+  "logger": "crewai_enterprise.utilities.pii_redaction",
+  "crewai_version": "1.14.7",
+  "msg": "PII tracking state reset (engines preserved)",
+  "automation_id": "12",
+  "task_id": "0843a930-b306-464b-89c8-bfafa78cc711",
+  "kickoff_id": "0843a930-b306-464b-89c8-bfafa78cc711",
+  "execution_id": "0843a930-b306-464b-89c8-bfafa78cc711",
+  "automation_name": "research_flow"
+}
+```
+
+An error with a Python exception is collapsed into a single event with the traceback as a string:
+
+```json
+{
+  "schema": "v1",
+  "ts": "2026-06-17T16:14:31.218450Z",
+  "level": "ERROR",
+  "logger": "api.tasks.flow_run_task",
+  "crewai_version": "1.14.7",
+  "msg": "Flow execution failed",
+  "automation_id": "12",
+  "kickoff_id": "0843a930-b306-464b-89c8-bfafa78cc711",
+  "execution_id": "0843a930-b306-464b-89c8-bfafa78cc711",
+  "automation_name": "research_flow",
+  "exception": {
+    "type": "ValueError",
+    "message": "Topic cannot be empty",
+    "stacktrace": "Traceback (most recent call last):\n  File \"/app/flow.py\", line 42, in summarize\n    ...\nValueError: Topic cannot be empty\n"
+  }
+}
+```
+
+The same error in legacy text mode would have produced ~25 separate log events (one per traceback line) — all of which the backend would bill and index individually.
+
+### Schema v1 fields
+
+Within the `v1` schema, fields are only added, never renamed or removed. New fields will appear as soon as a deployment is upgraded.
+
+| Field | Type | Always present | Source |
+|-------|------|----------------|--------|
+| `schema` | string | Yes | Constant `"v1"`. Increment indicates a breaking schema change. |
+| `ts` | string (ISO-8601 UTC, microseconds) | Yes | Record creation time, e.g. `2026-06-17T16:14:23.482914Z`. |
+| `level` | string | Yes | Python log level name: `DEBUG` / `INFO` / `WARNING` / `ERROR` / `CRITICAL`. |
+| `logger` | string | Yes | Dotted logger name, e.g. `api.tasks.flow_run_task`. |
+| `crewai_version` | string | Yes (when `crewai` package metadata is resolvable) | Installed `crewai` package version, e.g. `"1.14.7"`. |
+| `msg` | string | Yes | Rendered log message (after `%`-formatting / `{}`-formatting). |
+| `automation_id` | string | When `CREWAI_PLUS_ID` env var is set | Numeric deployment ID (AMP provisions this on every container). |
+| `task_id` | string | On Celery worker logs | Celery task UUID, or `"no-task"` for non-task contexts. |
+| `kickoff_id` | string | Inside an automation kickoff | UUID of the current kickoff. |
+| `execution_id` | string | Inside an automation kickoff | UUID of the current sub-execution. Equal to `kickoff_id` at the top level; differs for nested flow methods that spawn sub-executions. |
+| `automation_name` | string | Inside an automation kickoff | Human-readable automation/flow name, e.g. `"research_flow"`. |
+| `trace_id` | string (32-hex) | Inside a recording OpenTelemetry span | Hex trace ID. Omitted when no span is active. |
+| `span_id` | string (16-hex) | Inside a recording OpenTelemetry span | Hex span ID. Omitted when no span is active. |
+| `exception` | object | When the log record has `exc_info` | `{type, message, stacktrace}` — full traceback as a single escaped string. |
+
+<Tip>
+  Any additional `extra={...}` kwargs passed to a logger call appear as top-level JSON fields verbatim. Reserved field names above always win to keep the schema stable.
+</Tip>
+
+### Stability promise
+
+The `schema` field declares the contract. Within `v1`, CrewAI commits to:
+
+- **Never removing a field** that customers may have built queries or dashboards against.
+- **Never renaming a field** in place — renames happen via a schema bump (e.g. `v2`), with the old name kept as a deprecated alias for at least one release cycle.
+- **Adding new fields** at any time. Consumers should ignore unknown top-level keys.
+
+When a `v2` is introduced, both the `schema` field and the migration guide will be published in advance, and `v1` will continue to be emitted for one release cycle so dashboards and queries have time to migrate.
+
+## Prerequisite: promote facets
+
+Datadog auto-discovers fields the first time it sees them but doesn't make them queryable in widgets until they're promoted to **facets**. This is a one-time setup in your Datadog account.
+
+<Steps>
+  <Step title="Search for a CrewAI log">
+    Open [Logs Explorer](https://app.datadoghq.com/logs) and search `service:crewai*`. You should see at least one log event.
+  </Step>
+  <Step title="Promote each field">
+    Click any log entry to open the right-hand details panel. For each field below, hover the field name → click the gear icon → **Create facet**.
+
+    - `automation_id`, `automation_name`, `execution_id`, `kickoff_id`, `task_id`
+    - `crewai_version`, `model_id`
+    - `exception.type`, `exception.message`
+
+    Skip any field that already shows a star icon next to its name — that means it's already a facet. The `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, and `gen_ai.request.model` facets are typically promoted automatically by Datadog's LLM Observability auto-discovery, but verify they exist before importing the dashboard.
+  </Step>
+</Steps>
+
+## Import the dashboard
+
+<Steps>
+  <Step title="Download the dashboard JSON">
+    Save [`datadog_dashboard.json`](https://raw.githubusercontent.com/crewAIInc/crewAI/main/docs/edge/en/enterprise/guides/datadog_dashboard.json) to your machine.
+  </Step>
+  <Step title="Open the import dialog in Datadog">
+    Navigate to **Dashboards → New Dashboard**. Click the **gear icon** in the top right of the empty dashboard and select **Import Dashboard JSON**.
+  </Step>
+  <Step title="Paste or upload the JSON">
+    Paste the contents of `datadog_dashboard.json` into the import dialog (or drag the file in). Click **Import**.
+
+    Datadog creates the dashboard immediately and lands you on it. The first load may show empty widgets for a few seconds while queries execute against the time range.
+  </Step>
+</Steps>
+
+<Tip>
+  Datadog's [Dashboard API](https://docs.datadoghq.com/api/latest/dashboards/#create-a-new-dashboard) accepts the same JSON via `POST /api/v1/dashboard`. Use it if you manage dashboards through Terraform, Pulumi, or CI.
+</Tip>
+
+## What you get
+
+The dashboard is organized into four sections plus a placeholder for a custom drill-down widget:
+
+| Section | Widgets | Useful for |
+|---------|---------|------------|
+| **Header** | Total Executions · Error Rate (%) · Active Automations · CrewAI Versions in Use | At-a-glance health for the last hour. Error Rate is conditionally formatted (green ≤ 5%, yellow ≤ 10%, red > 10%). |
+| **Throughput** | Executions per Hour by Automation (top 10, stacked bars) | Spotting traffic shifts, surfacing busy automations, validating that a rollout didn't change baseline volume. |
+| **Errors** | Errors by Exception Type (top 5, stacked bars) · Top Exception Types by Count (toplist) | Triaging failures — which exception types are spiking, which automations they're hitting. |
+| **Cost** | Total Tokens per Hour by Model (input + output, stacked area) | Tracking LLM token spend by model. Useful for catching cost regressions when an automation switches model or starts looping. |
+| **Drill-Down** | _(empty placeholder)_ | See [Customization](#customize) for adding a recent-errors log stream here. |
+
+Three template variables at the top of the dashboard re-scope every widget at once:
+
+- **`$automation`** — filter to a single automation by name.
+- **`$version`** — filter to a single `crewai` SDK version (useful for comparing pre- and post-upgrade behavior).
+- **`$service`** — filter to a specific Datadog `service` tag (useful when multiple CrewAI deployments share one Datadog account).
+
+## Verify ingestion
+
+Open [Logs Explorer](https://app.datadoghq.com/logs) and run a query that matches your ingestion path:
+
+<Tabs>
+  <Tab title="Datadog Agent">
+    Search `service:crewai* @schema:v1`. You should see structured logs with the JSON fields parsed into Datadog facets. Pick a recent event and verify it has `@automation_id`, `@kickoff_id`, `@execution_id`, `@crewai_version`, and (when running inside a span) `@trace_id` / `@span_id` populated.
+
+    If nothing appears, confirm `CREWAI_LOG_FORMAT=json` is set under your automation's **Environment Variables** in AMP, the deployment was restarted after the change, and the Datadog Agent is tailing container stdout.
+  </Tab>
+  <Tab title="Datadog OTLP intake">
+    Search `source:otlp service:crewai*`. OTLP attributes land with their OpenTelemetry names (`automation_id`, `crewai.kickoff.id`, etc.) rather than the stdout JSON keys, but they map to the same dashboard facets after [facet promotion](#prerequisite-promote-facets).
+
+    If nothing appears, verify the collector endpoint is correct (`/v1/logs` for logs, `/v1/traces` for traces) and **Test Connection** succeeded when the collector was saved.
+  </Tab>
+</Tabs>
+
+## Customize
+
+The dashboard ships with deliberate gaps so you can extend it without uninstalling and re-importing.
+
+### Add a Recent Errors log stream
+
+The **Drill-Down** section is intentionally empty. Add a Log Stream widget to it for an inline view of recent failures:
+
+1. Edit the dashboard and click **+ Add Widgets** inside the Drill-Down group.
+2. Drag in a **Log Stream** widget.
+3. Set the filter query to `status:error $automation $version $service`.
+4. Choose columns: `@timestamp`, `@automation_name`, `@exception.type`, `@exception.message`, `@execution_id`.
+5. Sort by most recent, limit to 25 entries.
+
+Clicking any row jumps to Logs Explorer with the same filter pre-applied.
+
+### Add p95 latency
+
+Logs don't include execution duration by default. Two ways to add a latency widget:
+
+- **From APM traces** — if you also export OTLP traces to Datadog, add a Timeseries widget with data source **Traces**, query `service:crewai*`, aggregation `p95 of @duration`. Datadog APM auto-tracks span duration.
+- **From metric extraction** — extract a `flow.duration_ms` metric from logs via [Datadog's log-to-metric pipeline](https://docs.datadoghq.com/logs/log_configuration/logs_to_metrics/), then chart it like any other metric. Useful if you don't run APM.
+
+### Re-scope to multiple deployments
+
+The `$service` template variable defaults to `*` and will catch every CrewAI deployment in your Datadog account. Change the default to a specific service name in **Configure → Template Variables** if you want the dashboard to focus on one deployment by default.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| All widgets show "No data" | Facets aren't promoted | Re-do the [Promote facets](#prerequisite-promote-facets) step. Datadog won't query against an un-promoted field. |
+| Error Rate widget shows `NaN` | No executions in the time window | Either no traffic, or `@execution_id` isn't faceted. Expand the time range and re-check facets. |
+| Throughput chart is flat at the same value | Logs aren't reaching Datadog | Search `service:crewai*` in Logs Explorer. If nothing shows, verify the Datadog Agent is running (Agent path) or the OTel collector endpoint is correct (OTLP path). |
+| `crewai_version` shows fewer values than expected | Some containers predate the structured-logs work | The `crewai_version` field was added alongside JSON output. Older deployments running text mode (or older AMP builds) won't emit it. Upgrade those deployments to pick up the field. See the [log schema reference](#log-schema-reference) for the full field contract. |
+| Template variables don't filter widgets | The widget's filter line doesn't reference the template variable | Edit the widget and confirm the search includes `$automation $version $service`. |
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="OpenTelemetry Export" icon="magnifying-glass-chart" href="./capture_telemetry_logs">
+    Vendor-neutral observability for non-Datadog stacks (Grafana, Honeycomb, your own collector) — or as a Datadog complement when you want to fan out telemetry to multiple backends.
+  </Card>
+  <Card title="Datadog Log Search Syntax" icon="magnifying-glass" href="https://docs.datadoghq.com/logs/explorer/search_syntax/">
+    Reference for customizing widget queries against the structured facets above.
+  </Card>
+</CardGroup>

docs/edge/en/enterprise/guides/datadog_dashboard.json

@@ -0,0 +1,582 @@
+{
+  "title": "crewAI -- Operations",
+  "description": "Monitoring dashboard for self-hosted crewAI deployments running structured JSON logs. Tracks executions, errors, token usage, and automation health.",
+  "widgets": [
+    {
+      "id": 8810001,
+      "definition": {
+        "title": "Header",
+        "background_color": "vivid_blue",
+        "show_title": true,
+        "type": "group",
+        "layout_type": "ordered",
+        "widgets": [
+          {
+            "id": 9910001,
+            "definition": {
+              "title": "Total Executions",
+              "time": {
+                "live_span": "1h"
+              },
+              "type": "query_value",
+              "requests": [
+                {
+                  "response_format": "scalar",
+                  "queries": [
+                    {
+                      "data_source": "logs",
+                      "name": "query1",
+                      "search": {
+                        "query": "$automation $version $service"
+                      },
+                      "compute": {
+                        "aggregation": "cardinality",
+                        "metric": "@execution_id"
+                      },
+                      "indexes": [
+                        "*"
+                      ]
+                    }
+                  ],
+                  "formulas": [
+                    {
+                      "formula": "query1"
+                    }
+                  ]
+                }
+              ],
+              "autoscale": true,
+              "precision": 0
+            },
+            "layout": {
+              "x": 0,
+              "y": 0,
+              "width": 3,
+              "height": 2
+            }
+          },
+          {
+            "id": 9910002,
+            "definition": {
+              "title": "Error Rate (%)",
+              "time": {
+                "live_span": "1h"
+              },
+              "type": "query_value",
+              "requests": [
+                {
+                  "response_format": "scalar",
+                  "queries": [
+                    {
+                      "data_source": "logs",
+                      "name": "query1",
+                      "search": {
+                        "query": "status:error $automation $version $service"
+                      },
+                      "compute": {
+                        "aggregation": "count"
+                      },
+                      "indexes": [
+                        "*"
+                      ]
+                    },
+                    {
+                      "data_source": "logs",
+                      "name": "query2",
+                      "search": {
+                        "query": "$automation $version $service"
+                      },
+                      "compute": {
+                        "aggregation": "cardinality",
+                        "metric": "@execution_id"
+                      },
+                      "indexes": [
+                        "*"
+                      ]
+                    }
+                  ],
+                  "formulas": [
+                    {
+                      "formula": "query1 / query2 * 100"
+                    }
+                  ],
+                  "conditional_formats": [
+                    {
+                      "comparator": ">",
+                      "value": 10,
+                      "palette": "white_on_red"
+                    },
+                    {
+                      "comparator": ">",
+                      "value": 5,
+                      "palette": "white_on_yellow"
+                    },
+                    {
+                      "comparator": ">=",
+                      "value": 0,
+                      "palette": "white_on_green"
+                    }
+                  ]
+                }
+              ],
+              "autoscale": false,
+              "custom_unit": "%",
+              "precision": 2
+            },
+            "layout": {
+              "x": 3,
+              "y": 0,
+              "width": 3,
+              "height": 2
+            }
+          },
+          {
+            "id": 9910003,
+            "definition": {
+              "title": "Active Automations",
+              "time": {
+                "live_span": "1h"
+              },
+              "type": "query_value",
+              "requests": [
+                {
+                  "response_format": "scalar",
+                  "queries": [
+                    {
+                      "data_source": "logs",
+                      "name": "query1",
+                      "search": {
+                        "query": "$automation $version $service"
+                      },
+                      "compute": {
+                        "aggregation": "cardinality",
+                        "metric": "@automation_id"
+                      },
+                      "indexes": [
+                        "*"
+                      ]
+                    }
+                  ],
+                  "formulas": [
+                    {
+                      "formula": "query1"
+                    }
+                  ]
+                }
+              ],
+              "autoscale": true,
+              "precision": 0
+            },
+            "layout": {
+              "x": 6,
+              "y": 0,
+              "width": 3,
+              "height": 2
+            }
+          },
+          {
+            "id": 9910004,
+            "definition": {
+              "title": "CrewAI Versions in Use",
+              "time": {
+                "live_span": "1h"
+              },
+              "type": "query_value",
+              "requests": [
+                {
+                  "response_format": "scalar",
+                  "queries": [
+                    {
+                      "data_source": "logs",
+                      "name": "query1",
+                      "search": {
+                        "query": "$automation $version $service"
+                      },
+                      "compute": {
+                        "aggregation": "cardinality",
+                        "metric": "@crewai_version"
+                      },
+                      "indexes": [
+                        "*"
+                      ]
+                    }
+                  ],
+                  "formulas": [
+                    {
+                      "formula": "query1"
+                    }
+                  ]
+                }
+              ],
+              "autoscale": true,
+              "precision": 0
+            },
+            "layout": {
+              "x": 9,
+              "y": 0,
+              "width": 3,
+              "height": 2
+            }
+          }
+        ]
+      },
+      "layout": {
+        "x": 0,
+        "y": 0,
+        "width": 12,
+        "height": 3
+      }
+    },
+    {
+      "id": 8820001,
+      "definition": {
+        "title": "Throughput",
+        "background_color": "vivid_green",
+        "show_title": true,
+        "type": "group",
+        "layout_type": "ordered",
+        "widgets": [
+          {
+            "id": 9920001,
+            "definition": {
+              "title": "Executions per Hour by Automation (top 10)",
+              "show_legend": false,
+              "type": "timeseries",
+              "requests": [
+                {
+                  "response_format": "timeseries",
+                  "queries": [
+                    {
+                      "data_source": "logs",
+                      "name": "query1",
+                      "search": {
+                        "query": "$automation $version $service"
+                      },
+                      "compute": {
+                        "aggregation": "cardinality",
+                        "metric": "@execution_id",
+                        "interval": 3600000
+                      },
+                      "group_by": [
+                        {
+                          "facet": "@automation_name",
+                          "limit": 10,
+                          "sort": {
+                            "aggregation": "cardinality",
+                            "metric": "@execution_id",
+                            "order": "desc"
+                          }
+                        }
+                      ],
+                      "indexes": [
+                        "*"
+                      ]
+                    }
+                  ],
+                  "formulas": [
+                    {
+                      "formula": "query1"
+                    }
+                  ],
+                  "style": {
+                    "palette": "semantic"
+                  },
+                  "display_type": "bars"
+                }
+              ]
+            },
+            "layout": {
+              "x": 0,
+              "y": 0,
+              "width": 12,
+              "height": 3
+            }
+          }
+        ]
+      },
+      "layout": {
+        "x": 0,
+        "y": 3,
+        "width": 12,
+        "height": 4
+      }
+    },
+    {
+      "id": 8830001,
+      "definition": {
+        "title": "Errors",
+        "background_color": "vivid_orange",
+        "show_title": true,
+        "type": "group",
+        "layout_type": "ordered",
+        "widgets": [
+          {
+            "id": 9930001,
+            "definition": {
+              "title": "Errors by Exception Type (top 5)",
+              "show_legend": false,
+              "type": "timeseries",
+              "requests": [
+                {
+                  "response_format": "timeseries",
+                  "queries": [
+                    {
+                      "data_source": "logs",
+                      "name": "query1",
+                      "search": {
+                        "query": "status:error $automation $version $service"
+                      },
+                      "compute": {
+                        "aggregation": "count"
+                      },
+                      "group_by": [
+                        {
+                          "facet": "@exception.type",
+                          "limit": 5,
+                          "sort": {
+                            "aggregation": "count",
+                            "order": "desc"
+                          }
+                        }
+                      ],
+                      "indexes": [
+                        "*"
+                      ]
+                    }
+                  ],
+                  "formulas": [
+                    {
+                      "formula": "query1"
+                    }
+                  ],
+                  "style": {
+                    "palette": "warm"
+                  },
+                  "display_type": "bars"
+                }
+              ]
+            },
+            "layout": {
+              "x": 0,
+              "y": 0,
+              "width": 6,
+              "height": 3
+            }
+          },
+          {
+            "id": 9930002,
+            "definition": {
+              "title": "Top Exception Types by Count",
+              "type": "toplist",
+              "requests": [
+                {
+                  "response_format": "scalar",
+                  "queries": [
+                    {
+                      "data_source": "logs",
+                      "name": "query1",
+                      "search": {
+                        "query": "status:error $automation $version $service"
+                      },
+                      "compute": {
+                        "aggregation": "count"
+                      },
+                      "group_by": [
+                        {
+                          "facet": "@exception.type",
+                          "limit": 10,
+                          "sort": {
+                            "aggregation": "count",
+                            "order": "desc"
+                          }
+                        }
+                      ],
+                      "indexes": [
+                        "*"
+                      ]
+                    }
+                  ],
+                  "formulas": [
+                    {
+                      "formula": "query1"
+                    }
+                  ],
+                  "sort": {
+                    "count": 10,
+                    "order_by": [
+                      {
+                        "type": "formula",
+                        "index": 0,
+                        "order": "desc"
+                      }
+                    ]
+                  }
+                }
+              ],
+              "style": {
+                "palette": "datadog16"
+              }
+            },
+            "layout": {
+              "x": 6,
+              "y": 0,
+              "width": 6,
+              "height": 3
+            }
+          }
+        ]
+      },
+      "layout": {
+        "x": 0,
+        "y": 7,
+        "width": 12,
+        "height": 4
+      }
+    },
+    {
+      "id": 8840001,
+      "definition": {
+        "title": "Cost",
+        "background_color": "vivid_purple",
+        "show_title": true,
+        "type": "group",
+        "layout_type": "ordered",
+        "widgets": [
+          {
+            "id": 9940001,
+            "definition": {
+              "title": "Total Tokens per Hour by Model (input + output)",
+              "show_legend": false,
+              "type": "timeseries",
+              "requests": [
+                {
+                  "response_format": "timeseries",
+                  "queries": [
+                    {
+                      "data_source": "logs",
+                      "name": "query1",
+                      "search": {
+                        "query": "$automation $version $service"
+                      },
+                      "compute": {
+                        "aggregation": "sum",
+                        "metric": "@gen_ai.usage.input_tokens",
+                        "interval": 3600000
+                      },
+                      "group_by": [
+                        {
+                          "facet": "@gen_ai.request.model",
+                          "limit": 10,
+                          "sort": {
+                            "aggregation": "sum",
+                            "metric": "@gen_ai.usage.input_tokens",
+                            "order": "desc"
+                          }
+                        }
+                      ],
+                      "indexes": [
+                        "*"
+                      ]
+                    },
+                    {
+                      "data_source": "logs",
+                      "name": "query2",
+                      "search": {
+                        "query": "$automation $version $service"
+                      },
+                      "compute": {
+                        "aggregation": "sum",
+                        "metric": "@gen_ai.usage.output_tokens",
+                        "interval": 3600000
+                      },
+                      "group_by": [
+                        {
+                          "facet": "@gen_ai.request.model",
+                          "limit": 10,
+                          "sort": {
+                            "aggregation": "sum",
+                            "metric": "@gen_ai.usage.output_tokens",
+                            "order": "desc"
+                          }
+                        }
+                      ],
+                      "indexes": [
+                        "*"
+                      ]
+                    }
+                  ],
+                  "formulas": [
+                    {
+                      "formula": "query1 + query2",
+                      "alias": "Total Tokens"
+                    }
+                  ],
+                  "style": {
+                    "palette": "cool"
+                  },
+                  "display_type": "area"
+                }
+              ]
+            },
+            "layout": {
+              "x": 0,
+              "y": 0,
+              "width": 12,
+              "height": 3
+            }
+          }
+        ]
+      },
+      "layout": {
+        "x": 0,
+        "y": 11,
+        "width": 12,
+        "height": 4
+      }
+    },
+    {
+      "id": 8850002,
+      "definition": {
+        "title": "Drill-Down",
+        "background_color": "gray",
+        "show_title": true,
+        "type": "group",
+        "layout_type": "ordered",
+        "widgets": []
+      },
+      "layout": {
+        "x": 0,
+        "y": 15,
+        "width": 12,
+        "height": 1
+      }
+    }
+  ],
+  "template_variables": [
+    {
+      "name": "automation",
+      "prefix": "@automation_name",
+      "available_values": [],
+      "default": "*"
+    },
+    {
+      "name": "version",
+      "prefix": "@crewai_version",
+      "available_values": [],
+      "default": "*"
+    },
+    {
+      "name": "service",
+      "prefix": "service",
+      "available_values": [],
+      "default": "*"
+    }
+  ],
+  "layout_type": "ordered",
+  "notify_list": [],
+  "pause_auto_refresh": false,
+  "reflow_type": "fixed",
+  "tags": [
+    "ai:created_with_ai"
+  ]
+}

docs/edge/en/guides/tools/publish-custom-tools.mdx

@@ -65,7 +65,7 @@ Regardless of which approach you use, your tool must:
 - Have a **`description`** — tells the agent when and how to use the tool. This directly affects how well agents use your tool, so be clear and specific.
 - Implement **`_run`** (BaseTool) or provide a **function body** (@tool) — the synchronous execution logic.
 - Use **type annotations** on all parameters and return values.
-- Return a **string** result (or something that can be meaningfully converted to one).
+- Return a **string** result, or define an optional Pydantic output schema for structured results.
 
 ### Optional: Async Support
 
@@ -104,6 +104,67 @@ class TranslateInput(BaseModel):
 
 Explicit schemas are recommended for published tools — they produce better agent behavior and clearer documentation for your users.
 
+### Optional: Typed Outputs with `result_schema`
+
+If your tool returns structured data, define a Pydantic output model. This is a good default for published tools because users and agents can rely on named fields.
+
+Direct Python calls still receive the value your tool returns. When an agent uses the tool, CrewAI sends the agent JSON based on the output model.
+
+CrewAI can infer the output schema from a Pydantic return annotation:
+
+```python
+from crewai.tools import BaseTool
+from pydantic import BaseModel, Field
+
+
+class GeolocateResult(BaseModel):
+    latitude: float = Field(..., description="Latitude in decimal degrees.")
+    longitude: float = Field(..., description="Longitude in decimal degrees.")
+
+
+class GeolocateTool(BaseTool):
+    name: str = "Geolocate"
+    description: str = "Converts a street address into latitude/longitude coordinates."
+
+    def _run(self, address: str) -> GeolocateResult:
+        if "1600 Pennsylvania" in address:
+            return GeolocateResult(latitude=38.8977, longitude=-77.0365)
+        return GeolocateResult(latitude=40.7128, longitude=-74.0060)
+```
+
+Set `result_schema` explicitly when your tool returns a dictionary:
+
+```python
+class GeolocateTool(BaseTool):
+    name: str = "Geolocate"
+    description: str = "Converts a street address into latitude/longitude coordinates."
+    result_schema: type[BaseModel] = GeolocateResult
+
+    def _run(self, address: str) -> dict[str, float]:
+        if "1600 Pennsylvania" in address:
+            return {"latitude": 38.8977, "longitude": -77.0365}
+        return {"latitude": 40.7128, "longitude": -74.0060}
+```
+
+If agents should receive a short text summary instead of JSON, override `format_output_for_agent` on your `BaseTool` subclass.
+
+```python
+class GeolocateTool(BaseTool):
+    name: str = "Geolocate"
+    description: str = "Converts a street address into latitude/longitude coordinates."
+
+    def _run(self, address: str) -> GeolocateResult:
+        if "1600 Pennsylvania" in address:
+            return GeolocateResult(latitude=38.8977, longitude=-77.0365)
+        return GeolocateResult(latitude=40.7128, longitude=-74.0060)
+
+    def format_output_for_agent(self, raw_result: object) -> str:
+        result = GeolocateResult.model_validate(raw_result)
+        return f"Latitude {result.latitude}, longitude {result.longitude}"
+```
+
+The override only changes what the agent sees. Direct users of your package still receive the normal value from `tool.run(...)`.
+
 ### Optional: Environment Variables
 
 If your tool requires API keys or other configuration, declare them with `env_vars` so users know what to set:
@@ -241,4 +302,4 @@ agent = Agent(
     tools=[GeolocateTool()],
     # ...
 )
-```
+```

docs/edge/en/learn/create-custom-tools.mdx

@@ -53,6 +53,111 @@ def my_simple_tool(question: str) -> str:
     return "Tool output"
 ```
 
+### Best Practice: Define Typed Outputs
+
+When a tool returns structured data, define a Pydantic output model. This helps the agent read the result as clear fields instead of guessing from plain text.
+
+Typed outputs are useful for results with stable fields, such as IDs, status values, scores, prices, or lists. Plain strings are still fine for short prose results.
+
+Direct Python calls still receive the value your tool returns. When an agent uses a typed tool, CrewAI sends the agent JSON based on the output model.
+
+#### Return a Pydantic Model
+
+CrewAI infers the output schema when your `BaseTool` has a Pydantic return annotation.
+
+```python Code
+from crewai.tools import BaseTool
+from pydantic import BaseModel, Field
+
+class InventoryResult(BaseModel):
+    sku: str = Field(description="The product SKU.")
+    quantity: int = Field(description="Units available.")
+    needs_reorder: bool = Field(description="Whether the item should be reordered.")
+
+class InventoryTool(BaseTool):
+    name: str = "Inventory Check"
+    description: str = "Check current stock for a product SKU."
+
+    def _run(self, sku: str) -> InventoryResult:
+        quantity = {"SKU-123": 14, "SKU-456": 0}.get(sku, 0)
+        return InventoryResult(sku=sku, quantity=quantity, needs_reorder=quantity < 5)
+
+tool = InventoryTool()
+result = tool.run(sku="SKU-123")
+
+# Direct Python calls receive the raw Pydantic object.
+print(result.quantity)
+```
+
+When an agent calls `InventoryTool`, it receives JSON like this:
+
+```json
+{"sku":"SKU-123","quantity":14,"needs_reorder":false}
+```
+
+#### Use `result_schema` with Dictionary Results
+
+If your tool returns a dictionary, set `result_schema` explicitly. You can do this on a `BaseTool` subclass or with the `@tool` decorator:
+
+```python Code
+from crewai.tools import tool
+from pydantic import BaseModel, Field
+
+class ProductResult(BaseModel):
+    sku: str = Field(description="The product SKU.")
+    name: str = Field(description="The product name.")
+    in_stock: bool = Field(description="Whether the product is available.")
+
+@tool("Product Lookup", result_schema=ProductResult)
+def product_lookup(sku: str) -> dict[str, object]:
+    """Look up product availability by SKU."""
+    catalog = {
+        "SKU-123": ("Noise-canceling headset", True),
+        "SKU-456": ("USB-C dock", False),
+    }
+    name, in_stock = catalog.get(sku, ("Unknown product", False))
+    return {
+        "sku": sku,
+        "name": name,
+        "in_stock": in_stock,
+    }
+```
+
+#### Customize the Text Sent to the Agent
+
+By default, typed tool outputs are sent to the agent as JSON. If the agent should receive a short summary instead, subclass `BaseTool` and override `format_output_for_agent`.
+
+```python Code
+from crewai.tools import BaseTool
+from pydantic import BaseModel, Field
+
+class InventoryResult(BaseModel):
+    sku: str = Field(description="The product SKU.")
+    quantity: int = Field(description="Units available.")
+    needs_reorder: bool = Field(description="Whether the item should be reordered.")
+
+class InventoryTool(BaseTool):
+    name: str = "Inventory Check"
+    description: str = "Check current stock for a product SKU."
+
+    def _run(self, sku: str) -> InventoryResult:
+        quantity = {"SKU-123": 14, "SKU-456": 0}.get(sku, 0)
+        return InventoryResult(sku=sku, quantity=quantity, needs_reorder=quantity < 5)
+
+    def format_output_for_agent(self, raw_result: object) -> str:
+        result = InventoryResult.model_validate(raw_result)
+        status = "reorder needed" if result.needs_reorder else "stock is healthy"
+        return f"{result.sku}: {result.quantity} units. {status}."
+
+tool = InventoryTool()
+result = tool.run(sku="SKU-123")
+
+# Direct Python calls receive the raw Pydantic object.
+print(result.quantity)
+```
+
+The override only changes what the agent sees. Direct calls to `tool.run(...)` still return the normal Python value.
+
 ### Defining a Cache Function for the Tool
 
 To optimize tool performance with caching, define custom caching strategies using the `cache_function` attribute.

docs/edge/en/learn/execution-hooks.mdx

@@ -195,9 +195,12 @@ class ToolCallHookContext:
     agent: Agent | None          # Agent executing
     task: Task | None            # Current task
     crew: Crew | None            # Crew instance
-    tool_result: str | None      # Tool result (after hooks)
+    tool_result: str | None      # Agent-facing result string (after hooks)
+    raw_tool_result: Any | None  # Raw Python result (after hooks)
 ```
 
+For typed tool outputs, `tool_result` is the string the agent sees. By default, this is JSON. If the tool uses custom formatting, it can be Markdown or another string. `raw_tool_result` is the original Python value returned by the tool.
+
 ## Common Patterns
 
 ### Safety and Validation

docs/edge/en/learn/tool-hooks.mdx

@@ -60,9 +60,12 @@ class ToolCallHookContext:
     agent: Agent | BaseAgent | None   # Agent executing the tool
     task: Task | None                 # Current task
     crew: Crew | None                 # Crew instance
-    tool_result: str | None           # Tool result (after hooks only)
+    tool_result: str | None           # Agent-facing result string (after hooks only)
+    raw_tool_result: Any | None       # Raw Python result (after hooks only)
 ```
 
+For typed tool outputs, `tool_result` is the string the agent sees. By default, this is JSON. If the tool uses custom formatting, it can be Markdown or another string. Use `raw_tool_result` when your hook needs the typed object or dictionary.
+
 ### Modifying Tool Inputs
 
 **Important:** Always modify tool inputs in-place:

docs/edge/en/tools/file-document/filewritetool.mdx

@@ -42,6 +42,25 @@ print(result)
 - `content`: The content to write into the file.
 - `directory` (optional): The path to the directory where the file will be created. Defaults to the current directory (`.`). If the directory does not exist, it will be created.
 
+## Path confinement
+
+Because `filename` and `directory` may be supplied at runtime by an agent acting on untrusted content, `FileWriterTool` confines writes to an **allow-listed set of root directories**. The resolved target (after expanding symlinks and `..`) must fall inside one of these roots or the write is rejected — a `directory` argument pointing outside them (e.g. `~/.ssh`, `/etc`) no longer grants write access.
+
+The allow-list is, by default, the current working directory. You can extend it for deployments that legitimately write elsewhere:
+
+- `CREWAI_TOOLS_ALLOWED_DIRS` — one or more additional root directories, separated by the OS path separator (`:` on Linux/macOS, `;` on Windows).
+
+```shell
+# Allow writes under /data and /workspace in addition to the cwd
+export CREWAI_TOOLS_ALLOWED_DIRS="/data:/workspace"
+```
+
+<Warning>
+  If the process runs with its working directory set to the filesystem root (`/`) — common in containers started without a `WORKDIR` — the tool will **not** fall back to allow-listing the entire filesystem. Writes fail with a `ValueError` until you set `CREWAI_TOOLS_ALLOWED_DIRS` to an explicit directory. Set a `WORKDIR` (or the env var) in such deployments.
+</Warning>
+
+The `CREWAI_TOOLS_ALLOW_UNSAFE_PATHS=true` escape hatch disables path validation entirely. It is intended only for trusted local development and should not be set in any environment that runs agent-generated or otherwise untrusted instructions.
+
 ## Conclusion
 
 By integrating the `FileWriterTool` into your crews, the agents can reliably write content to files across different operating systems. 

docs/edge/ko/changelog.mdx

@@ -4,6 +4,27 @@ description: "CrewAI의 제품 업데이트, 개선 사항 및 버그 수정"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="2026년 6월 18일">
+  ## v1.14.8a2
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.14.8a2)
+
+  ## 변경 사항
+
+  ### 기능
+  - Flow 정의에 단일 에이전트 작업 추가
+  - 정의 로드 시 흐름 CEL 표현식 검증
+
+  ### 문서
+  - 가져올 수 있는 운영 대시보드와 함께 Datadog 통합 가이드 추가
+  - v1.14.8a1의 스냅샷 및 변경 로그 업데이트
+
+  ## 기여자
+
+  @joaomdmoura, @lucasgomide, @vinibrsl
+
+</Update>
+
 <Update label="2026년 6월 18일">
   ## v1.14.8a1
 

docs/edge/ko/enterprise/features/merged-step-card.mdx

@@ -0,0 +1,87 @@
+---
+title: 단계당 하나의 카드
+description: "Studio 캔버스의 각 단계는 작업과 이를 수행하는 에이전트를 하나로 결합한 단일 카드입니다."
+icon: "layer-group"
+mode: "wide"
+---
+
+{/* CLEANUP: This <Note> banner is the only time-bound content on the page. After the feature ships (Wednesday, June 24th 2026), delete the banner below — the rest of the page is evergreen present-tense docs and needs no other edits. */}
+<Note>
+  **6월 24일 수요일 출시.** Studio 캔버스가 작업과 에이전트를 별도의 노드로 표시하는 대신 단계당 하나의 카드로 전환됩니다. 곧 추가될 새로운 기능을 위해 캔버스를 간소화하기 위한 변경입니다. 기존 자동화는 아무런 변경 없이 그대로 동작하며, 모든 작업 및 에이전트 설정은 단일 카드에 정리되어 그대로 사용할 수 있습니다.
+</Note>
+
+## 개요
+
+Studio 캔버스에서 각 작업 단계는 **하나의 카드**로 표현됩니다. 이 카드는 이전에 별도의 노드에 있던 두 가지를 결합합니다:
+
+- **작업(Task)** — 무엇을 할지(이름, 설명, 예상 출력, 응답 형식).
+- **에이전트(Agent)** — 누가 수행하는지(할당된 에이전트, 모델, 도구).
+
+에이전트는 워크플로의 독립적인 참여자가 아니라 작업의 속성, 즉 *이 작업을 어떤 에이전트가 수행하는지*를 나타냅니다. 작업과 에이전트를 하나의 카드에 두면 이 관계가 명확해지고, 자동화가 왼쪽에서 오른쪽으로 이어지는 단일 작업 단위 체인이 되어 한눈에 읽기 쉬워집니다.
+
+<Frame caption="단계당 하나의 카드: 작업과 푸터에 요약된 할당 에이전트.">
+  ![캔버스의 통합 단계 카드](/images/enterprise/merged-step-card-canvas.png)
+</Frame>
+
+## 캔버스에서
+
+접힌 각 카드는 다음을 표시합니다:
+
+- 상단의 **작업 이름과 설명**.
+- **할당된 에이전트를 요약한 푸터** — 아바타, 이름, 모델, 도구.
+
+별도의 에이전트 노드나 에이전트 → 작업 세로 연결선이 없습니다. 각 단계는 실행 순서대로 서로 직접 연결됩니다.
+
+## 에디터에서
+
+카드를 열어 편집합니다. 확장된 보기는 다른 화면이 아니라 동일한 카드의 상세 상태이며, 명확하게 구분된 두 개의 섹션으로 구성됩니다.
+
+<Frame caption="확장된 에디터: 작업 섹션이 열려 있고 그 아래에 에이전트가 요약되어 있습니다.">
+  ![확장된 단계 에디터](/images/enterprise/merged-step-card-editor.png)
+</Frame>
+
+### 작업 — 무엇을 할지
+
+가장 자주 편집하는 항목이므로 기본적으로 열려 있습니다:
+
+- **이름**
+- **설명**
+- **예상 출력**
+- **응답 형식** — 다운스트림 단계(예: 라우팅)가 이 단계에서 무엇을 읽을지 정확히 제어하므로 여기에 표시됩니다.
+
+### 에이전트 — 누가 수행하는지
+
+할당된 에이전트는 요약으로 표시됩니다 — **이름, 모델, 도구가 인라인으로** 표시됩니다. 더 깊은 구성은 두 개의 접이식 섹션 뒤에 보존됩니다:
+
+- **역할, 목표 및 배경 스토리**
+- **에이전트 설정** — 추론, 최대 추론 시도 횟수, 위임 허용, 최대 반복 횟수, LLM 설정.
+
+<Tip>
+  에이전트의 전체 구성 — 역할, 목표, 배경 스토리, 모델, 도구, LLM 설정 및 전체 에이전트 설정 블록 — 은 **역할, 목표 및 배경 스토리**와 **에이전트 설정** 접이식 섹션 뒤에 편집 빈도에 따라 정리되어 있습니다.
+</Tip>
+
+## 에이전트 교체 vs. 편집
+
+카드에서 에이전트를 다루는 방식은 두 가지로 구분되며, 각각 다른 작업을 수행합니다:
+
+- **교체(Swap)** 는 *어떤* 에이전트가 이 작업을 수행할지 재할당합니다. **교체** 컨트롤을 사용하여 이 프로젝트의 다른 에이전트를 선택하거나, 에이전트 저장소에서 선택하거나, 새 에이전트를 만들 수 있습니다. 이는 작업 범위로 한정됩니다.
+- 에이전트 **편집** — **역할, 목표 및 배경 스토리** 또는 **에이전트 설정** 을 여는 것 — 은 에이전트 *자체*를 변경합니다.
+
+<Frame caption="교체는 작업을 수행할 에이전트를 변경합니다.">
+  ![에이전트 교체 패널](/images/enterprise/merged-step-card-swap-agent.png)
+</Frame>
+
+<Warning>
+  **에이전트는 재사용 가능하며 공유됩니다.** 동일한 에이전트가 프로젝트 전반에서 둘 이상의 작업을 수행할 수 있습니다. 에이전트의 역할, 배경 스토리 또는 설정을 편집하면 열어 본 카드뿐만 아니라 **해당 에이전트가 사용되는 모든 곳**에서 업데이트됩니다. 변경 사항을 하나의 단계에만 적용하려면 공유 에이전트를 편집하지 말고 다른 에이전트로 **교체**하세요.
+</Warning>
+
+## 관련 항목
+
+<CardGroup cols={2}>
+  <Card title="Crew Studio" href="/ko/enterprise/features/crew-studio" icon="pencil">
+    AI 지원과 비주얼 에디터로 자동화를 구축합니다.
+  </Card>
+  <Card title="에이전트 저장소" href="/ko/enterprise/features/agent-repositories" icon="users">
+    자동화 전반에서 에이전트를 관리하고 재사용합니다.
+  </Card>
+</CardGroup>

docs/edge/ko/enterprise/guides/capture_telemetry_logs.mdx

@@ -9,6 +9,10 @@ CrewAI AMP는 배포에서 OpenTelemetry **트레이스**와 **로그**를 자
 
 텔레메트리 데이터는 [OpenTelemetry GenAI 시맨틱 규칙](https://opentelemetry.io/docs/specs/semconv/gen-ai/)과 추가적인 CrewAI 전용 속성을 따릅니다.
 
+<Tip>
+OpenTelemetry는 **권장되는 관측 가능성 경로**입니다 — 벤더 중립적이며, OTLP 호환 백엔드(Grafana, Honeycomb, NewRelic, 자체 수집기)에서 작동합니다. Datadog을 사용하는 경우, Datadog Agent 경로와 Datadog의 OTLP 수집을 모두 다루는 전용 [Datadog 통합](./datadog) 가이드를 참조하세요.
+</Tip>
+
 ## 사전 요구 사항
 
 <CardGroup cols={2}>
@@ -41,17 +45,7 @@ CrewAI AMP는 배포에서 OpenTelemetry **트레이스**와 **로그**를 자
     <Frame>![OpenTelemetry 수집기 구성](/images/crewai-otel-collector-opentelemetry.png)</Frame>
   </Tab>
   <Tab title="Datadog">
-    - **Datadog Site Domain** — Datadog 사이트의 OTLP 호스트만 입력합니다 (프로토콜이나 경로 제외). CrewAI가 전체 HTTPS OTLP 엔드포인트를 자동으로 구성합니다. [Datadog 사이트](https://docs.datadoghq.com/getting_started/site/)에 맞는 호스트를 사용하세요:
-      - `otlp.datadoghq.com` (US1)
-      - `otlp.us3.datadoghq.com` (US3)
-      - `otlp.us5.datadoghq.com` (US5)
-      - `otlp.datadoghq.eu` (EU1)
-      - `otlp.ap1.datadoghq.com` (AP1)
-    - **API Key** — Datadog API 키입니다. [키 생성 방법](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys)을 참고하세요.
-
-    Datadog 통합은 **트레이스**를 내보냅니다.
-
-    <Frame>![Datadog 수집기 구성](/images/crewai-otel-collector-datadog.png)</Frame>
+    Datadog 설정은 전용 [Datadog 통합](./datadog) 가이드를 참조하세요 — Datadog Agent 경로(권장, 로그 볼륨에 더 저렴)와 Datadog의 OTLP 수집을 모두 다루며, 수집기 구성 단계를 완전히 설명합니다.
   </Tab>
 </Tabs>
 

docs/edge/ko/enterprise/guides/datadog.mdx

@@ -0,0 +1,295 @@
+---
+title: "Datadog 통합"
+description: "Datadog Agent 또는 Datadog의 OTLP 수집을 통해 자체 호스팅 CrewAI AMP 배포를 Datadog에서 모니터링하세요 — 두 경로 모두 동일한 구조화된 패싯을 생성하므로 기성 운영 대시보드를 가져올 수 있습니다."
+icon: "dog"
+mode: "wide"
+---
+
+<Note>
+**번역 진행 중** — 콘텐츠가 영어로 표시됩니다.
+</Note>
+
+CrewAI ships first-class support for Datadog: two log-ingestion paths, a JSON log schema designed for cheap indexing, and a ready-made operations dashboard you can import in under five minutes.
+
+<Note>
+For vendor-neutral observability via any OTLP backend (Grafana, Honeycomb, your own collector), see [OpenTelemetry Export](./capture_telemetry_logs).
+</Note>
+
+## Choose a path
+
+CrewAI supports two log-ingestion paths to Datadog — both are first-class and produce the same structured facets that power the dashboard. Pick the one that fits your infrastructure.
+
+<Tabs>
+  <Tab title="Datadog Agent">
+    The Datadog Agent runs alongside your CrewAI containers (typically as a DaemonSet on Kubernetes) and tails their stdout. With `CREWAI_LOG_FORMAT=json` set, each log event ships as a single billable line with structured attributes.
+
+    **Setup:**
+    1. Run the Datadog Agent next to your CrewAI containers — see [Datadog's deployment docs](https://docs.datadoghq.com/agent/) for Kubernetes, ECS, or VM setup. Enable log collection (`logs_enabled: true`) and container log collection (`logs_config.container_collect_all: true`).
+    2. Set `CREWAI_LOG_FORMAT=json` as an **automation environment variable** in CrewAI AMP (open your automation → **Settings → Environment Variables**) so each log event is a single line instead of a multi-line traceback. AMP propagates the value to every container in the deployment (API + workers) — don't set it on the container or host directly. See [Enabling JSON output](#enabling-json-output) below for the AMP UI walkthrough and the [log schema reference](#log-schema-reference) for the full field contract.
+    3. Confirm logs arrive in Datadog Logs with the JSON fields parsed — see [Verify ingestion](#verify-ingestion).
+
+    **Pick this path if** you already operate Datadog Agents (e.g. for infrastructure metrics), or your log volume makes per-event ingestion cost a real concern — collapsing tracebacks into single events keeps Agent ingestion cheap at scale.
+  </Tab>
+  <Tab title="Datadog OTLP intake">
+    CrewAI AMP exports OpenTelemetry traffic directly to Datadog's OTLP endpoint with no Agent required. Logs and traces ride a single export pipeline configured in AMP's UI, using the same protocol you'd use for any other OTLP backend.
+
+    **Setup:**
+    1. In CrewAI AMP, go to **Settings → OpenTelemetry Collectors → Add Collector** and pick **Datadog**.
+    2. Configure the connection:
+       - **Datadog Site Domain** — your Datadog site's OTLP host only, no protocol or path. CrewAI builds the full HTTPS OTLP endpoint for you. Use the host that matches your [Datadog site](https://docs.datadoghq.com/getting_started/site/):
+         - `otlp.datadoghq.com` (US1)
+         - `otlp.us3.datadoghq.com` (US3)
+         - `otlp.us5.datadoghq.com` (US5)
+         - `otlp.datadoghq.eu` (EU1)
+         - `otlp.ap1.datadoghq.com` (AP1)
+       - **API Key** — your Datadog API key. See [how to create one](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys).
+    3. The Datadog template provisions **both signals at once** — when you save, AMP creates a traces collector at `/v1/traces` and a logs collector at `/v1/logs`, both sharing the same Datadog OTLP host and API key. You'll see them as two separate rows in your OTel collectors list.
+    4. *(optional)* Click **Test Connection** to verify CrewAI can reach the endpoint with the credentials you provided. Then click **Save** — both collectors are created in one step.
+
+    <Frame>![Datadog collector configuration](/images/crewai-otel-collector-datadog.png)</Frame>
+
+    **Pick this path if** you'd rather not operate a Datadog Agent, you already use OTLP for traces and want one export pipeline, or you may later want to fan out the same telemetry to other backends (Grafana, Honeycomb, etc.) without changing your application setup.
+  </Tab>
+</Tabs>
+
+Either path lands the same structured facets in Datadog (`@automation_id`, `@kickoff_id`, `@execution_id`, `@automation_name`, `@crewai_version`, `@exception.type`, `@gen_ai.*`), so the dashboard works identically with either choice.
+
+## Log schema reference
+
+<Info>
+This schema applies to the **Datadog Agent path** — stdout JSON logs produced when `CREWAI_LOG_FORMAT=json` is set. Logs delivered via the **Datadog OTLP intake** use OpenTelemetry attribute names and may differ; see [OpenTelemetry Export](./capture_telemetry_logs).
+</Info>
+
+When `CREWAI_LOG_FORMAT=json` is set, every log event is emitted as a **single JSON object per line** to stdout, with internal newlines escaped. The format is plain JSON — Datadog parses it natively, and the same payload is also consumable by Splunk, Loki, Elasticsearch, and CloudWatch without custom log pipelines.
+
+### Why JSON output
+
+<CardGroup cols={2}>
+  <Card title="Lower ingestion cost" icon="dollar-sign">
+    Most managed log backends bill per event. A Python traceback in text format is counted as one event per line — 30+ events for a single error. JSON output collapses each traceback into a single event with the stack trace as an escaped string field.
+  </Card>
+  <Card title="Structured search" icon="magnifying-glass">
+    Search by `@automation_id`, `@exception.type`, `@kickoff_id` instead of grepping free-text. Build dashboards on typed facets without parser configuration.
+  </Card>
+  <Card title="APM ↔ logs correlation" icon="link">
+    Every event carries `trace_id` and `span_id` when fired inside a recording span, so backends auto-link logs to traces.
+  </Card>
+  <Card title="Stable contract" icon="file-shield">
+    The `schema` field gates compatibility — within `v1`, fields are added but never renamed or removed.
+  </Card>
+</CardGroup>
+
+### Enabling JSON output
+
+`CREWAI_LOG_FORMAT=json` must be set as an **automation environment variable** in CrewAI AMP — it is **not** a container, host, or Docker setting. Open your automation in AMP, click the **Settings** icon, and add the variable under the **Environment Variables** section. AMP applies the value to every container in the deployment (API + workers) on the next restart. See [Update Your Crew](./update-crew) for the full UI walkthrough with screenshots.
+
+```shell
+CREWAI_LOG_FORMAT=json
+```
+
+Restart the deployment to pick up the change. Every log line on stdout from that point on is a single JSON object.
+
+<Note>
+  The default value is `text`, which preserves the legacy human-readable line format byte-for-byte. Setting any value other than `json` falls back to text mode. There is no migration step — the variable is read at process start and the format switches immediately.
+</Note>
+
+### Example events
+
+A single info-level log inside an active automation kickoff:
+
+```json
+{
+  "schema": "v1",
+  "ts": "2026-06-17T16:14:23.482914Z",
+  "level": "INFO",
+  "logger": "crewai_enterprise.utilities.pii_redaction",
+  "crewai_version": "1.14.7",
+  "msg": "PII tracking state reset (engines preserved)",
+  "automation_id": "12",
+  "task_id": "0843a930-b306-464b-89c8-bfafa78cc711",
+  "kickoff_id": "0843a930-b306-464b-89c8-bfafa78cc711",
+  "execution_id": "0843a930-b306-464b-89c8-bfafa78cc711",
+  "automation_name": "research_flow"
+}
+```
+
+An error with a Python exception is collapsed into a single event with the traceback as a string:
+
+```json
+{
+  "schema": "v1",
+  "ts": "2026-06-17T16:14:31.218450Z",
+  "level": "ERROR",
+  "logger": "api.tasks.flow_run_task",
+  "crewai_version": "1.14.7",
+  "msg": "Flow execution failed",
+  "automation_id": "12",
+  "kickoff_id": "0843a930-b306-464b-89c8-bfafa78cc711",
+  "execution_id": "0843a930-b306-464b-89c8-bfafa78cc711",
+  "automation_name": "research_flow",
+  "exception": {
+    "type": "ValueError",
+    "message": "Topic cannot be empty",
+    "stacktrace": "Traceback (most recent call last):\n  File \"/app/flow.py\", line 42, in summarize\n    ...\nValueError: Topic cannot be empty\n"
+  }
+}
+```
+
+The same error in legacy text mode would have produced ~25 separate log events (one per traceback line) — all of which the backend would bill and index individually.
+
+### Schema v1 fields
+
+Within the `v1` schema, fields are only added, never renamed or removed. New fields will appear as soon as a deployment is upgraded.
+
+| Field | Type | Always present | Source |
+|-------|------|----------------|--------|
+| `schema` | string | Yes | Constant `"v1"`. Increment indicates a breaking schema change. |
+| `ts` | string (ISO-8601 UTC, microseconds) | Yes | Record creation time, e.g. `2026-06-17T16:14:23.482914Z`. |
+| `level` | string | Yes | Python log level name: `DEBUG` / `INFO` / `WARNING` / `ERROR` / `CRITICAL`. |
+| `logger` | string | Yes | Dotted logger name, e.g. `api.tasks.flow_run_task`. |
+| `crewai_version` | string | Yes (when `crewai` package metadata is resolvable) | Installed `crewai` package version, e.g. `"1.14.7"`. |
+| `msg` | string | Yes | Rendered log message (after `%`-formatting / `{}`-formatting). |
+| `automation_id` | string | When `CREWAI_PLUS_ID` env var is set | Numeric deployment ID (AMP provisions this on every container). |
+| `task_id` | string | On Celery worker logs | Celery task UUID, or `"no-task"` for non-task contexts. |
+| `kickoff_id` | string | Inside an automation kickoff | UUID of the current kickoff. |
+| `execution_id` | string | Inside an automation kickoff | UUID of the current sub-execution. Equal to `kickoff_id` at the top level; differs for nested flow methods that spawn sub-executions. |
+| `automation_name` | string | Inside an automation kickoff | Human-readable automation/flow name, e.g. `"research_flow"`. |
+| `trace_id` | string (32-hex) | Inside a recording OpenTelemetry span | Hex trace ID. Omitted when no span is active. |
+| `span_id` | string (16-hex) | Inside a recording OpenTelemetry span | Hex span ID. Omitted when no span is active. |
+| `exception` | object | When the log record has `exc_info` | `{type, message, stacktrace}` — full traceback as a single escaped string. |
+
+<Tip>
+  Any additional `extra={...}` kwargs passed to a logger call appear as top-level JSON fields verbatim. Reserved field names above always win to keep the schema stable.
+</Tip>
+
+### Stability promise
+
+The `schema` field declares the contract. Within `v1`, CrewAI commits to:
+
+- **Never removing a field** that customers may have built queries or dashboards against.
+- **Never renaming a field** in place — renames happen via a schema bump (e.g. `v2`), with the old name kept as a deprecated alias for at least one release cycle.
+- **Adding new fields** at any time. Consumers should ignore unknown top-level keys.
+
+When a `v2` is introduced, both the `schema` field and the migration guide will be published in advance, and `v1` will continue to be emitted for one release cycle so dashboards and queries have time to migrate.
+
+## Prerequisite: promote facets
+
+Datadog auto-discovers fields the first time it sees them but doesn't make them queryable in widgets until they're promoted to **facets**. This is a one-time setup in your Datadog account.
+
+<Steps>
+  <Step title="Search for a CrewAI log">
+    Open [Logs Explorer](https://app.datadoghq.com/logs) and search `service:crewai*`. You should see at least one log event.
+  </Step>
+  <Step title="Promote each field">
+    Click any log entry to open the right-hand details panel. For each field below, hover the field name → click the gear icon → **Create facet**.
+
+    - `automation_id`, `automation_name`, `execution_id`, `kickoff_id`, `task_id`
+    - `crewai_version`, `model_id`
+    - `exception.type`, `exception.message`
+
+    Skip any field that already shows a star icon next to its name — that means it's already a facet. The `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, and `gen_ai.request.model` facets are typically promoted automatically by Datadog's LLM Observability auto-discovery, but verify they exist before importing the dashboard.
+  </Step>
+</Steps>
+
+## Import the dashboard
+
+<Steps>
+  <Step title="Download the dashboard JSON">
+    Save [`datadog_dashboard.json`](https://raw.githubusercontent.com/crewAIInc/crewAI/main/docs/edge/en/enterprise/guides/datadog_dashboard.json) to your machine.
+  </Step>
+  <Step title="Open the import dialog in Datadog">
+    Navigate to **Dashboards → New Dashboard**. Click the **gear icon** in the top right of the empty dashboard and select **Import Dashboard JSON**.
+  </Step>
+  <Step title="Paste or upload the JSON">
+    Paste the contents of `datadog_dashboard.json` into the import dialog (or drag the file in). Click **Import**.
+
+    Datadog creates the dashboard immediately and lands you on it. The first load may show empty widgets for a few seconds while queries execute against the time range.
+  </Step>
+</Steps>
+
+<Tip>
+  Datadog's [Dashboard API](https://docs.datadoghq.com/api/latest/dashboards/#create-a-new-dashboard) accepts the same JSON via `POST /api/v1/dashboard`. Use it if you manage dashboards through Terraform, Pulumi, or CI.
+</Tip>
+
+## What you get
+
+The dashboard is organized into four sections plus a placeholder for a custom drill-down widget:
+
+| Section | Widgets | Useful for |
+|---------|---------|------------|
+| **Header** | Total Executions · Error Rate (%) · Active Automations · CrewAI Versions in Use | At-a-glance health for the last hour. Error Rate is conditionally formatted (green ≤ 5%, yellow ≤ 10%, red > 10%). |
+| **Throughput** | Executions per Hour by Automation (top 10, stacked bars) | Spotting traffic shifts, surfacing busy automations, validating that a rollout didn't change baseline volume. |
+| **Errors** | Errors by Exception Type (top 5, stacked bars) · Top Exception Types by Count (toplist) | Triaging failures — which exception types are spiking, which automations they're hitting. |
+| **Cost** | Total Tokens per Hour by Model (input + output, stacked area) | Tracking LLM token spend by model. Useful for catching cost regressions when an automation switches model or starts looping. |
+| **Drill-Down** | _(empty placeholder)_ | See [Customization](#customize) for adding a recent-errors log stream here. |
+
+Three template variables at the top of the dashboard re-scope every widget at once:
+
+- **`$automation`** — filter to a single automation by name.
+- **`$version`** — filter to a single `crewai` SDK version (useful for comparing pre- and post-upgrade behavior).
+- **`$service`** — filter to a specific Datadog `service` tag (useful when multiple CrewAI deployments share one Datadog account).
+
+## Verify ingestion
+
+Open [Logs Explorer](https://app.datadoghq.com/logs) and run a query that matches your ingestion path:
+
+<Tabs>
+  <Tab title="Datadog Agent">
+    Search `service:crewai* @schema:v1`. You should see structured logs with the JSON fields parsed into Datadog facets. Pick a recent event and verify it has `@automation_id`, `@kickoff_id`, `@execution_id`, `@crewai_version`, and (when running inside a span) `@trace_id` / `@span_id` populated.
+
+    If nothing appears, confirm `CREWAI_LOG_FORMAT=json` is set under your automation's **Environment Variables** in AMP, the deployment was restarted after the change, and the Datadog Agent is tailing container stdout.
+  </Tab>
+  <Tab title="Datadog OTLP intake">
+    Search `source:otlp service:crewai*`. OTLP attributes land with their OpenTelemetry names (`automation_id`, `crewai.kickoff.id`, etc.) rather than the stdout JSON keys, but they map to the same dashboard facets after [facet promotion](#prerequisite-promote-facets).
+
+    If nothing appears, verify the collector endpoint is correct (`/v1/logs` for logs, `/v1/traces` for traces) and **Test Connection** succeeded when the collector was saved.
+  </Tab>
+</Tabs>
+
+## Customize
+
+The dashboard ships with deliberate gaps so you can extend it without uninstalling and re-importing.
+
+### Add a Recent Errors log stream
+
+The **Drill-Down** section is intentionally empty. Add a Log Stream widget to it for an inline view of recent failures:
+
+1. Edit the dashboard and click **+ Add Widgets** inside the Drill-Down group.
+2. Drag in a **Log Stream** widget.
+3. Set the filter query to `status:error $automation $version $service`.
+4. Choose columns: `@timestamp`, `@automation_name`, `@exception.type`, `@exception.message`, `@execution_id`.
+5. Sort by most recent, limit to 25 entries.
+
+Clicking any row jumps to Logs Explorer with the same filter pre-applied.
+
+### Add p95 latency
+
+Logs don't include execution duration by default. Two ways to add a latency widget:
+
+- **From APM traces** — if you also export OTLP traces to Datadog, add a Timeseries widget with data source **Traces**, query `service:crewai*`, aggregation `p95 of @duration`. Datadog APM auto-tracks span duration.
+- **From metric extraction** — extract a `flow.duration_ms` metric from logs via [Datadog's log-to-metric pipeline](https://docs.datadoghq.com/logs/log_configuration/logs_to_metrics/), then chart it like any other metric. Useful if you don't run APM.
+
+### Re-scope to multiple deployments
+
+The `$service` template variable defaults to `*` and will catch every CrewAI deployment in your Datadog account. Change the default to a specific service name in **Configure → Template Variables** if you want the dashboard to focus on one deployment by default.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| All widgets show "No data" | Facets aren't promoted | Re-do the [Promote facets](#prerequisite-promote-facets) step. Datadog won't query against an un-promoted field. |
+| Error Rate widget shows `NaN` | No executions in the time window | Either no traffic, or `@execution_id` isn't faceted. Expand the time range and re-check facets. |
+| Throughput chart is flat at the same value | Logs aren't reaching Datadog | Search `service:crewai*` in Logs Explorer. If nothing shows, verify the Datadog Agent is running (Agent path) or the OTel collector endpoint is correct (OTLP path). |
+| `crewai_version` shows fewer values than expected | Some containers predate the structured-logs work | The `crewai_version` field was added alongside JSON output. Older deployments running text mode (or older AMP builds) won't emit it. Upgrade those deployments to pick up the field. See the [log schema reference](#log-schema-reference) for the full field contract. |
+| Template variables don't filter widgets | The widget's filter line doesn't reference the template variable | Edit the widget and confirm the search includes `$automation $version $service`. |
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="OpenTelemetry Export" icon="magnifying-glass-chart" href="./capture_telemetry_logs">
+    Vendor-neutral observability for non-Datadog stacks (Grafana, Honeycomb, your own collector) — or as a Datadog complement when you want to fan out telemetry to multiple backends.
+  </Card>
+  <Card title="Datadog Log Search Syntax" icon="magnifying-glass" href="https://docs.datadoghq.com/logs/explorer/search_syntax/">
+    Reference for customizing widget queries against the structured facets above.
+  </Card>
+</CardGroup>

docs/edge/pt-BR/changelog.mdx

@@ -4,6 +4,27 @@ description: "Atualizações de produto, melhorias e correções do CrewAI"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="18 jun 2026">
+  ## v1.14.8a2
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.8a2)
+
+  ## O que Mudou
+
+  ### Funcionalidades
+  - Adicionar ação de agente único às definições de Fluxo
+  - Validar expressões CEL de fluxo no momento do carregamento da definição
+
+  ### Documentação
+  - Adicionar guia de integração do Datadog com painel de operações importável
+  - Atualizar snapshot e changelog para v1.14.8a1
+
+  ## Contributors
+
+  @joaomdmoura, @lucasgomide, @vinibrsl
+
+</Update>
+
 <Update label="18 jun 2026">
   ## v1.14.8a1
 

docs/edge/pt-BR/enterprise/features/merged-step-card.mdx

@@ -0,0 +1,87 @@
+---
+title: Um Card por Etapa
+description: "Cada etapa no canvas do Studio é um único card que combina a tarefa e o agente que a executa."
+icon: "layer-group"
+mode: "wide"
+---
+
+{/* CLEANUP: This <Note> banner is the only time-bound content on the page. After the feature ships (Wednesday, June 24th 2026), delete the banner below — the rest of the page is evergreen present-tense docs and needs no other edits. */}
+<Note>
+  **Lançamento na quarta-feira, 24 de junho.** O canvas do Studio passa a exibir um card por etapa, em vez de nós separados para tarefa e agente, para simplificar o canvas à medida que adicionamos novas funcionalidades em breve. Suas automações existentes continuam funcionando sem nenhuma alteração necessária — cada configuração de tarefa e de agente continua disponível, apenas organizada em um único card.
+</Note>
+
+## Visão geral
+
+No canvas do Studio, cada etapa de trabalho é representada por um **único card**. O card combina dois elementos que antes ficavam em nós separados:
+
+- **A tarefa** — o que fazer (nome, descrição, saída esperada e formato da resposta).
+- **O agente** — quem faz (o agente atribuído, seu modelo e suas ferramentas).
+
+Um agente não é um participante independente do seu fluxo de trabalho — ele é um atributo da tarefa: *qual agente executa este trabalho.* Colocar a tarefa e seu agente em um único card torna essa relação explícita e transforma sua automação em uma única cadeia de unidades de trabalho, da esquerda para a direita, mais fácil de ler em uma olhada.
+
+<Frame caption="Um card por etapa: a tarefa com o agente atribuído resumido no rodapé.">
+  ![Cards de etapa unificados no canvas](/images/enterprise/merged-step-card-canvas.png)
+</Frame>
+
+## No canvas
+
+Cada card recolhido mostra:
+
+- O **nome e a descrição da tarefa** no topo.
+- Um **rodapé resumindo o agente atribuído** — avatar, nome, modelo e ferramentas.
+
+Não há nó de agente separado nem aresta vertical de agente → tarefa. Suas etapas se conectam diretamente umas às outras na ordem em que são executadas.
+
+## No editor
+
+Abra um card para editá-lo. A visão expandida é o mesmo card em um estado detalhado — não uma tela diferente — organizada em duas seções claramente identificadas.
+
+<Frame caption="O editor expandido: a seção da tarefa aberta, com o agente resumido abaixo.">
+  ![Editor de etapa expandido](/images/enterprise/merged-step-card-editor.png)
+</Frame>
+
+### A tarefa — o que fazer
+
+Aberta por padrão, já que é o que você costuma editar:
+
+- **Nome**
+- **Descrição**
+- **Saída Esperada**
+- **Formato da Resposta** — exibido aqui porque controla exatamente o que as etapas seguintes (como o roteamento) leem desta etapa.
+
+### O agente — quem faz
+
+O agente atribuído é mostrado como um resumo — **nome, modelo e ferramentas em linha**. Sua configuração mais detalhada é preservada por trás de duas seções recolhíveis:
+
+- **Papel, objetivo e história**
+- **Configurações do agente** — raciocínio, máximo de tentativas de raciocínio, permitir delegação, máximo de iterações e configurações de LLM.
+
+<Tip>
+  A configuração completa de um agente — Papel, Objetivo, História, Modelo, Ferramentas, Configurações de LLM e todo o bloco de Configurações do agente — fica por trás das seções recolhíveis **Papel, objetivo e história** e **Configurações do agente**, organizada pela frequência com que você a edita.
+</Tip>
+
+## Trocar vs. editar o agente
+
+Há duas maneiras distintas de trabalhar com o agente em um card, e elas fazem coisas diferentes:
+
+- **Trocar** reatribui *qual* agente executa esta tarefa. Use o controle **Trocar** para escolher um agente diferente deste projeto, selecionar um do seu Repositório de Agentes ou criar um novo agente. Isso tem escopo limitado à tarefa.
+- **Editar** o agente — abrindo **Papel, objetivo e história** ou **Configurações do agente** — altera o agente *em si*.
+
+<Frame caption="Trocar muda qual agente executa a tarefa.">
+  ![Painel de troca de agente](/images/enterprise/merged-step-card-swap-agent.png)
+</Frame>
+
+<Warning>
+  **Os agentes são reutilizáveis e compartilhados.** O mesmo agente pode executar mais de uma tarefa em todo o seu projeto. Editar o papel, a história ou as configurações de um agente atualiza esse agente **em todos os lugares onde ele é usado** — não apenas no card que você abriu. Se quiser que uma alteração se aplique a apenas uma etapa, **Troque** por um agente diferente em vez de editar o agente compartilhado.
+</Warning>
+
+## Relacionados
+
+<CardGroup cols={2}>
+  <Card title="Crew Studio" href="/pt-BR/enterprise/features/crew-studio" icon="pencil">
+    Crie automações com assistência de IA e um editor visual.
+  </Card>
+  <Card title="Repositórios de Agentes" href="/pt-BR/enterprise/features/agent-repositories" icon="users">
+    Gerencie e reutilize agentes em suas automações.
+  </Card>
+</CardGroup>

docs/edge/pt-BR/enterprise/guides/capture_telemetry_logs.mdx

@@ -9,6 +9,10 @@ O CrewAI AMP pode exportar **traces** e **logs** do OpenTelemetry das suas impla
 
 Os dados de telemetria seguem as [convenções semânticas GenAI do OpenTelemetry](https://opentelemetry.io/docs/specs/semconv/gen-ai/) além de atributos adicionais específicos do CrewAI.
 
+<Tip>
+OpenTelemetry é o **caminho de observabilidade recomendado** — neutro em relação a fornecedores, funciona com qualquer backend compatível com OTLP (Grafana, Honeycomb, NewRelic, seu próprio coletor). Se você usa especificamente o Datadog, veja o guia dedicado [Integração com Datadog](./datadog), que cobre tanto o caminho do Datadog Agent quanto o ingest OTLP do Datadog.
+</Tip>
+
 ## Pré-requisitos
 
 <CardGroup cols={2}>
@@ -41,17 +45,7 @@ Os dados de telemetria seguem as [convenções semânticas GenAI do OpenTelemetr
     <Frame>![Configuração do coletor OpenTelemetry](/images/crewai-otel-collector-opentelemetry.png)</Frame>
   </Tab>
   <Tab title="Datadog">
-    - **Datadog Site Domain** — Apenas o host OTLP do seu site Datadog, sem protocolo ou caminho. O CrewAI monta o endpoint HTTPS OTLP completo para você. Use o host correspondente ao seu [site Datadog](https://docs.datadoghq.com/getting_started/site/):
-      - `otlp.datadoghq.com` (US1)
-      - `otlp.us3.datadoghq.com` (US3)
-      - `otlp.us5.datadoghq.com` (US5)
-      - `otlp.datadoghq.eu` (EU1)
-      - `otlp.ap1.datadoghq.com` (AP1)
-    - **API Key** — Sua chave de API do Datadog. Veja [como criar uma](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys).
-
-    A integração com o Datadog exporta **traces**.
-
-    <Frame>![Configuração do coletor Datadog](/images/crewai-otel-collector-datadog.png)</Frame>
+    Para configurar o Datadog, veja o guia dedicado [Integração com Datadog](./datadog) — ele cobre tanto o caminho do Datadog Agent (recomendado, mais barato para volumes altos de log) quanto o ingest OTLP do Datadog, com os passos completos de configuração do coletor.
   </Tab>
 </Tabs>
 

docs/edge/pt-BR/enterprise/guides/datadog.mdx

@@ -0,0 +1,295 @@
+---
+title: "Integração com Datadog"
+description: "Monitore implantações CrewAI AMP auto-hospedadas no Datadog via Datadog Agent ou ingest OTLP do Datadog — ambos os caminhos entregam as mesmas facetas estruturadas para importar o dashboard de operações pronto."
+icon: "dog"
+mode: "wide"
+---
+
+<Note>
+**Tradução em andamento** — conteúdo exibido em inglês.
+</Note>
+
+CrewAI ships first-class support for Datadog: two log-ingestion paths, a JSON log schema designed for cheap indexing, and a ready-made operations dashboard you can import in under five minutes.
+
+<Note>
+For vendor-neutral observability via any OTLP backend (Grafana, Honeycomb, your own collector), see [OpenTelemetry Export](./capture_telemetry_logs).
+</Note>
+
+## Choose a path
+
+CrewAI supports two log-ingestion paths to Datadog — both are first-class and produce the same structured facets that power the dashboard. Pick the one that fits your infrastructure.
+
+<Tabs>
+  <Tab title="Datadog Agent">
+    The Datadog Agent runs alongside your CrewAI containers (typically as a DaemonSet on Kubernetes) and tails their stdout. With `CREWAI_LOG_FORMAT=json` set, each log event ships as a single billable line with structured attributes.
+
+    **Setup:**
+    1. Run the Datadog Agent next to your CrewAI containers — see [Datadog's deployment docs](https://docs.datadoghq.com/agent/) for Kubernetes, ECS, or VM setup. Enable log collection (`logs_enabled: true`) and container log collection (`logs_config.container_collect_all: true`).
+    2. Set `CREWAI_LOG_FORMAT=json` as an **automation environment variable** in CrewAI AMP (open your automation → **Settings → Environment Variables**) so each log event is a single line instead of a multi-line traceback. AMP propagates the value to every container in the deployment (API + workers) — don't set it on the container or host directly. See [Enabling JSON output](#enabling-json-output) below for the AMP UI walkthrough and the [log schema reference](#log-schema-reference) for the full field contract.
+    3. Confirm logs arrive in Datadog Logs with the JSON fields parsed — see [Verify ingestion](#verify-ingestion).
+
+    **Pick this path if** you already operate Datadog Agents (e.g. for infrastructure metrics), or your log volume makes per-event ingestion cost a real concern — collapsing tracebacks into single events keeps Agent ingestion cheap at scale.
+  </Tab>
+  <Tab title="Datadog OTLP intake">
+    CrewAI AMP exports OpenTelemetry traffic directly to Datadog's OTLP endpoint with no Agent required. Logs and traces ride a single export pipeline configured in AMP's UI, using the same protocol you'd use for any other OTLP backend.
+
+    **Setup:**
+    1. In CrewAI AMP, go to **Settings → OpenTelemetry Collectors → Add Collector** and pick **Datadog**.
+    2. Configure the connection:
+       - **Datadog Site Domain** — your Datadog site's OTLP host only, no protocol or path. CrewAI builds the full HTTPS OTLP endpoint for you. Use the host that matches your [Datadog site](https://docs.datadoghq.com/getting_started/site/):
+         - `otlp.datadoghq.com` (US1)
+         - `otlp.us3.datadoghq.com` (US3)
+         - `otlp.us5.datadoghq.com` (US5)
+         - `otlp.datadoghq.eu` (EU1)
+         - `otlp.ap1.datadoghq.com` (AP1)
+       - **API Key** — your Datadog API key. See [how to create one](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys).
+    3. The Datadog template provisions **both signals at once** — when you save, AMP creates a traces collector at `/v1/traces` and a logs collector at `/v1/logs`, both sharing the same Datadog OTLP host and API key. You'll see them as two separate rows in your OTel collectors list.
+    4. *(optional)* Click **Test Connection** to verify CrewAI can reach the endpoint with the credentials you provided. Then click **Save** — both collectors are created in one step.
+
+    <Frame>![Datadog collector configuration](/images/crewai-otel-collector-datadog.png)</Frame>
+
+    **Pick this path if** you'd rather not operate a Datadog Agent, you already use OTLP for traces and want one export pipeline, or you may later want to fan out the same telemetry to other backends (Grafana, Honeycomb, etc.) without changing your application setup.
+  </Tab>
+</Tabs>
+
+Either path lands the same structured facets in Datadog (`@automation_id`, `@kickoff_id`, `@execution_id`, `@automation_name`, `@crewai_version`, `@exception.type`, `@gen_ai.*`), so the dashboard works identically with either choice.
+
+## Log schema reference
+
+<Info>
+This schema applies to the **Datadog Agent path** — stdout JSON logs produced when `CREWAI_LOG_FORMAT=json` is set. Logs delivered via the **Datadog OTLP intake** use OpenTelemetry attribute names and may differ; see [OpenTelemetry Export](./capture_telemetry_logs).
+</Info>
+
+When `CREWAI_LOG_FORMAT=json` is set, every log event is emitted as a **single JSON object per line** to stdout, with internal newlines escaped. The format is plain JSON — Datadog parses it natively, and the same payload is also consumable by Splunk, Loki, Elasticsearch, and CloudWatch without custom log pipelines.
+
+### Why JSON output
+
+<CardGroup cols={2}>
+  <Card title="Lower ingestion cost" icon="dollar-sign">
+    Most managed log backends bill per event. A Python traceback in text format is counted as one event per line — 30+ events for a single error. JSON output collapses each traceback into a single event with the stack trace as an escaped string field.
+  </Card>
+  <Card title="Structured search" icon="magnifying-glass">
+    Search by `@automation_id`, `@exception.type`, `@kickoff_id` instead of grepping free-text. Build dashboards on typed facets without parser configuration.
+  </Card>
+  <Card title="APM ↔ logs correlation" icon="link">
+    Every event carries `trace_id` and `span_id` when fired inside a recording span, so backends auto-link logs to traces.
+  </Card>
+  <Card title="Stable contract" icon="file-shield">
+    The `schema` field gates compatibility — within `v1`, fields are added but never renamed or removed.
+  </Card>
+</CardGroup>
+
+### Enabling JSON output
+
+`CREWAI_LOG_FORMAT=json` must be set as an **automation environment variable** in CrewAI AMP — it is **not** a container, host, or Docker setting. Open your automation in AMP, click the **Settings** icon, and add the variable under the **Environment Variables** section. AMP applies the value to every container in the deployment (API + workers) on the next restart. See [Update Your Crew](./update-crew) for the full UI walkthrough with screenshots.
+
+```shell
+CREWAI_LOG_FORMAT=json
+```
+
+Restart the deployment to pick up the change. Every log line on stdout from that point on is a single JSON object.
+
+<Note>
+  The default value is `text`, which preserves the legacy human-readable line format byte-for-byte. Setting any value other than `json` falls back to text mode. There is no migration step — the variable is read at process start and the format switches immediately.
+</Note>
+
+### Example events
+
+A single info-level log inside an active automation kickoff:
+
+```json
+{
+  "schema": "v1",
+  "ts": "2026-06-17T16:14:23.482914Z",
+  "level": "INFO",
+  "logger": "crewai_enterprise.utilities.pii_redaction",
+  "crewai_version": "1.14.7",
+  "msg": "PII tracking state reset (engines preserved)",
+  "automation_id": "12",
+  "task_id": "0843a930-b306-464b-89c8-bfafa78cc711",
+  "kickoff_id": "0843a930-b306-464b-89c8-bfafa78cc711",
+  "execution_id": "0843a930-b306-464b-89c8-bfafa78cc711",
+  "automation_name": "research_flow"
+}
+```
+
+An error with a Python exception is collapsed into a single event with the traceback as a string:
+
+```json
+{
+  "schema": "v1",
+  "ts": "2026-06-17T16:14:31.218450Z",
+  "level": "ERROR",
+  "logger": "api.tasks.flow_run_task",
+  "crewai_version": "1.14.7",
+  "msg": "Flow execution failed",
+  "automation_id": "12",
+  "kickoff_id": "0843a930-b306-464b-89c8-bfafa78cc711",
+  "execution_id": "0843a930-b306-464b-89c8-bfafa78cc711",
+  "automation_name": "research_flow",
+  "exception": {
+    "type": "ValueError",
+    "message": "Topic cannot be empty",
+    "stacktrace": "Traceback (most recent call last):\n  File \"/app/flow.py\", line 42, in summarize\n    ...\nValueError: Topic cannot be empty\n"
+  }
+}
+```
+
+The same error in legacy text mode would have produced ~25 separate log events (one per traceback line) — all of which the backend would bill and index individually.
+
+### Schema v1 fields
+
+Within the `v1` schema, fields are only added, never renamed or removed. New fields will appear as soon as a deployment is upgraded.
+
+| Field | Type | Always present | Source |
+|-------|------|----------------|--------|
+| `schema` | string | Yes | Constant `"v1"`. Increment indicates a breaking schema change. |
+| `ts` | string (ISO-8601 UTC, microseconds) | Yes | Record creation time, e.g. `2026-06-17T16:14:23.482914Z`. |
+| `level` | string | Yes | Python log level name: `DEBUG` / `INFO` / `WARNING` / `ERROR` / `CRITICAL`. |
+| `logger` | string | Yes | Dotted logger name, e.g. `api.tasks.flow_run_task`. |
+| `crewai_version` | string | Yes (when `crewai` package metadata is resolvable) | Installed `crewai` package version, e.g. `"1.14.7"`. |
+| `msg` | string | Yes | Rendered log message (after `%`-formatting / `{}`-formatting). |
+| `automation_id` | string | When `CREWAI_PLUS_ID` env var is set | Numeric deployment ID (AMP provisions this on every container). |
+| `task_id` | string | On Celery worker logs | Celery task UUID, or `"no-task"` for non-task contexts. |
+| `kickoff_id` | string | Inside an automation kickoff | UUID of the current kickoff. |
+| `execution_id` | string | Inside an automation kickoff | UUID of the current sub-execution. Equal to `kickoff_id` at the top level; differs for nested flow methods that spawn sub-executions. |
+| `automation_name` | string | Inside an automation kickoff | Human-readable automation/flow name, e.g. `"research_flow"`. |
+| `trace_id` | string (32-hex) | Inside a recording OpenTelemetry span | Hex trace ID. Omitted when no span is active. |
+| `span_id` | string (16-hex) | Inside a recording OpenTelemetry span | Hex span ID. Omitted when no span is active. |
+| `exception` | object | When the log record has `exc_info` | `{type, message, stacktrace}` — full traceback as a single escaped string. |
+
+<Tip>
+  Any additional `extra={...}` kwargs passed to a logger call appear as top-level JSON fields verbatim. Reserved field names above always win to keep the schema stable.
+</Tip>
+
+### Stability promise
+
+The `schema` field declares the contract. Within `v1`, CrewAI commits to:
+
+- **Never removing a field** that customers may have built queries or dashboards against.
+- **Never renaming a field** in place — renames happen via a schema bump (e.g. `v2`), with the old name kept as a deprecated alias for at least one release cycle.
+- **Adding new fields** at any time. Consumers should ignore unknown top-level keys.
+
+When a `v2` is introduced, both the `schema` field and the migration guide will be published in advance, and `v1` will continue to be emitted for one release cycle so dashboards and queries have time to migrate.
+
+## Prerequisite: promote facets
+
+Datadog auto-discovers fields the first time it sees them but doesn't make them queryable in widgets until they're promoted to **facets**. This is a one-time setup in your Datadog account.
+
+<Steps>
+  <Step title="Search for a CrewAI log">
+    Open [Logs Explorer](https://app.datadoghq.com/logs) and search `service:crewai*`. You should see at least one log event.
+  </Step>
+  <Step title="Promote each field">
+    Click any log entry to open the right-hand details panel. For each field below, hover the field name → click the gear icon → **Create facet**.
+
+    - `automation_id`, `automation_name`, `execution_id`, `kickoff_id`, `task_id`
+    - `crewai_version`, `model_id`
+    - `exception.type`, `exception.message`
+
+    Skip any field that already shows a star icon next to its name — that means it's already a facet. The `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, and `gen_ai.request.model` facets are typically promoted automatically by Datadog's LLM Observability auto-discovery, but verify they exist before importing the dashboard.
+  </Step>
+</Steps>
+
+## Import the dashboard
+
+<Steps>
+  <Step title="Download the dashboard JSON">
+    Save [`datadog_dashboard.json`](https://raw.githubusercontent.com/crewAIInc/crewAI/main/docs/edge/en/enterprise/guides/datadog_dashboard.json) to your machine.
+  </Step>
+  <Step title="Open the import dialog in Datadog">
+    Navigate to **Dashboards → New Dashboard**. Click the **gear icon** in the top right of the empty dashboard and select **Import Dashboard JSON**.
+  </Step>
+  <Step title="Paste or upload the JSON">
+    Paste the contents of `datadog_dashboard.json` into the import dialog (or drag the file in). Click **Import**.
+
+    Datadog creates the dashboard immediately and lands you on it. The first load may show empty widgets for a few seconds while queries execute against the time range.
+  </Step>
+</Steps>
+
+<Tip>
+  Datadog's [Dashboard API](https://docs.datadoghq.com/api/latest/dashboards/#create-a-new-dashboard) accepts the same JSON via `POST /api/v1/dashboard`. Use it if you manage dashboards through Terraform, Pulumi, or CI.
+</Tip>
+
+## What you get
+
+The dashboard is organized into four sections plus a placeholder for a custom drill-down widget:
+
+| Section | Widgets | Useful for |
+|---------|---------|------------|
+| **Header** | Total Executions · Error Rate (%) · Active Automations · CrewAI Versions in Use | At-a-glance health for the last hour. Error Rate is conditionally formatted (green ≤ 5%, yellow ≤ 10%, red > 10%). |
+| **Throughput** | Executions per Hour by Automation (top 10, stacked bars) | Spotting traffic shifts, surfacing busy automations, validating that a rollout didn't change baseline volume. |
+| **Errors** | Errors by Exception Type (top 5, stacked bars) · Top Exception Types by Count (toplist) | Triaging failures — which exception types are spiking, which automations they're hitting. |
+| **Cost** | Total Tokens per Hour by Model (input + output, stacked area) | Tracking LLM token spend by model. Useful for catching cost regressions when an automation switches model or starts looping. |
+| **Drill-Down** | _(empty placeholder)_ | See [Customization](#customize) for adding a recent-errors log stream here. |
+
+Three template variables at the top of the dashboard re-scope every widget at once:
+
+- **`$automation`** — filter to a single automation by name.
+- **`$version`** — filter to a single `crewai` SDK version (useful for comparing pre- and post-upgrade behavior).
+- **`$service`** — filter to a specific Datadog `service` tag (useful when multiple CrewAI deployments share one Datadog account).
+
+## Verify ingestion
+
+Open [Logs Explorer](https://app.datadoghq.com/logs) and run a query that matches your ingestion path:
+
+<Tabs>
+  <Tab title="Datadog Agent">
+    Search `service:crewai* @schema:v1`. You should see structured logs with the JSON fields parsed into Datadog facets. Pick a recent event and verify it has `@automation_id`, `@kickoff_id`, `@execution_id`, `@crewai_version`, and (when running inside a span) `@trace_id` / `@span_id` populated.
+
+    If nothing appears, confirm `CREWAI_LOG_FORMAT=json` is set under your automation's **Environment Variables** in AMP, the deployment was restarted after the change, and the Datadog Agent is tailing container stdout.
+  </Tab>
+  <Tab title="Datadog OTLP intake">
+    Search `source:otlp service:crewai*`. OTLP attributes land with their OpenTelemetry names (`automation_id`, `crewai.kickoff.id`, etc.) rather than the stdout JSON keys, but they map to the same dashboard facets after [facet promotion](#prerequisite-promote-facets).
+
+    If nothing appears, verify the collector endpoint is correct (`/v1/logs` for logs, `/v1/traces` for traces) and **Test Connection** succeeded when the collector was saved.
+  </Tab>
+</Tabs>
+
+## Customize
+
+The dashboard ships with deliberate gaps so you can extend it without uninstalling and re-importing.
+
+### Add a Recent Errors log stream
+
+The **Drill-Down** section is intentionally empty. Add a Log Stream widget to it for an inline view of recent failures:
+
+1. Edit the dashboard and click **+ Add Widgets** inside the Drill-Down group.
+2. Drag in a **Log Stream** widget.
+3. Set the filter query to `status:error $automation $version $service`.
+4. Choose columns: `@timestamp`, `@automation_name`, `@exception.type`, `@exception.message`, `@execution_id`.
+5. Sort by most recent, limit to 25 entries.
+
+Clicking any row jumps to Logs Explorer with the same filter pre-applied.
+
+### Add p95 latency
+
+Logs don't include execution duration by default. Two ways to add a latency widget:
+
+- **From APM traces** — if you also export OTLP traces to Datadog, add a Timeseries widget with data source **Traces**, query `service:crewai*`, aggregation `p95 of @duration`. Datadog APM auto-tracks span duration.
+- **From metric extraction** — extract a `flow.duration_ms` metric from logs via [Datadog's log-to-metric pipeline](https://docs.datadoghq.com/logs/log_configuration/logs_to_metrics/), then chart it like any other metric. Useful if you don't run APM.
+
+### Re-scope to multiple deployments
+
+The `$service` template variable defaults to `*` and will catch every CrewAI deployment in your Datadog account. Change the default to a specific service name in **Configure → Template Variables** if you want the dashboard to focus on one deployment by default.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| All widgets show "No data" | Facets aren't promoted | Re-do the [Promote facets](#prerequisite-promote-facets) step. Datadog won't query against an un-promoted field. |
+| Error Rate widget shows `NaN` | No executions in the time window | Either no traffic, or `@execution_id` isn't faceted. Expand the time range and re-check facets. |
+| Throughput chart is flat at the same value | Logs aren't reaching Datadog | Search `service:crewai*` in Logs Explorer. If nothing shows, verify the Datadog Agent is running (Agent path) or the OTel collector endpoint is correct (OTLP path). |
+| `crewai_version` shows fewer values than expected | Some containers predate the structured-logs work | The `crewai_version` field was added alongside JSON output. Older deployments running text mode (or older AMP builds) won't emit it. Upgrade those deployments to pick up the field. See the [log schema reference](#log-schema-reference) for the full field contract. |
+| Template variables don't filter widgets | The widget's filter line doesn't reference the template variable | Edit the widget and confirm the search includes `$automation $version $service`. |
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="OpenTelemetry Export" icon="magnifying-glass-chart" href="./capture_telemetry_logs">
+    Vendor-neutral observability for non-Datadog stacks (Grafana, Honeycomb, your own collector) — or as a Datadog complement when you want to fan out telemetry to multiple backends.
+  </Card>
+  <Card title="Datadog Log Search Syntax" icon="magnifying-glass" href="https://docs.datadoghq.com/logs/explorer/search_syntax/">
+    Reference for customizing widget queries against the structured facets above.
+  </Card>
+</CardGroup>

docs/v1.14.7/ar/enterprise/features/merged-step-card.mdx

@@ -0,0 +1,87 @@
+---
+title: بطاقة واحدة لكل خطوة
+description: "كل خطوة على لوحة Studio هي بطاقة واحدة تجمع بين المهمة والوكيل الذي ينفّذها."
+icon: "layer-group"
+mode: "wide"
+---
+
+{/* CLEANUP: This <Note> banner is the only time-bound content on the page. After the feature ships (Wednesday, June 24th 2026), delete the banner below — the rest of the page is evergreen present-tense docs and needs no other edits. */}
+<Note>
+  **الإطلاق يوم الأربعاء 24 يونيو.** تنتقل لوحة Studio إلى بطاقة واحدة لكل خطوة بدلاً من عُقد منفصلة للمهمة والوكيل، وذلك لتبسيط اللوحة مع إضافتنا لوظائف جديدة قريبًا. تستمر أتمتتك الحالية في العمل دون أي تغييرات مطلوبة — تبقى جميع إعدادات المهمة والوكيل متاحة، ولكن منظّمة في بطاقة واحدة.
+</Note>
+
+## نظرة عامة
+
+على لوحة Studio، تُمثَّل كل خطوة عمل بـ **بطاقة واحدة**. تجمع البطاقة بين عنصرين كانا في السابق في عُقد منفصلة:
+
+- **المهمة** — ماذا تفعل (الاسم، الوصف، المخرجات المتوقعة، وتنسيق الاستجابة).
+- **الوكيل** — من ينفّذها (الوكيل المُعيَّن ونموذجه وأدواته).
+
+الوكيل ليس مشاركًا مستقلاً في سير العمل لديك — بل هو سمة من سمات المهمة: *أي وكيل ينفّذ هذا العمل.* وضع المهمة والوكيل في بطاقة واحدة يجعل هذه العلاقة واضحة، ويحوّل أتمتتك إلى سلسلة واحدة من وحدات العمل من اليسار إلى اليمين يسهل قراءتها بنظرة واحدة.
+
+<Frame caption="بطاقة واحدة لكل خطوة: المهمة مع ملخص للوكيل المُعيَّن في التذييل.">
+  ![بطاقات الخطوات الموحّدة على اللوحة](/images/enterprise/merged-step-card-canvas.png)
+</Frame>
+
+## على اللوحة
+
+تعرض كل بطاقة مطوية ما يلي:
+
+- **اسم المهمة ووصفها** في الأعلى.
+- **تذييل يلخّص الوكيل المُعيَّن** — الصورة الرمزية والاسم والنموذج والأدوات.
+
+لا توجد عقدة وكيل منفصلة ولا حافة عمودية من الوكيل ← المهمة. تتصل خطواتك مباشرةً ببعضها البعض بالترتيب الذي تُنفَّذ به.
+
+## في المحرّر
+
+افتح بطاقة لتحريرها. العرض الموسّع هو البطاقة نفسها في حالة مفصّلة — وليس شاشة مختلفة — منظّمة في قسمين موسومين بوضوح.
+
+<Frame caption="المحرّر الموسّع: قسم المهمة مفتوح، والوكيل ملخّص أسفله.">
+  ![محرّر الخطوة الموسّع](/images/enterprise/merged-step-card-editor.png)
+</Frame>
+
+### المهمة — ماذا تفعل
+
+مفتوحة افتراضيًا، لأنها ما تحرّره عادةً:
+
+- **الاسم**
+- **الوصف**
+- **المخرجات المتوقعة**
+- **تنسيق الاستجابة** — يظهر هنا لأنه يتحكم تحديدًا في ما تقرأه الخطوات اللاحقة (مثل التوجيه) من هذه الخطوة.
+
+### الوكيل — من ينفّذها
+
+يُعرض الوكيل المُعيَّن كملخّص — **الاسم والنموذج والأدوات في سطر واحد**. ويُحفَظ إعداده الأعمق خلف قسمين قابلين للطي:
+
+- **الدور والهدف والخلفية**
+- **إعدادات الوكيل** — الاستدلال، الحد الأقصى لمحاولات الاستدلال، السماح بالتفويض، الحد الأقصى للتكرارات، وإعدادات LLM.
+
+<Tip>
+  الإعداد الكامل للوكيل — الدور، الهدف، الخلفية، النموذج، الأدوات، إعدادات LLM، وكامل كتلة إعدادات الوكيل — موجود خلف القسمين القابلين للطي **الدور والهدف والخلفية** و**إعدادات الوكيل**، منظّمًا حسب عدد مرّات تحريرك له.
+</Tip>
+
+## التبديل مقابل تحرير الوكيل
+
+هناك طريقتان متمايزتان للتعامل مع الوكيل في البطاقة، وكل منهما تؤدي وظيفة مختلفة:
+
+- **التبديل (Swap)** يعيد تعيين *أي* وكيل ينفّذ هذه المهمة. استخدم عنصر التحكم **تبديل** لاختيار وكيل مختلف من هذا المشروع، أو اختيار واحد من مستودع الوكلاء، أو إنشاء وكيل جديد. هذا مقصور على نطاق المهمة.
+- **تحرير** الوكيل — بفتح **الدور والهدف والخلفية** أو **إعدادات الوكيل** — يغيّر الوكيل *نفسه*.
+
+<Frame caption="التبديل يغيّر الوكيل الذي ينفّذ المهمة.">
+  ![لوحة تبديل الوكيل](/images/enterprise/merged-step-card-swap-agent.png)
+</Frame>
+
+<Warning>
+  **الوكلاء قابلون لإعادة الاستخدام ومشتركون.** يمكن للوكيل نفسه تنفيذ أكثر من مهمة عبر مشروعك. تحرير دور الوكيل أو خلفيته أو إعداداته يحدّث ذلك الوكيل **في كل مكان يُستخدم فيه** — وليس فقط في البطاقة التي فتحتها. إذا أردت تطبيق تغيير على خطوة واحدة فقط، فقم **بالتبديل** إلى وكيل مختلف بدلاً من تحرير الوكيل المشترك.
+</Warning>
+
+## ذات صلة
+
+<CardGroup cols={2}>
+  <Card title="Crew Studio" href="/ar/enterprise/features/crew-studio" icon="pencil">
+    أنشئ الأتمتة بمساعدة الذكاء الاصطناعي ومحرّر مرئي.
+  </Card>
+  <Card title="مستودعات الوكلاء" href="/ar/enterprise/features/agent-repositories" icon="users">
+    إدارة الوكلاء وإعادة استخدامهم عبر أتمتتك.
+  </Card>
+</CardGroup>

docs/v1.14.7/en/enterprise/features/merged-step-card.mdx

@@ -0,0 +1,87 @@
+---
+title: One Card per Step
+description: "Each step on the Studio canvas is a single card that combines the task and the agent that performs it."
+icon: "layer-group"
+mode: "wide"
+---
+
+{/* CLEANUP: This <Note> banner is the only time-bound content on the page. After the feature ships (Wednesday, June 24th 2026), delete the banner below — the rest of the page is evergreen present-tense docs and needs no other edits. */}
+<Note>
+  **Rolling out Wednesday, June 24th.** The Studio canvas is moving to one card per step instead of separate task and agent nodes, to streamline the canvas as we add new functionality soon. Your existing automations keep working with no changes needed — every task and agent setting is still available, just organized onto a single card.
+</Note>
+
+## Overview
+
+On the Studio canvas, each step of work is represented by a **single card**. The card combines two things that used to live in separate nodes:
+
+- **The task** — what to do (name, description, expected output, and response format).
+- **The agent** — who does it (the assigned agent, its model, and its tools).
+
+An agent isn't an independent participant in your workflow — it's an attribute of the task: *which agent performs this work.* Putting the task and its agent on one card makes that relationship explicit and turns your automation into a single, left-to-right chain of work units that's easier to read at a glance.
+
+<Frame caption="One card per step: the task with its assigned agent summarized in the footer.">
+  ![Merged step cards on the canvas](/images/enterprise/merged-step-card-canvas.png)
+</Frame>
+
+## On the canvas
+
+Each collapsed card shows:
+
+- The **task name and description** at the top.
+- A **footer summarizing the assigned agent** — avatar, name, model, and tools.
+
+There's no separate agent node and no vertical agent → task edge. Your steps connect directly to one another in the order they run.
+
+## In the editor
+
+Open a card to edit it. The expanded view is the same card in a detailed state — not a different screen — organized into two clearly labeled sections.
+
+<Frame caption="The expanded editor: the task section open, the agent summarized below it.">
+  ![Expanded step editor](/images/enterprise/merged-step-card-editor.png)
+</Frame>
+
+### The task — what to do
+
+Open by default, since this is what you usually edit:
+
+- **Name**
+- **Description**
+- **Expected Output**
+- **Response Format** — surfaced here because it controls exactly what downstream steps (such as routing) read from this step.
+
+### The agent — who does it
+
+The assigned agent is shown as a summary — **name, model, and tools inline**. Its deeper configuration is preserved behind two disclosures:
+
+- **Role, goal & backstory**
+- **Agent settings** — reasoning, max reasoning attempts, allow delegation, max iterations, and LLM settings.
+
+<Tip>
+  An agent's full configuration — Role, Goal, Backstory, Model, Tools, LLM Settings, and the complete Agent Settings block — lives behind the **Role, goal & backstory** and **Agent settings** disclosures, organized by how often you edit it.
+</Tip>
+
+## Swapping vs. editing the agent
+
+There are two distinct ways to work with the agent on a card, and they do different things:
+
+- **Swap** reassigns *which* agent performs this task. Use the **Swap** control to pick a different agent from this project, choose one from your Agent Repository, or create a new agent. This is scoped to the task.
+- **Editing** the agent — opening **Role, goal & backstory** or **Agent settings** — changes the agent *itself*.
+
+<Frame caption="Swap changes which agent performs the task.">
+  ![Swap agent panel](/images/enterprise/merged-step-card-swap-agent.png)
+</Frame>
+
+<Warning>
+  **Agents are reusable and shared.** The same agent can perform more than one task across your project. Editing an agent's role, backstory, or settings updates that agent **everywhere it's used** — not just on the card you opened. If you want a change to apply to only one step, **Swap** in a different agent instead of editing the shared one.
+</Warning>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Crew Studio" href="/en/enterprise/features/crew-studio" icon="pencil">
+    Build automations with AI assistance and a visual editor.
+  </Card>
+  <Card title="Agent Repositories" href="/en/enterprise/features/agent-repositories" icon="users">
+    Manage and reuse agents across your automations.
+  </Card>
+</CardGroup>

docs/v1.14.7/ko/enterprise/features/merged-step-card.mdx

@@ -0,0 +1,87 @@
+---
+title: 단계당 하나의 카드
+description: "Studio 캔버스의 각 단계는 작업과 이를 수행하는 에이전트를 하나로 결합한 단일 카드입니다."
+icon: "layer-group"
+mode: "wide"
+---
+
+{/* CLEANUP: This <Note> banner is the only time-bound content on the page. After the feature ships (Wednesday, June 24th 2026), delete the banner below — the rest of the page is evergreen present-tense docs and needs no other edits. */}
+<Note>
+  **6월 24일 수요일 출시.** Studio 캔버스가 작업과 에이전트를 별도의 노드로 표시하는 대신 단계당 하나의 카드로 전환됩니다. 곧 추가될 새로운 기능을 위해 캔버스를 간소화하기 위한 변경입니다. 기존 자동화는 아무런 변경 없이 그대로 동작하며, 모든 작업 및 에이전트 설정은 단일 카드에 정리되어 그대로 사용할 수 있습니다.
+</Note>
+
+## 개요
+
+Studio 캔버스에서 각 작업 단계는 **하나의 카드**로 표현됩니다. 이 카드는 이전에 별도의 노드에 있던 두 가지를 결합합니다:
+
+- **작업(Task)** — 무엇을 할지(이름, 설명, 예상 출력, 응답 형식).
+- **에이전트(Agent)** — 누가 수행하는지(할당된 에이전트, 모델, 도구).
+
+에이전트는 워크플로의 독립적인 참여자가 아니라 작업의 속성, 즉 *이 작업을 어떤 에이전트가 수행하는지*를 나타냅니다. 작업과 에이전트를 하나의 카드에 두면 이 관계가 명확해지고, 자동화가 왼쪽에서 오른쪽으로 이어지는 단일 작업 단위 체인이 되어 한눈에 읽기 쉬워집니다.
+
+<Frame caption="단계당 하나의 카드: 작업과 푸터에 요약된 할당 에이전트.">
+  ![캔버스의 통합 단계 카드](/images/enterprise/merged-step-card-canvas.png)
+</Frame>
+
+## 캔버스에서
+
+접힌 각 카드는 다음을 표시합니다:
+
+- 상단의 **작업 이름과 설명**.
+- **할당된 에이전트를 요약한 푸터** — 아바타, 이름, 모델, 도구.
+
+별도의 에이전트 노드나 에이전트 → 작업 세로 연결선이 없습니다. 각 단계는 실행 순서대로 서로 직접 연결됩니다.
+
+## 에디터에서
+
+카드를 열어 편집합니다. 확장된 보기는 다른 화면이 아니라 동일한 카드의 상세 상태이며, 명확하게 구분된 두 개의 섹션으로 구성됩니다.
+
+<Frame caption="확장된 에디터: 작업 섹션이 열려 있고 그 아래에 에이전트가 요약되어 있습니다.">
+  ![확장된 단계 에디터](/images/enterprise/merged-step-card-editor.png)
+</Frame>
+
+### 작업 — 무엇을 할지
+
+가장 자주 편집하는 항목이므로 기본적으로 열려 있습니다:
+
+- **이름**
+- **설명**
+- **예상 출력**
+- **응답 형식** — 다운스트림 단계(예: 라우팅)가 이 단계에서 무엇을 읽을지 정확히 제어하므로 여기에 표시됩니다.
+
+### 에이전트 — 누가 수행하는지
+
+할당된 에이전트는 요약으로 표시됩니다 — **이름, 모델, 도구가 인라인으로** 표시됩니다. 더 깊은 구성은 두 개의 접이식 섹션 뒤에 보존됩니다:
+
+- **역할, 목표 및 배경 스토리**
+- **에이전트 설정** — 추론, 최대 추론 시도 횟수, 위임 허용, 최대 반복 횟수, LLM 설정.
+
+<Tip>
+  에이전트의 전체 구성 — 역할, 목표, 배경 스토리, 모델, 도구, LLM 설정 및 전체 에이전트 설정 블록 — 은 **역할, 목표 및 배경 스토리**와 **에이전트 설정** 접이식 섹션 뒤에 편집 빈도에 따라 정리되어 있습니다.
+</Tip>
+
+## 에이전트 교체 vs. 편집
+
+카드에서 에이전트를 다루는 방식은 두 가지로 구분되며, 각각 다른 작업을 수행합니다:
+
+- **교체(Swap)** 는 *어떤* 에이전트가 이 작업을 수행할지 재할당합니다. **교체** 컨트롤을 사용하여 이 프로젝트의 다른 에이전트를 선택하거나, 에이전트 저장소에서 선택하거나, 새 에이전트를 만들 수 있습니다. 이는 작업 범위로 한정됩니다.
+- 에이전트 **편집** — **역할, 목표 및 배경 스토리** 또는 **에이전트 설정** 을 여는 것 — 은 에이전트 *자체*를 변경합니다.
+
+<Frame caption="교체는 작업을 수행할 에이전트를 변경합니다.">
+  ![에이전트 교체 패널](/images/enterprise/merged-step-card-swap-agent.png)
+</Frame>
+
+<Warning>
+  **에이전트는 재사용 가능하며 공유됩니다.** 동일한 에이전트가 프로젝트 전반에서 둘 이상의 작업을 수행할 수 있습니다. 에이전트의 역할, 배경 스토리 또는 설정을 편집하면 열어 본 카드뿐만 아니라 **해당 에이전트가 사용되는 모든 곳**에서 업데이트됩니다. 변경 사항을 하나의 단계에만 적용하려면 공유 에이전트를 편집하지 말고 다른 에이전트로 **교체**하세요.
+</Warning>
+
+## 관련 항목
+
+<CardGroup cols={2}>
+  <Card title="Crew Studio" href="/ko/enterprise/features/crew-studio" icon="pencil">
+    AI 지원과 비주얼 에디터로 자동화를 구축합니다.
+  </Card>
+  <Card title="에이전트 저장소" href="/ko/enterprise/features/agent-repositories" icon="users">
+    자동화 전반에서 에이전트를 관리하고 재사용합니다.
+  </Card>
+</CardGroup>

docs/v1.14.7/pt-BR/enterprise/features/merged-step-card.mdx

@@ -0,0 +1,87 @@
+---
+title: Um Card por Etapa
+description: "Cada etapa no canvas do Studio é um único card que combina a tarefa e o agente que a executa."
+icon: "layer-group"
+mode: "wide"
+---
+
+{/* CLEANUP: This <Note> banner is the only time-bound content on the page. After the feature ships (Wednesday, June 24th 2026), delete the banner below — the rest of the page is evergreen present-tense docs and needs no other edits. */}
+<Note>
+  **Lançamento na quarta-feira, 24 de junho.** O canvas do Studio passa a exibir um card por etapa, em vez de nós separados para tarefa e agente, para simplificar o canvas à medida que adicionamos novas funcionalidades em breve. Suas automações existentes continuam funcionando sem nenhuma alteração necessária — cada configuração de tarefa e de agente continua disponível, apenas organizada em um único card.
+</Note>
+
+## Visão geral
+
+No canvas do Studio, cada etapa de trabalho é representada por um **único card**. O card combina dois elementos que antes ficavam em nós separados:
+
+- **A tarefa** — o que fazer (nome, descrição, saída esperada e formato da resposta).
+- **O agente** — quem faz (o agente atribuído, seu modelo e suas ferramentas).
+
+Um agente não é um participante independente do seu fluxo de trabalho — ele é um atributo da tarefa: *qual agente executa este trabalho.* Colocar a tarefa e seu agente em um único card torna essa relação explícita e transforma sua automação em uma única cadeia de unidades de trabalho, da esquerda para a direita, mais fácil de ler em uma olhada.
+
+<Frame caption="Um card por etapa: a tarefa com o agente atribuído resumido no rodapé.">
+  ![Cards de etapa unificados no canvas](/images/enterprise/merged-step-card-canvas.png)
+</Frame>
+
+## No canvas
+
+Cada card recolhido mostra:
+
+- O **nome e a descrição da tarefa** no topo.
+- Um **rodapé resumindo o agente atribuído** — avatar, nome, modelo e ferramentas.
+
+Não há nó de agente separado nem aresta vertical de agente → tarefa. Suas etapas se conectam diretamente umas às outras na ordem em que são executadas.
+
+## No editor
+
+Abra um card para editá-lo. A visão expandida é o mesmo card em um estado detalhado — não uma tela diferente — organizada em duas seções claramente identificadas.
+
+<Frame caption="O editor expandido: a seção da tarefa aberta, com o agente resumido abaixo.">
+  ![Editor de etapa expandido](/images/enterprise/merged-step-card-editor.png)
+</Frame>
+
+### A tarefa — o que fazer
+
+Aberta por padrão, já que é o que você costuma editar:
+
+- **Nome**
+- **Descrição**
+- **Saída Esperada**
+- **Formato da Resposta** — exibido aqui porque controla exatamente o que as etapas seguintes (como o roteamento) leem desta etapa.
+
+### O agente — quem faz
+
+O agente atribuído é mostrado como um resumo — **nome, modelo e ferramentas em linha**. Sua configuração mais detalhada é preservada por trás de duas seções recolhíveis:
+
+- **Papel, objetivo e história**
+- **Configurações do agente** — raciocínio, máximo de tentativas de raciocínio, permitir delegação, máximo de iterações e configurações de LLM.
+
+<Tip>
+  A configuração completa de um agente — Papel, Objetivo, História, Modelo, Ferramentas, Configurações de LLM e todo o bloco de Configurações do agente — fica por trás das seções recolhíveis **Papel, objetivo e história** e **Configurações do agente**, organizada pela frequência com que você a edita.
+</Tip>
+
+## Trocar vs. editar o agente
+
+Há duas maneiras distintas de trabalhar com o agente em um card, e elas fazem coisas diferentes:
+
+- **Trocar** reatribui *qual* agente executa esta tarefa. Use o controle **Trocar** para escolher um agente diferente deste projeto, selecionar um do seu Repositório de Agentes ou criar um novo agente. Isso tem escopo limitado à tarefa.
+- **Editar** o agente — abrindo **Papel, objetivo e história** ou **Configurações do agente** — altera o agente *em si*.
+
+<Frame caption="Trocar muda qual agente executa a tarefa.">
+  ![Painel de troca de agente](/images/enterprise/merged-step-card-swap-agent.png)
+</Frame>
+
+<Warning>
+  **Os agentes são reutilizáveis e compartilhados.** O mesmo agente pode executar mais de uma tarefa em todo o seu projeto. Editar o papel, a história ou as configurações de um agente atualiza esse agente **em todos os lugares onde ele é usado** — não apenas no card que você abriu. Se quiser que uma alteração se aplique a apenas uma etapa, **Troque** por um agente diferente em vez de editar o agente compartilhado.
+</Warning>
+
+## Relacionados
+
+<CardGroup cols={2}>
+  <Card title="Crew Studio" href="/pt-BR/enterprise/features/crew-studio" icon="pencil">
+    Crie automações com assistência de IA e um editor visual.
+  </Card>
+  <Card title="Repositórios de Agentes" href="/pt-BR/enterprise/features/agent-repositories" icon="users">
+    Gerencie e reutilize agentes em suas automações.
+  </Card>
+</CardGroup>

lib/cli/pyproject.toml

@@ -8,7 +8,7 @@ authors = [
 ]
 requires-python = ">=3.10, <3.14"
 dependencies = [
-    "crewai-core==1.14.8a1",
+    "crewai-core==1.14.8a2",
     "click>=8.1.7,<9",
     "pydantic>=2.11.9,<2.13",
     "pydantic-settings~=2.10.1",

lib/cli/src/crewai_cli/__init__.py

@@ -1 +1 @@
-__version__ = "1.14.8a1"
+__version__ = "1.14.8a2"

lib/cli/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.8a1"
+    "crewai[tools]==1.14.8a2"
 ]
 
 [project.scripts]

lib/cli/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.8a1"
+    "crewai[tools]==1.14.8a2"
 ]
 
 [project.scripts]

lib/cli/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.8a1"
+    "crewai[tools]==1.14.8a2"
 ]
 
 [tool.crewai]

lib/crewai-core/src/crewai_core/__init__.py

@@ -1 +1 @@
-__version__ = "1.14.8a1"
+__version__ = "1.14.8a2"

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

@@ -152,4 +152,4 @@ __all__ = [
     "wrap_file_source",
 ]
 
-__version__ = "1.14.8a1"
+__version__ = "1.14.8a2"

lib/crewai-tools/pyproject.toml

@@ -10,7 +10,7 @@ requires-python = ">=3.10, <3.14"
 dependencies = [
     "pytube~=15.0.0",
     "requests>=2.33.0,<3",
-    "crewai==1.14.8a1",
+    "crewai==1.14.8a2",
     "tiktoken>=0.8.0,<0.13",
     "beautifulsoup4~=4.13.4",
     "python-docx~=1.2.0",
@@ -131,7 +131,7 @@ postgresql = [
 ]
 bedrock = [
     "beautifulsoup4>=4.13.4",
-    "bedrock-agentcore>=0.1.0",
+    "bedrock-agentcore>=1.7.0,<1.8.0",
     "playwright>=1.52.0",
     "nest-asyncio>=1.6.0",
 ]

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

@@ -330,4 +330,4 @@ __all__ = [
     "ZapierActionTools",
 ]
 
-__version__ = "1.14.8a1"
+__version__ = "1.14.8a2"

lib/crewai-tools/src/crewai_tools/security/safe_path.py

@@ -20,6 +20,82 @@ from urllib.parse import urlparse
 logger = logging.getLogger(__name__)
 
 _UNSAFE_PATHS_ENV = "CREWAI_TOOLS_ALLOW_UNSAFE_PATHS"
+_ALLOWED_DIRS_ENV = "CREWAI_TOOLS_ALLOWED_DIRS"
+
+
+def _get_allowed_roots(
+    base_dir: str | None = None,
+    allowed_dirs: list[str] | None = None,
+) -> list[str]:
+    """Build the deny-by-default set of allowed root directories.
+
+    Roots are drawn from, in order:
+
+    1. ``base_dir`` (defaults to the current working directory),
+    2. the ``CREWAI_TOOLS_ALLOWED_DIRS`` environment variable, split on
+       ``os.pathsep``,
+    3. the caller-supplied ``allowed_dirs`` list.
+
+    Every root is resolved with :func:`os.path.realpath` so a symlinked root
+    is compared by its real location. Empty entries are ignored and duplicates
+    are collapsed while preserving order. The first element is always the
+    primary root used to resolve relative candidate paths.
+
+    The filesystem root (``os.sep``, e.g. ``"/"``) is never accepted as an
+    *implicitly defaulted* root. When ``base_dir`` is not supplied and the
+    current working directory is ``/`` -- common in containers started without
+    a ``WORKDIR`` -- defaulting to it would make every absolute path "within"
+    the allow-list and disable confinement entirely. In that case the cwd
+    default is dropped; an operator who genuinely wants the whole filesystem
+    must opt in explicitly via ``base_dir``, ``allowed_dirs``, or
+    ``CREWAI_TOOLS_ALLOWED_DIRS``. If no usable root remains, a ``ValueError``
+    is raised rather than silently allowing everything.
+    """
+    primary_explicit = base_dir is not None
+    primary = base_dir if base_dir is not None else os.getcwd()
+
+    # (root, is_explicit) -- explicit roots are operator-provided and may
+    # legitimately include the filesystem root as an opt-in.
+    raw_roots: list[tuple[str, bool]] = [(primary, primary_explicit)]
+
+    env_dirs = os.environ.get(_ALLOWED_DIRS_ENV, "")
+    if env_dirs:
+        raw_roots.extend((d, True) for d in env_dirs.split(os.pathsep) if d)
+
+    if allowed_dirs:
+        raw_roots.extend((d, True) for d in allowed_dirs if d)
+
+    resolved: list[str] = []
+    seen: set[str] = set()
+    for root, is_explicit in raw_roots:
+        real = os.path.realpath(root)
+        if real == os.sep and not is_explicit:
+            # Refuse to let an unconfigured cwd of "/" open the whole filesystem.
+            continue
+        if real not in seen:
+            seen.add(real)
+            resolved.append(real)
+
+    if not resolved:
+        raise ValueError(
+            "No safe allowed directory could be determined: the current working "
+            f"directory is the filesystem root ('{os.sep}'). Set "
+            f"{_ALLOWED_DIRS_ENV} to an explicit directory, pass "
+            f"base_dir/allowed_dirs, or set {_UNSAFE_PATHS_ENV}=true to bypass "
+            "path validation."
+        )
+    return resolved
+
+
+def _is_within_root(resolved_path: str, resolved_root: str) -> bool:
+    """Return True if *resolved_path* equals *resolved_root* or lives beneath it.
+
+    When ``resolved_root`` already ends with a separator (e.g. the filesystem
+    root ``"/"``), appending ``os.sep`` would double it, so the root is used
+    as-is for the prefix in that case.
+    """
+    prefix = resolved_root if resolved_root.endswith(os.sep) else resolved_root + os.sep
+    return resolved_path == resolved_root or resolved_path.startswith(prefix)
 
 
 def format_path_for_display(path: str, base_dir: str | None = None) -> str:
@@ -52,21 +128,32 @@ def _is_escape_hatch_enabled() -> bool:
     return os.environ.get(_UNSAFE_PATHS_ENV, "").lower() in ("true", "1", "yes")
 
 
-def validate_file_path(path: str, base_dir: str | None = None) -> str:
+def validate_file_path(
+    path: str,
+    base_dir: str | None = None,
+    *,
+    allowed_dirs: list[str] | None = None,
+) -> str:
     """Validate that a file path is safe to read.
 
     Resolves symlinks and ``..`` components, then checks that the resolved
-    path falls within *base_dir* (defaults to the current working directory).
+    path falls within at least one allowed root directory. The allow-list is
+    built from *base_dir* (defaults to the current working directory), the
+    ``CREWAI_TOOLS_ALLOWED_DIRS`` environment variable, and *allowed_dirs* —
+    see :func:`_get_allowed_roots`. Access is denied by default for anything
+    outside that set.
 
     Args:
         path: The file path to validate.
-        base_dir: Allowed root directory. Defaults to ``os.getcwd()``.
+        base_dir: Primary allowed root. Defaults to ``os.getcwd()`` and is
+            used to resolve relative ``path`` values.
+        allowed_dirs: Additional allowed root directories.
 
     Returns:
         The resolved, validated absolute path.
 
     Raises:
-        ValueError: If the path escapes the allowed directory.
+        ValueError: If the path escapes every allowed directory.
     """
     if _is_escape_hatch_enabled():
         logger.warning(
@@ -76,30 +163,30 @@ def validate_file_path(path: str, base_dir: str | None = None) -> str:
         )
         return os.path.realpath(path)
 
-    if base_dir is None:
-        base_dir = os.getcwd()
+    allowed_roots = _get_allowed_roots(base_dir, allowed_dirs)
+    primary_root = allowed_roots[0]
 
-    resolved_base = os.path.realpath(base_dir)
     resolved_path = os.path.realpath(
-        os.path.join(resolved_base, path) if not os.path.isabs(path) else path
+        path if os.path.isabs(path) else os.path.join(primary_root, path)
     )
 
-    # Ensure the resolved path is within the base directory.
-    # When resolved_base already ends with a separator (e.g. the filesystem
-    # root "/"), appending os.sep would double it ("//"), so use the base
-    # as-is in that case.
-    prefix = resolved_base if resolved_base.endswith(os.sep) else resolved_base + os.sep
-    if not resolved_path.startswith(prefix) and resolved_path != resolved_base:
-        raise ValueError(
-            f"Path '{format_path_for_display(resolved_path, resolved_base)}' is "
-            f"outside the allowed directory. "
-            f"Set {_UNSAFE_PATHS_ENV}=true to bypass this check."
-        )
+    if any(_is_within_root(resolved_path, root) for root in allowed_roots):
+        return resolved_path
 
-    return resolved_path
+    raise ValueError(
+        f"Path '{format_path_for_display(resolved_path, primary_root)}' is "
+        f"outside the allowed directories. "
+        f"Add the directory via {_ALLOWED_DIRS_ENV}, or set "
+        f"{_UNSAFE_PATHS_ENV}=true to bypass this check."
+    )
 
 
-def validate_directory_path(path: str, base_dir: str | None = None) -> str:
+def validate_directory_path(
+    path: str,
+    base_dir: str | None = None,
+    *,
+    allowed_dirs: list[str] | None = None,
+) -> str:
     """Validate that a directory path is safe to read.
 
     Same as :func:`validate_file_path` but also checks that the path
@@ -107,15 +194,16 @@ def validate_directory_path(path: str, base_dir: str | None = None) -> str:
 
     Args:
         path: The directory path to validate.
-        base_dir: Allowed root directory. Defaults to ``os.getcwd()``.
+        base_dir: Primary allowed root. Defaults to ``os.getcwd()``.
+        allowed_dirs: Additional allowed root directories.
 
     Returns:
         The resolved, validated absolute path.
 
     Raises:
-        ValueError: If the path escapes the allowed directory or is not a directory.
+        ValueError: If the path escapes every allowed directory or is not a directory.
     """
-    validated = validate_file_path(path, base_dir)
+    validated = validate_file_path(path, base_dir, allowed_dirs=allowed_dirs)
     if not os.path.isdir(validated):
         raise ValueError(f"Path '{validated}' is not a directory.")
     return validated

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

@@ -1,5 +1,4 @@
 import os
-from pathlib import Path
 from typing import Any
 
 from crewai.tools import BaseTool
@@ -8,6 +7,7 @@ from pydantic import BaseModel
 from crewai_tools.security.safe_path import (
     format_error_for_display,
     format_path_for_display,
+    validate_file_path,
 )
 
 
@@ -41,22 +41,27 @@ class FileWriterTool(BaseTool):
 
             filepath = os.path.join(directory, filename)
 
-            # Prevent path traversal: the resolved path must be strictly inside
-            # filename, and symlink escapes regardless of how directory is set.
-            # is_relative_to() does a proper path-component comparison that is
-            # safe on case-insensitive filesystems and avoids the "// " edge case
-            # We also reject the case where filepath resolves to the directory
-            # itself, since that is not a valid file target.
-            real_directory = Path(directory).resolve()
-            real_filepath = Path(filepath).resolve()
-            display_filepath = format_path_for_display(
-                str(real_filepath), str(real_directory)
-            )
-            if (
-                not real_filepath.is_relative_to(real_directory)
-                or real_filepath == real_directory
-            ):
-                return "Error: Invalid file path — the filename must not escape the target directory."
+            # Confine the resolved write target to an allow-listed root
+            # (cwd + CREWAI_TOOLS_ALLOWED_DIRS), NOT merely inside the
+            # caller-supplied `directory`. That value is itself untrusted when
+            # an LLM tool call chooses it, so checking containment against it
+            # would let an agent write anywhere (e.g. ~/.ssh/authorized_keys).
+            # validate_file_path resolves symlinks and ".." before checking.
+            try:
+                real_filepath = validate_file_path(filepath)
+            except ValueError as e:
+                return f"Error: {format_error_for_display(e)}"
+
+            real_directory = os.path.dirname(real_filepath)
+            display_filepath = format_path_for_display(real_filepath, real_directory)
+
+            # A target that resolves to an existing directory is not a valid
+            # file destination.
+            if os.path.isdir(real_filepath):
+                return (
+                    "Error: Invalid file path — the target must be a file, "
+                    "not a directory."
+                )
 
             if kwargs.get("directory"):
                 os.makedirs(real_directory, exist_ok=True)

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

@@ -17,12 +17,23 @@ def temp_env():
     test_file = "test.txt"
     test_content = "Hello, World!"
 
+    # FileWriterTool confines writes to an allow-listed root (cwd plus
+    # CREWAI_TOOLS_ALLOWED_DIRS). Explicitly permit this temp dir — this is the
+    # supported way for a developer to widen the write scope to an external
+    # directory, and lets the happy-path tests below write into it.
+    prev_allowed = os.environ.get("CREWAI_TOOLS_ALLOWED_DIRS")
+    os.environ["CREWAI_TOOLS_ALLOWED_DIRS"] = temp_dir
+
     yield {
         "temp_dir": temp_dir,
         "test_file": test_file,
         "test_content": test_content,
     }
 
+    if prev_allowed is None:
+        os.environ.pop("CREWAI_TOOLS_ALLOWED_DIRS", None)
+    else:
+        os.environ["CREWAI_TOOLS_ALLOWED_DIRS"] = prev_allowed
     shutil.rmtree(temp_dir, ignore_errors=True)
 
 
@@ -196,3 +207,24 @@ def test_blocks_symlink_escape(tool, temp_env):
         assert not os.path.exists(outside_file)
     finally:
         shutil.rmtree(outside_dir, ignore_errors=True)
+
+
+
+def test_blocks_unbounded_directory_arg(tool, temp_env):
+    # The core fix: the `directory` argument is itself untrusted (LLM-chosen).
+    # A directory outside the allow-list must be rejected even when filename
+    # is benign — previously this let an agent write anywhere on disk
+    # (e.g. ~/.ssh/authorized_keys).
+    outside_dir = tempfile.mkdtemp()  # NOT added to CREWAI_TOOLS_ALLOWED_DIRS
+    outside_file = os.path.join(outside_dir, "test.txt")
+    try:
+        result = tool._run(
+            filename="test.txt",
+            directory=outside_dir,
+            content="should not be written",
+            overwrite=True,
+        )
+        assert "Error" in result
+        assert not os.path.exists(outside_file)
+    finally:
+        shutil.rmtree(outside_dir, ignore_errors=True)

lib/crewai-tools/tests/utilities/test_safe_path.py

@@ -32,12 +32,12 @@ class TestValidateFilePath:
 
     def test_rejects_dotdot_traversal(self, tmp_path):
         """Reject ../ traversal that escapes base_dir."""
-        with pytest.raises(ValueError, match="outside the allowed directory"):
+        with pytest.raises(ValueError, match="outside the allowed director"):
             validate_file_path("../../etc/passwd", str(tmp_path))
 
     def test_rejects_absolute_path_outside_base(self, tmp_path):
         """Reject absolute path outside base_dir."""
-        with pytest.raises(ValueError, match="outside the allowed directory"):
+        with pytest.raises(ValueError, match="outside the allowed directories"):
             validate_file_path("/etc/passwd", str(tmp_path))
 
     def test_allows_absolute_path_inside_base(self, tmp_path):
@@ -50,7 +50,7 @@ class TestValidateFilePath:
         """Reject symlinks that point outside base_dir."""
         link = tmp_path / "sneaky_link"
         os.symlink("/etc/passwd", str(link))
-        with pytest.raises(ValueError, match="outside the allowed directory"):
+        with pytest.raises(ValueError, match="outside the allowed directories"):
             validate_file_path("sneaky_link", str(tmp_path))
 
     def test_defaults_to_cwd(self):
@@ -113,7 +113,7 @@ class TestValidateDirectoryPath:
             validate_directory_path("file.txt", str(tmp_path))
 
     def test_rejects_traversal(self, tmp_path):
-        with pytest.raises(ValueError, match="outside the allowed directory"):
+        with pytest.raises(ValueError, match="outside the allowed directories"):
             validate_directory_path("../../", str(tmp_path))
 
 
@@ -191,3 +191,95 @@ class TestValidateUrl:
         # file:// would normally be blocked
         result = validate_url("file:///etc/passwd")
         assert result == "file:///etc/passwd"
+
+
+
+class TestAllowList:
+    """Tests for the configurable deny-by-default allow-list of roots."""
+
+    def test_param_extends_allowed_roots(self, tmp_path):
+        """A directory passed via allowed_dirs is permitted."""
+        extra = tmp_path / "extra"
+        extra.mkdir()
+        (extra / "data.txt").touch()
+        result = validate_file_path(
+            str(extra / "data.txt"),
+            base_dir=str(tmp_path / "base"),
+            allowed_dirs=[str(extra)],
+        )
+        assert result == str(extra / "data.txt")
+
+    def test_env_extends_allowed_roots(self, tmp_path, monkeypatch):
+        """A directory listed in CREWAI_TOOLS_ALLOWED_DIRS is permitted."""
+        base = tmp_path / "base"
+        base.mkdir()
+        extra = tmp_path / "extra"
+        extra.mkdir()
+        (extra / "data.txt").touch()
+        monkeypatch.setenv("CREWAI_TOOLS_ALLOWED_DIRS", str(extra))
+        result = validate_file_path(str(extra / "data.txt"), base_dir=str(base))
+        assert result == str(extra / "data.txt")
+
+    def test_denied_without_allow_listing(self, tmp_path, monkeypatch):
+        """The same external dir is rejected when not allow-listed."""
+        base = tmp_path / "base"
+        base.mkdir()
+        extra = tmp_path / "extra"
+        extra.mkdir()
+        (extra / "data.txt").touch()
+        monkeypatch.delenv("CREWAI_TOOLS_ALLOWED_DIRS", raising=False)
+        with pytest.raises(ValueError, match="outside the allowed directories"):
+            validate_file_path(str(extra / "data.txt"), base_dir=str(base))
+
+    def test_multiple_env_roots(self, tmp_path, monkeypatch):
+        """Multiple os.pathsep-separated roots are each honored."""
+        base = tmp_path / "base"
+        base.mkdir()
+        a = tmp_path / "a"
+        a.mkdir()
+        b = tmp_path / "b"
+        b.mkdir()
+        (a / "fa.txt").touch()
+        (b / "fb.txt").touch()
+        monkeypatch.setenv(
+            "CREWAI_TOOLS_ALLOWED_DIRS", os.pathsep.join([str(a), str(b)])
+        )
+        assert validate_file_path(str(a / "fa.txt"), base_dir=str(base)) == str(
+            a / "fa.txt"
+        )
+        assert validate_file_path(str(b / "fb.txt"), base_dir=str(base)) == str(
+            b / "fb.txt"
+        )
+
+    def test_cwd_root_default_is_not_an_allowed_root(self, tmp_path, monkeypatch):
+        """An unconfigured cwd of '/' must not open the whole filesystem.
+
+        Regression for the deny-by-default allow-list silently defaulting to the
+        filesystem root in containers started without a WORKDIR.
+        """
+        monkeypatch.delenv("CREWAI_TOOLS_ALLOWED_DIRS", raising=False)
+        monkeypatch.delenv("CREWAI_TOOLS_ALLOW_UNSAFE_PATHS", raising=False)
+        monkeypatch.setattr(os, "getcwd", lambda: os.sep)
+        with pytest.raises(ValueError, match="filesystem root"):
+            validate_file_path("/etc/passwd")
+
+    def test_cwd_root_with_explicit_allowed_dirs_confines(
+        self, tmp_path, monkeypatch
+    ):
+        """With cwd '/', confinement falls back to the explicit allow-list."""
+        monkeypatch.delenv("CREWAI_TOOLS_ALLOWED_DIRS", raising=False)
+        monkeypatch.setattr(os, "getcwd", lambda: os.sep)
+        (tmp_path / "data.txt").touch()
+        assert validate_file_path(
+            str(tmp_path / "data.txt"), allowed_dirs=[str(tmp_path)]
+        ) == str(tmp_path / "data.txt")
+        with pytest.raises(ValueError, match="outside the allowed directories"):
+            validate_file_path("/etc/passwd", allowed_dirs=[str(tmp_path)])
+
+    def test_explicit_base_dir_root_is_opt_in(self, monkeypatch):
+        """An explicit base_dir of '/' is honored as a deliberate opt-in."""
+        monkeypatch.delenv("CREWAI_TOOLS_ALLOWED_DIRS", raising=False)
+        monkeypatch.delenv("CREWAI_TOOLS_ALLOW_UNSAFE_PATHS", raising=False)
+        assert validate_file_path("/etc/passwd", base_dir=os.sep) == os.path.realpath(
+            "/etc/passwd"
+        )

lib/crewai/pyproject.toml

@@ -8,8 +8,8 @@ authors = [
 ]
 requires-python = ">=3.10, <3.14"
 dependencies = [
-    "crewai-core==1.14.8a1",
-    "crewai-cli==1.14.8a1",
+    "crewai-core==1.14.8a2",
+    "crewai-cli==1.14.8a2",
     # Core Dependencies
     "pydantic>=2.11.9,<2.13",
     "openai>=2.30.0,<3",
@@ -55,7 +55,7 @@ Repository = "https://github.com/crewAIInc/crewAI"
 
 [project.optional-dependencies]
 tools = [
-    "crewai-tools==1.14.8a1",
+    "crewai-tools==1.14.8a2",
 ]
 embeddings = [
     "tiktoken>=0.8.0,<0.13"
@@ -78,8 +78,8 @@ qdrant = [
     "qdrant-client[fastembed]~=1.14.3",
 ]
 aws = [
-    "boto3~=1.42.79",
-    "aiobotocore~=3.4.0",
+    "boto3~=1.42.90",
+    "aiobotocore~=3.5.0",
 ]
 watson = [
     "ibm-watsonx-ai~=1.3.39",
@@ -91,7 +91,7 @@ litellm = [
     "litellm>=1.84.0,<2",
 ]
 bedrock = [
-    "boto3~=1.42.79",
+    "boto3~=1.42.90",
 ]
 google-genai = [
     "google-genai~=1.65.0",

lib/crewai/src/crewai/__init__.py

@@ -48,7 +48,7 @@ def _suppress_pydantic_deprecation_warnings() -> None:
 
 _suppress_pydantic_deprecation_warnings()
 
-__version__ = "1.14.8a1"
+__version__ = "1.14.8a2"
 
 _LAZY_IMPORTS: dict[str, tuple[str, str]] = {
     "Memory": ("crewai.memory.unified_memory", "Memory"),

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

@@ -57,6 +57,7 @@ from crewai.utilities.agent_utils import (
     convert_tools_to_openai_schema,
     enforce_rpm_limit,
     format_message_for_llm,
+    format_native_tool_output_for_agent,
     get_llm_response,
     handle_agent_action_core,
     handle_context_length,
@@ -907,19 +908,31 @@ class CrewAgentExecutor(BaseAgentExecutor):
         ):
             max_usage_reached = True
 
+        structured_tool: CrewStructuredTool | None = None
+        if original_tool is not None:
+            for structured in self.tools or []:
+                if getattr(structured, "_original_tool", None) is original_tool:
+                    structured_tool = structured
+                    break
+        if structured_tool is None:
+            for structured in self.tools or []:
+                if sanitize_tool_name(structured.name) == func_name:
+                    structured_tool = structured
+                    break
+
+        output_tool = original_tool or structured_tool
+
         from_cache = False
         result: str = "Tool not found"
+        raw_tool_result: Any = result
         input_str = json.dumps(args_dict) if args_dict else ""
-        if self.tools_handler and self.tools_handler.cache:
+        if self.tools_handler and self.tools_handler.cache and output_tool is not None:
             cached_result = self.tools_handler.cache.read(
                 tool=func_name, input=input_str
             )
             if cached_result is not None:
-                result = (
-                    str(cached_result)
-                    if not isinstance(cached_result, str)
-                    else cached_result
-                )
+                raw_tool_result = cached_result
+                result = format_native_tool_output_for_agent(output_tool, cached_result)
                 from_cache = True
 
         agent_key = getattr(self.agent, "key", "unknown") if self.agent else "unknown"
@@ -938,18 +951,6 @@ class CrewAgentExecutor(BaseAgentExecutor):
 
         track_delegation_if_needed(func_name, args_dict or {}, self.task)
 
-        structured_tool: CrewStructuredTool | None = None
-        if original_tool is not None:
-            for structured in self.tools or []:
-                if getattr(structured, "_original_tool", None) is original_tool:
-                    structured_tool = structured
-                    break
-        if structured_tool is None:
-            for structured in self.tools or []:
-                if sanitize_tool_name(structured.name) == func_name:
-                    structured_tool = structured
-                    break
-
         hook_blocked = False
         before_hook_context = ToolCallHookContext(
             tool_name=func_name,
@@ -975,11 +976,18 @@ class CrewAgentExecutor(BaseAgentExecutor):
 
         if hook_blocked:
             result = f"Tool execution blocked by hook. Tool: {func_name}"
+            raw_tool_result = result
         elif max_usage_reached and original_tool:
             result = f"Tool '{func_name}' has reached its usage limit of {original_tool.max_usage_count} times and cannot be used anymore."
-        elif not from_cache and func_name in available_functions:
+            raw_tool_result = result
+        elif (
+            not from_cache
+            and func_name in available_functions
+            and output_tool is not None
+        ):
             try:
                 raw_result = available_functions[func_name](**(args_dict or {}))
+                raw_tool_result = raw_result
 
                 if self.tools_handler and self.tools_handler.cache:
                     should_cache = True
@@ -996,11 +1004,10 @@ class CrewAgentExecutor(BaseAgentExecutor):
                             tool=func_name, input=input_str, output=raw_result
                         )
 
-                result = (
-                    str(raw_result) if not isinstance(raw_result, str) else raw_result
-                )
+                result = format_native_tool_output_for_agent(output_tool, raw_result)
             except Exception as e:
                 result = f"Error executing tool: {e}"
+                raw_tool_result = result
                 if self.task:
                     self.task.increment_tools_errors()
                 crewai_event_bus.emit(
@@ -1024,6 +1031,7 @@ class CrewAgentExecutor(BaseAgentExecutor):
             task=self.task,
             crew=self.crew,
             tool_result=result,
+            raw_tool_result=raw_tool_result,
         )
         after_hooks = get_after_tool_call_hooks()
         try:

lib/crewai/src/crewai/agents/tools_handler.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+from typing import Any
 
 from pydantic import BaseModel, Field
 
@@ -25,14 +26,14 @@ class ToolsHandler(BaseModel):
     def on_tool_use(
         self,
         calling: ToolCalling | InstructorToolCalling,
-        output: str,
+        output: Any,
         should_cache: bool = True,
     ) -> None:
         """Run when tool ends running.
 
         Args:
             calling: The tool calling instance.
-            output: The output from the tool execution.
+            output: The raw output from the tool execution.
             should_cache: Whether to cache the tool output.
         """
         self.last_used_tool = calling

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

@@ -80,6 +80,7 @@ from crewai.utilities.agent_utils import (
     enforce_rpm_limit,
     extract_tool_call_info,
     format_message_for_llm,
+    format_native_tool_output_for_agent,
     get_llm_response,
     handle_agent_action_core,
     handle_context_length,
@@ -1905,19 +1906,32 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):
         ):
             max_usage_reached = True
 
+        structured_tool: CrewStructuredTool | None = None
+        if original_tool is not None:
+            for structured in self.tools or []:
+                if getattr(structured, "_original_tool", None) is original_tool:
+                    structured_tool = structured
+                    break
+        if structured_tool is None:
+            for structured in self.tools or []:
+                if sanitize_tool_name(structured.name) == func_name:
+                    structured_tool = structured
+                    break
+
+        output_tool = original_tool or structured_tool
+
         # Check cache before executing
         from_cache = False
+        result = "Tool not found"
+        raw_tool_result: Any = result
         input_str = json.dumps(args_dict) if args_dict else ""
-        if self.tools_handler and self.tools_handler.cache:
+        if self.tools_handler and self.tools_handler.cache and output_tool is not None:
             cached_result = self.tools_handler.cache.read(
                 tool=func_name, input=input_str
             )
             if cached_result is not None:
-                result = (
-                    str(cached_result)
-                    if not isinstance(cached_result, str)
-                    else cached_result
-                )
+                raw_tool_result = cached_result
+                result = format_native_tool_output_for_agent(output_tool, cached_result)
                 from_cache = True
 
         # Emit tool usage started event
@@ -1936,18 +1950,6 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):
 
         track_delegation_if_needed(func_name, args_dict, self.task)
 
-        structured_tool: CrewStructuredTool | None = None
-        if original_tool is not None:
-            for structured in self.tools or []:
-                if getattr(structured, "_original_tool", None) is original_tool:
-                    structured_tool = structured
-                    break
-        if structured_tool is None:
-            for structured in self.tools or []:
-                if sanitize_tool_name(structured.name) == func_name:
-                    structured_tool = structured
-                    break
-
         hook_blocked = False
         before_hook_context = ToolCallHookContext(
             tool_name=func_name,
@@ -1973,12 +1975,13 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):
 
         if hook_blocked:
             result = f"Tool execution blocked by hook. Tool: {func_name}"
-        elif not from_cache and not max_usage_reached:
-            result = "Tool not found"
+            raw_tool_result = result
+        elif not from_cache and not max_usage_reached and output_tool is not None:
             if func_name in self._available_functions:
                 try:
                     tool_func = self._available_functions[func_name]
                     raw_result = tool_func(**args_dict)
+                    raw_tool_result = raw_result
 
                     # Add to cache after successful execution (before string conversion)
                     if self.tools_handler and self.tools_handler.cache:
@@ -1992,14 +1995,12 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):
                                 tool=func_name, input=input_str, output=raw_result
                             )
 
-                    # Convert to string for message
-                    result = (
-                        str(raw_result)
-                        if not isinstance(raw_result, str)
-                        else raw_result
+                    result = format_native_tool_output_for_agent(
+                        output_tool, raw_result
                     )
                 except Exception as e:
                     result = f"Error executing tool: {e}"
+                    raw_tool_result = result
                     if self.task:
                         self.task.increment_tools_errors()
                     # Emit tool usage error event
@@ -2021,6 +2022,7 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):
                 result = f"Tool '{func_name}' has reached its usage limit of {original_tool.max_usage_count} times and cannot be used anymore."
             else:
                 result = f"Tool '{func_name}' has reached its maximum usage limit and cannot be used anymore."
+            raw_tool_result = result
 
         # Execute after_tool_call hooks (even if blocked, to allow logging/monitoring)
         after_hook_context = ToolCallHookContext(
@@ -2031,6 +2033,7 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):
             task=self.task,
             crew=self.crew,
             tool_result=result,
+            raw_tool_result=raw_tool_result,
         )
         after_hooks = get_after_tool_call_hooks()
         try:

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

@@ -10,6 +10,7 @@ from crewai.flow.conversation import (
     ConversationalInputs,
 )
 from crewai.flow.dsl import HumanFeedbackResult, human_feedback
+from crewai.flow.expressions import Expression
 from crewai.flow.flow import Flow, and_, listen, or_, router, start
 from crewai.flow.flow_config import flow_config
 from crewai.flow.input_provider import InputProvider, InputResponse
@@ -26,6 +27,7 @@ __all__ = [
     "ConsoleProvider",
     "ConversationalConfig",
     "ConversationalInputs",
+    "Expression",
     "Flow",
     "FlowStructure",
     "HumanFeedbackPending",

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

@@ -0,0 +1,329 @@
+"""Runtime expression support for FlowDefinition CEL expressions."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+import json
+from typing import TYPE_CHECKING, Any, TypeAlias, cast
+
+from crewai.utilities.serialization import to_serializable
+
+
+if TYPE_CHECKING:
+    from crewai.flow.runtime import Flow
+else:
+    from typing_extensions import TypeAliasType
+
+
+_CEL_MACROS_WITH_LOCAL_BINDINGS = frozenset(
+    {"all", "exists", "exists_one", "filter", "map"}
+)
+if TYPE_CHECKING:
+    ExpressionData: TypeAlias = (
+        str
+        | int
+        | float
+        | bool
+        | None
+        | list["ExpressionData"]
+        | dict[str, "ExpressionData"]
+    )
+else:
+    ExpressionData = TypeAliasType(
+        "ExpressionData",
+        str
+        | int
+        | float
+        | bool
+        | None
+        | list["ExpressionData"]
+        | dict[str, "ExpressionData"],
+    )
+
+__all__ = [
+    "Expression",
+    "ExpressionData",
+    "ExpressionError",
+]
+
+
+class ExpressionError(ValueError):
+    """An expression failed to parse, validate, render, or evaluate."""
+
+
+class Expression:
+    """CEL expression helper used for definition-time checks and runtime rendering."""
+
+    def __init__(
+        self, value: ExpressionData, *, context: dict[str, Any] | None = None
+    ) -> None:
+        self.value = value
+        self.context = context
+
+    @classmethod
+    def from_flow(
+        cls,
+        value: ExpressionData,
+        flow: Flow[Any],
+        *,
+        local_context: dict[str, Any] | None = None,
+    ) -> Expression:
+        """Build an expression with the standard Flow runtime context."""
+        return cls(value, context=cls._flow_context(flow, local_context=local_context))
+
+    def validate_expression(
+        self,
+        *,
+        allowed_roots: Iterable[str],
+        source: str = "CEL expression",
+    ) -> None:
+        """Validate a full CEL expression without evaluating it."""
+        allowed = frozenset(allowed_roots)
+        expression = self._require_cel_source(cast(str, self.value), source=source)
+        roots = self._collect_root_identifiers(
+            self._compile_cel(expression, source=source)
+        )
+        unknown = sorted(root for root in roots if root not in allowed)
+        if unknown:
+            allowed_list = ", ".join(sorted(allowed))
+            unknown_list = ", ".join(repr(root) for root in unknown)
+            raise ExpressionError(
+                f"unknown CEL root at {source}: {unknown_list}; "
+                f"allowed roots: {allowed_list}. Reference flow data through one "
+                "of those roots, for example state.field or outputs.step_name."
+            )
+
+    def validate_template(
+        self,
+        *,
+        allowed_roots: Iterable[str],
+        source: str = "with block",
+    ) -> None:
+        """Validate nested strings fully wrapped in ``${...}`` as CEL."""
+        self._validate_template_value(
+            self.value, allowed_roots=allowed_roots, source=source
+        )
+
+    def evaluate(self, context: dict[str, Any] | None = None) -> Any:
+        """Evaluate this value as a full CEL expression."""
+        resolved_context = self.context if context is None else context
+        return self._evaluate_cel(
+            self._require_cel_source(cast(str, self.value)),
+            resolved_context or {},
+        )
+
+    def render_template(self, context: dict[str, Any] | None = None) -> Any:
+        """Evaluate nested strings fully wrapped in ``${...}`` as CEL."""
+        resolved_context = self.context if context is None else context
+        return self._render_template_value(self.value, resolved_context or {})
+
+    @staticmethod
+    def _validate_template_value(
+        value: ExpressionData,
+        *,
+        allowed_roots: Iterable[str],
+        source: str,
+    ) -> None:
+        if isinstance(value, str):
+            expression = Expression._expression_marker_source(value, source=source)
+            if expression is not None:
+                Expression(expression).validate_expression(
+                    allowed_roots=allowed_roots, source=source
+                )
+            return
+        if isinstance(value, dict):
+            for key, item in value.items():
+                item_source = f"{source}.{key}" if isinstance(key, str) else source
+                Expression._validate_template_value(
+                    item, allowed_roots=allowed_roots, source=item_source
+                )
+            return
+        if isinstance(value, list):
+            for index, item in enumerate(value):
+                Expression._validate_template_value(
+                    item,
+                    allowed_roots=allowed_roots,
+                    source=f"{source}[{index}]",
+                )
+
+    @staticmethod
+    def _flow_context(
+        flow: Flow[Any], local_context: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        from crewai.flow.runtime._outputs import outputs_by_name
+
+        local_outputs = local_context.get("outputs") if local_context else None
+        outputs = outputs_by_name(
+            flow._method_outputs,
+            local_outputs=local_outputs,
+            serialize=True,
+        )
+        context: dict[str, Any] = {
+            "state": flow._copy_and_serialize_state(),
+            "outputs": outputs,
+        }
+        if local_context:
+            context.update(
+                {
+                    key: to_serializable(value, max_depth=0)
+                    for key, value in local_context.items()
+                    if key not in {"outputs", "state"}
+                }
+            )
+        return context
+
+    @staticmethod
+    def _render_template_value(value: ExpressionData, context: dict[str, Any]) -> Any:
+        if isinstance(value, str):
+            return Expression._render_template_string(value, context)
+        if isinstance(value, dict):
+            return {
+                key: Expression._render_template_value(item, context)
+                for key, item in value.items()
+            }
+        if isinstance(value, list):
+            return [Expression._render_template_value(item, context) for item in value]
+        return value
+
+    @staticmethod
+    def _render_template_string(value: str, context: dict[str, Any]) -> Any:
+        expression = Expression._expression_marker_source(value)
+        if expression is None:
+            return value
+        return Expression._evaluate_cel(expression, context)
+
+    @staticmethod
+    def _expression_marker_source(
+        value: str, *, source: str | None = None
+    ) -> str | None:
+        """Return CEL source when the trimmed string starts with ``${`` and ends with ``}``."""
+        stripped = value.strip()
+        if not stripped.startswith("${"):
+            return None
+        if not stripped.endswith("}"):
+            return None
+
+        expression = stripped[2:-1].strip()
+        if not expression:
+            if source is None:
+                raise ExpressionError("empty CEL expression in with block")
+            raise ExpressionError(f"empty CEL expression at {source}")
+        return expression
+
+    @staticmethod
+    def _evaluate_cel(expression: str, context: dict[str, Any]) -> Any:
+        try:
+            from celpy import Environment
+            from celpy.adapter import CELJSONEncoder, json_to_cel
+            from celpy.evaluation import Context
+
+            environment = Environment()
+            program = environment.program(
+                Expression._compile_cel(expression, environment=environment)
+            )
+            result = program.evaluate(cast(Context, json_to_cel(context)))
+            return json.loads(json.dumps(result, cls=CELJSONEncoder))
+        except Exception as e:
+            raise ExpressionError(
+                f"failed to evaluate CEL expression {expression!r}: {e}"
+            ) from e
+
+    @staticmethod
+    def _compile_cel(
+        expression: str,
+        *,
+        source: str | None = None,
+        environment: Any | None = None,
+    ) -> Any:
+        if environment is None:
+            from celpy import Environment
+
+            environment = Environment()
+        try:
+            return environment.compile(expression)
+        except Exception as e:
+            if source is None:
+                raise
+            raise ExpressionError(
+                f"invalid CEL expression at {source}: {expression!r}. "
+                f"Check the CEL syntax. Parser details: {e}"
+            ) from e
+
+    @staticmethod
+    def _require_cel_source(value: str, *, source: str | None = None) -> str:
+        expression = value.strip()
+        if expression.startswith("${") and expression.endswith("}"):
+            expression = expression[2:-1].strip()
+        if expression:
+            return expression
+        if source is None:
+            raise ExpressionError("empty CEL expression")
+        raise ExpressionError(
+            f"empty CEL expression at {source}. Provide a CEL expression such as "
+            "state.topic or outputs.step_name."
+        )
+
+    @staticmethod
+    def _collect_root_identifiers(
+        tree: Any, local_roots: frozenset[str] = frozenset()
+    ) -> set[str]:
+        """Collect CEL root identifiers, excluding receiver macro local variables."""
+        data = getattr(tree, "data", None)
+        children = list(getattr(tree, "children", []) or [])
+
+        if data == "ident" and children:
+            name = str(children[0])
+            return set() if name in local_roots else {name}
+
+        if data == "ident_arg":
+            return Expression._collect_root_identifiers_from(
+                children[1:], local_roots=local_roots
+            )
+
+        if data == "member_dot_arg":
+            roots = (
+                Expression._collect_root_identifiers(children[0], local_roots)
+                if children
+                else set()
+            )
+            nested_locals = frozenset(
+                {*local_roots, *Expression._receiver_macro_local_roots(children)}
+            )
+            roots.update(
+                Expression._collect_root_identifiers_from(
+                    children[2:], local_roots=nested_locals
+                )
+            )
+            return roots
+
+        return Expression._collect_root_identifiers_from(
+            children, local_roots=local_roots
+        )
+
+    @staticmethod
+    def _collect_root_identifiers_from(
+        trees: Iterable[Any], *, local_roots: frozenset[str]
+    ) -> set[str]:
+        return set().union(
+            *(Expression._collect_root_identifiers(tree, local_roots) for tree in trees)
+        )
+
+    @staticmethod
+    def _receiver_macro_local_roots(children: list[Any]) -> set[str]:
+        if len(children) < 3 or str(children[1]) not in _CEL_MACROS_WITH_LOCAL_BINDINGS:
+            return set()
+        exprlist = children[2]
+        exprs = list(getattr(exprlist, "children", []) or [])
+        if exprs and (name := Expression._single_identifier_name(exprs[0])):
+            return {name}
+        return set()
+
+    @staticmethod
+    def _single_identifier_name(tree: Any) -> str | None:
+        data = getattr(tree, "data", None)
+        children = list(getattr(tree, "children", []) or [])
+        if data == "ident" and children:
+            return str(children[0])
+        if len(children) != 1:
+            return None
+        return Expression._single_identifier_name(children[0])

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

@@ -12,7 +12,7 @@ from __future__ import annotations
 import json
 import logging
 import re
-from typing import Annotated, Any, Literal, TypeAlias
+from typing import Annotated, Any, Literal, TypeAlias, cast
 
 from pydantic import (
     BaseModel,
@@ -27,16 +27,20 @@ from crewai.flow.conversational_definition import (
     FlowConversationalDefinition,
     FlowConversationalRouterDefinition,
 )
-from crewai.project.crew_definition import CrewDefinition
+from crewai.flow.expressions import ExpressionData
+from crewai.project.crew_definition import AgentDefinition, CrewDefinition
 
 
 logger = logging.getLogger(__name__)
 
 FlowDefinitionCondition = str | dict[str, Any]
 _STEP_NAME_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+_BASE_CEL_ROOTS = frozenset({"outputs", "state"})
+_EACH_STEP_CEL_ROOTS = frozenset({"item", "outputs", "state"})
 
 __all__ = [
     "FlowActionDefinition",
+    "FlowAgentActionDefinition",
     "FlowAtomicActionDefinition",
     "FlowCodeActionDefinition",
     "FlowConfigDefinition",
@@ -353,10 +357,14 @@ class FlowCodeActionDefinition(BaseModel):
         description="Import reference for the callable, formatted as module:qualname.",
         examples=["my_project.flows:normalize_topic"],
     )
-    with_: dict[str, Any] | None = Field(
+    with_: dict[str, ExpressionData] | None = Field(
         default=None,
         alias="with",
-        description="Keyword arguments passed to the callable after expression rendering.",
+        description=(
+            "Keyword arguments passed to the callable. String values are evaluated "
+            "as CEL only when the trimmed value starts with ${ and ends with }; "
+            "all other values are literal."
+        ),
         examples=[{"topic": "${state.topic}"}],
     )
 
@@ -377,10 +385,14 @@ class FlowToolActionDefinition(BaseModel):
         description="Import reference for a BaseTool class, formatted as module:qualname.",
         examples=["my_project.tools:SearchTool"],
     )
-    with_: dict[str, Any] | None = Field(
+    with_: dict[str, ExpressionData] | None = Field(
         default=None,
         alias="with",
-        description="Tool input arguments after expression rendering.",
+        description=(
+            "Tool input arguments. String values are evaluated as CEL only when "
+            "the trimmed value starts with ${ and ends with }; all other values "
+            "are literal."
+        ),
         examples=[{"query": "${outputs.normalize_topic}", "limit": 5}],
     )
 
@@ -424,6 +436,33 @@ class FlowCrewActionDefinition(BaseModel):
     )
 
 
+class FlowAgentActionDefinition(BaseModel):
+    """A Flow method action that builds and kicks off a CrewAI agent."""
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        extra="forbid",
+    )
+
+    call: Literal["agent"] = Field(
+        description="Action discriminator. Use agent to run an inline Agent definition.",
+        examples=["agent"],
+    )
+    with_: AgentDefinition = Field(
+        alias="with",
+        description="Inline Agent definition to load and execute for this action.",
+        examples=[
+            {
+                "role": "Analyst",
+                "goal": "Answer user questions",
+                "backstory": "Precise and concise.",
+                "settings": {"llm": "openai/gpt-4o-mini"},
+                "input": "${state.question}",
+            }
+        ],
+    )
+
+
 class FlowExpressionActionDefinition(BaseModel):
     """A Flow method action that evaluates a CEL expression."""
 
@@ -470,6 +509,7 @@ FlowAtomicActionDefinition: TypeAlias = Annotated[
     FlowCodeActionDefinition
     | FlowToolActionDefinition
     | FlowCrewActionDefinition
+    | FlowAgentActionDefinition
     | FlowExpressionActionDefinition
     | FlowScriptActionDefinition,
     Field(discriminator="call"),
@@ -562,6 +602,7 @@ FlowActionDefinition: TypeAlias = (
     FlowCodeActionDefinition
     | FlowToolActionDefinition
     | FlowCrewActionDefinition
+    | FlowAgentActionDefinition
     | FlowExpressionActionDefinition
     | FlowScriptActionDefinition
     | FlowEachActionDefinition
@@ -696,6 +737,16 @@ class FlowDefinition(BaseModel):
             _validate_step_name(method_name, field="Flow method names")
         return self
 
+    @model_validator(mode="after")
+    def _validate_cel_expressions(self) -> FlowDefinition:
+        for method_name, method in self.methods.items():
+            _validate_action_cel(
+                method.do,
+                path=f"methods.{method_name}.do",
+                allowed_roots=_BASE_CEL_ROOTS,
+            )
+        return self
+
     def to_dict(self, *, exclude_none: bool = True) -> dict[str, Any]:
         """Serialize the definition to a JSON/YAML-ready dictionary."""
         return self.model_dump(by_alias=True, exclude_none=exclude_none, mode="json")
@@ -753,6 +804,69 @@ def _validate_step_list(steps: list[FlowEachStepDefinition], *, field: str) -> N
         seen.add(name)
 
 
+def _validate_action_cel(
+    action: FlowActionDefinition,
+    *,
+    path: str,
+    allowed_roots: frozenset[str],
+) -> None:
+    from crewai.flow.expressions import Expression
+
+    if isinstance(action, FlowExpressionActionDefinition):
+        Expression(action.expr).validate_expression(
+            allowed_roots=allowed_roots, source=f"{path}.expr"
+        )
+        return
+
+    if isinstance(action, (FlowCodeActionDefinition, FlowToolActionDefinition)):
+        if action.with_ is not None:
+            Expression(action.with_).validate_template(
+                allowed_roots=allowed_roots, source=f"{path}.with"
+            )
+        return
+
+    if isinstance(action, FlowCrewActionDefinition):
+        Expression(cast(ExpressionData, action.with_.inputs)).validate_template(
+            allowed_roots=allowed_roots,
+            source=f"{path}.with.inputs",
+        )
+        return
+
+    if isinstance(action, FlowAgentActionDefinition):
+        Expression(cast(ExpressionData, action.with_.input)).validate_template(
+            allowed_roots=allowed_roots,
+            source=f"{path}.with.input",
+        )
+        return
+
+    if isinstance(action, FlowEachActionDefinition):
+        Expression(action.in_).validate_expression(
+            allowed_roots=_BASE_CEL_ROOTS,
+            source=f"{path}.in",
+        )
+        for index, step in enumerate(action.do):
+            step_path = f"{path}.do[{index}]"
+            if step.if_ is not None:
+                Expression(step.if_).validate_expression(
+                    allowed_roots=_EACH_STEP_CEL_ROOTS,
+                    source=f"{step_path}.if",
+                )
+            _validate_action_cel(
+                step.action,
+                path=f"{step_path}.action",
+                allowed_roots=_EACH_STEP_CEL_ROOTS,
+            )
+        return
+
+    if isinstance(action, FlowScriptActionDefinition):
+        return
+
+    raise TypeError(
+        f"no CEL validation defined for action type {type(action).__name__} at "
+        f"{path}; add a branch to _validate_action_cel for it."
+    )
+
+
 def log_flow_definition_issues(definition: FlowDefinition) -> None:
     for method_name, method in definition.methods.items():
         path = f"methods.{method_name}"

lib/crewai/src/crewai/flow/runtime/_actions.py

@@ -10,8 +10,10 @@ import inspect
 import os
 from typing import TYPE_CHECKING, Any, Protocol, cast
 
+from crewai.flow.expressions import Expression, ExpressionData
 from crewai.flow.flow_definition import (
     FlowActionDefinition,
+    FlowAgentActionDefinition,
     FlowCodeActionDefinition,
     FlowCrewActionDefinition,
     FlowEachActionDefinition,
@@ -20,7 +22,6 @@ from crewai.flow.flow_definition import (
     FlowScriptActionDefinition,
     FlowToolActionDefinition,
 )
-from crewai.flow.runtime._expressions import evaluate_expression, render_with_block
 from crewai.flow.runtime._outputs import outputs_by_name
 from crewai.flow.runtime._refs import InvalidRefError, resolve_ref
 
@@ -67,9 +68,9 @@ class CodeAction:
         if self.definition.with_ is None:
             return self.handler(*args, **kwargs)
         return self.handler(
-            **render_with_block(
-                self.flow, self.definition.with_, local_context=local_context
-            )
+            **Expression.from_flow(
+                self.definition.with_, self.flow, local_context=local_context
+            ).render_template()
         )
 
     def _resolve_handler(self) -> Callable[..., Any]:
@@ -95,7 +96,9 @@ class ToolAction:
     def run(self, *_args: Any, **kwargs: Any) -> Any:
         local_context = _pop_local_context(kwargs)
         return self.tool.run(
-            **render_with_block(self.flow, self.kwargs, local_context=local_context)
+            **Expression.from_flow(
+                self.kwargs, self.flow, local_context=local_context
+            ).render_template()
         )
 
     def _build_tool(self) -> Any:
@@ -129,13 +132,44 @@ class CrewAction:
 
         local_context = _pop_local_context(kwargs)
         crew_definition = self.definition.with_
-        inputs = render_with_block(
-            self.flow, crew_definition.inputs, local_context=local_context
-        )
+        inputs = Expression.from_flow(
+            cast(ExpressionData, crew_definition.inputs),
+            self.flow,
+            local_context=local_context,
+        ).render_template()
         crew, _ = load_crew_from_definition(crew_definition, source="crew action")
         return await crew.kickoff_async(inputs=inputs)
 
 
+class AgentAction:
+    definition_type = FlowAgentActionDefinition
+
+    def __init__(self, flow: Flow[Any], definition: FlowAgentActionDefinition) -> None:
+        self.flow = flow
+        self.definition = definition
+
+    async def run(self, *_args: Any, **kwargs: Any) -> Any:
+        from crewai.project.json_loader import load_agent_from_definition
+
+        local_context = _pop_local_context(kwargs)
+        rendered_input = Expression.from_flow(
+            cast(ExpressionData, self.definition.with_.input),
+            self.flow,
+            local_context=local_context,
+        ).render_template()
+        if not isinstance(rendered_input, str):
+            raise ValueError("agent input must render to a string")
+
+        agent, response_format = load_agent_from_definition(
+            self.definition.with_,
+            source="agent action",
+        )
+        return await agent.kickoff_async(
+            rendered_input,
+            response_format=response_format,
+        )
+
+
 class ExpressionAction:
     definition_type = FlowExpressionActionDefinition
 
@@ -147,9 +181,9 @@ class ExpressionAction:
 
     def run(self, *_args: Any, **kwargs: Any) -> Any:
         local_context = _pop_local_context(kwargs)
-        return evaluate_expression(
-            self.flow, self.definition.expr, local_context=local_context
-        )
+        return Expression.from_flow(
+            self.definition.expr, self.flow, local_context=local_context
+        ).evaluate()
 
 
 class ScriptAction:
@@ -225,7 +259,7 @@ class EachAction:
         ]
 
     async def run(self, *_args: Any, **_kwargs: Any) -> list[Any]:
-        items = evaluate_expression(self.flow, self.definition.in_)
+        items = Expression.from_flow(self.definition.in_, self.flow).evaluate()
         if not isinstance(items, list):
             raise ValueError("each.in must evaluate to an array")
 
@@ -248,7 +282,9 @@ class EachAction:
         return results
 
     def _condition_matches(self, condition: str, local_context: LocalContext) -> bool:
-        result = evaluate_expression(self.flow, condition, local_context=local_context)
+        result = Expression.from_flow(
+            condition, self.flow, local_context=local_context
+        ).evaluate()
         if not isinstance(result, bool):
             raise ValueError("if expression must evaluate to a boolean")
         return result
@@ -278,6 +314,7 @@ _ACTION_TYPES: tuple[_ActionType, ...] = (
     EachAction,
     CodeAction,
     ToolAction,
+    AgentAction,
     CrewAction,
     ExpressionAction,
     ScriptAction,

lib/crewai/src/crewai/flow/runtime/_expressions.py

@@ -1,146 +0,0 @@
-"""Runtime expression support for FlowDefinition CEL expressions."""
-
-from __future__ import annotations
-
-from itertools import pairwise
-import json
-import re
-from typing import TYPE_CHECKING, Any, cast
-
-from crewai.flow.runtime._outputs import outputs_by_name
-from crewai.utilities.serialization import to_serializable
-
-
-if TYPE_CHECKING:
-    from crewai.flow.runtime import Flow
-
-
-_EXPRESSION_PATTERN = re.compile(r"\$\{([^{}]*)\}")
-
-__all__ = ["FlowExpressionError", "evaluate_expression", "render_with_block"]
-
-
-class FlowExpressionError(ValueError):
-    """A FlowDefinition expression failed to parse or evaluate."""
-
-
-def render_with_block(
-    flow: Flow[Any], value: Any, local_context: dict[str, Any] | None = None
-) -> Any:
-    """Render CEL expressions inside a FlowDefinition ``with:`` payload."""
-    context = _expression_context(flow, local_context=local_context)
-    return _render_value(value, context)
-
-
-def evaluate_expression(
-    flow: Flow[Any], expression: str, local_context: dict[str, Any] | None = None
-) -> Any:
-    """Evaluate a FlowDefinition CEL expression against runtime context."""
-    expression = expression.strip()
-    if not expression:
-        raise FlowExpressionError("empty CEL expression")
-    return _eval_cel(expression, _expression_context(flow, local_context=local_context))
-
-
-def _expression_context(
-    flow: Flow[Any], local_context: dict[str, Any] | None = None
-) -> dict[str, Any]:
-    local_outputs = local_context.get("outputs") if local_context else None
-    outputs = outputs_by_name(
-        flow._method_outputs,
-        local_outputs=local_outputs,
-        serialize=True,
-    )
-    context: dict[str, Any] = {
-        "state": flow._copy_and_serialize_state(),
-        "outputs": outputs,
-    }
-    if local_context:
-        local_values = {
-            key: to_serializable(value, max_depth=0)
-            for key, value in local_context.items()
-            if key not in {"outputs", "state"}
-        }
-        context.update(local_values)
-    return context
-
-
-def _render_value(value: Any, context: dict[str, Any]) -> Any:
-    if isinstance(value, str):
-        return _render_string(value, context)
-    if isinstance(value, dict):
-        return {key: _render_value(item, context) for key, item in value.items()}
-    if isinstance(value, list):
-        return [_render_value(item, context) for item in value]
-    return value
-
-
-def _render_string(value: str, context: dict[str, Any]) -> Any:
-    matches = list(_EXPRESSION_PATTERN.finditer(value))
-    if not matches:
-        _raise_for_invalid_interpolation(value)
-        return value
-
-    _raise_for_literal_braces(value[: matches[0].start()])
-    for previous, current in pairwise(matches):
-        _raise_for_literal_braces(value[previous.end() : current.start()])
-    _raise_for_literal_braces(value[matches[-1].end() :])
-
-    if len(matches) == 1 and matches[0].span() == (0, len(value)):
-        expression = matches[0].group(1).strip()
-        if not expression:
-            raise FlowExpressionError("empty CEL expression in with block")
-        return _eval_cel(expression, context)
-
-    rendered: list[str] = []
-    position = 0
-    for match in matches:
-        start, end = match.span()
-        literal = value[position:start]
-        rendered.append(literal)
-
-        expression = match.group(1).strip()
-        if not expression:
-            raise FlowExpressionError("empty CEL expression in with block")
-        result = _eval_cel(expression, context)
-        rendered.append(result if isinstance(result, str) else json.dumps(result))
-        position = end
-
-    literal = value[position:]
-    rendered.append(literal)
-
-    return "".join(rendered)
-
-
-def _raise_for_invalid_interpolation(value: str) -> None:
-    if "${" not in value:
-        return
-    raise FlowExpressionError(
-        "invalid CEL interpolation in with block: expressions must be enclosed "
-        "as ${...} and cannot contain braces"
-    )
-
-
-def _raise_for_literal_braces(value: str) -> None:
-    if "{" not in value and "}" not in value:
-        return
-    raise FlowExpressionError(
-        "invalid CEL interpolation in with block: expressions must be enclosed "
-        "as ${...} and cannot contain braces"
-    )
-
-
-def _eval_cel(expression: str, context: dict[str, Any]) -> Any:
-    try:
-        from celpy import Environment
-        from celpy.adapter import CELJSONEncoder, json_to_cel
-        from celpy.evaluation import Context
-
-        environment = Environment()
-        program = environment.program(environment.compile(expression))
-        result = program.evaluate(cast(Context, json_to_cel(context)))
-        return json.loads(json.dumps(result, cls=CELJSONEncoder))
-    except Exception as e:
-        raise FlowExpressionError(
-            f"failed to evaluate CEL expression {expression!r}: {e}"
-        ) from e

lib/crewai/src/crewai/hooks/tool_hooks.py

@@ -40,6 +40,8 @@ class ToolCallHookContext:
         crew: Crew instance (may be None)
         tool_result: Tool execution result (only set for after_tool_call hooks).
             Can be modified by returning a new string from after_tool_call hook.
+        raw_tool_result: Raw Python tool execution result (only set for
+            after_tool_call hooks). This is not modified by after hooks.
     """
 
     def __init__(
@@ -51,6 +53,7 @@ class ToolCallHookContext:
         task: Task | None = None,
         crew: Crew | None = None,
         tool_result: str | None = None,
+        raw_tool_result: Any | None = None,
     ) -> None:
         """Initialize tool call hook context.
 
@@ -62,6 +65,7 @@ class ToolCallHookContext:
             task: Optional current task
             crew: Optional crew instance
             tool_result: Optional tool result (for after hooks)
+            raw_tool_result: Optional raw tool result (for after hooks)
         """
         self.tool_name = tool_name
         self.tool_input = tool_input
@@ -70,6 +74,7 @@ class ToolCallHookContext:
         self.task = task
         self.crew = crew
         self.tool_result = tool_result
+        self.raw_tool_result = raw_tool_result
 
     def request_human_input(
         self,

lib/crewai/src/crewai/project/__init__.py

@@ -15,16 +15,22 @@ from crewai.project.annotations import (
 )
 from crewai.project.crew_base import CrewBase
 from crewai.project.crew_definition import (
+    AgentDefinition,
     CrewAgentDefinition,
     CrewDefinition,
     CrewTaskDefinition,
     PythonReferenceDefinition,
 )
 from crewai.project.crew_loader import load_crew, load_crew_and_kickoff
-from crewai.project.json_loader import load_agent, strip_jsonc_comments
+from crewai.project.json_loader import (
+    load_agent,
+    load_agent_from_definition,
+    strip_jsonc_comments,
+)
 
 
 __all__ = [
+    "AgentDefinition",
     "CrewAgentDefinition",
     "CrewBase",
     "CrewDefinition",
@@ -38,6 +44,7 @@ __all__ = [
     "crew",
     "llm",
     "load_agent",
+    "load_agent_from_definition",
     "load_crew",
     "load_crew_and_kickoff",
     "output_json",

lib/crewai/src/crewai/project/crew_definition.py

@@ -8,6 +8,7 @@ from pydantic import BaseModel, ConfigDict, Field, field_validator, model_valida
 
 
 __all__ = [
+    "AgentDefinition",
     "CrewAgentDefinition",
     "CrewDefinition",
     "CrewTaskDefinition",
@@ -53,6 +54,20 @@ class CrewAgentDefinition(BaseModel):
         return value or {}
 
 
+class AgentDefinition(CrewAgentDefinition):
+    """Inline agent definition used by a Flow agent action."""
+
+    input: str
+    response_format: PythonReferenceDefinition | None = None
+
+    @field_validator("input", mode="before")
+    @classmethod
+    def _validate_input(cls, value: Any) -> Any:
+        if not isinstance(value, str):
+            raise ValueError("agent.input must be a string")
+        return value
+
+
 class CrewTaskDefinition(BaseModel):
     """Task definition used by a crew definition."""
 

lib/crewai/src/crewai/project/json_loader.py

@@ -207,19 +207,18 @@ def load_jsonc_file(source: str | Path) -> Any:
     return parse_jsonc(path.read_text(encoding="utf-8"), source=path)
 
 
-def load_agent(source: str | Path) -> Any:
-    """Load an existing ``Agent`` from a ``.json`` / ``.jsonc`` definition file."""
-    path = Path(source)
-    defn = _expect_object(load_jsonc_file(path), path)
-    root = path.parent.parent if path.parent.name == "agents" else path.parent
+def _instantiate_agent_from_data(
+    defn: dict[str, Any], source_label: str, root: Path
+) -> Any:
+    """Resolve the agent class and kwargs from definition data and instantiate it."""
     agent_class = _agent_class_from_definition(
         defn,
-        f"{path}: type",
+        f"{source_label}: type",
         project_root=root,
     )
     agent_kwargs = _agent_kwargs_from_definition(
         defn,
-        path,
+        source_label,
         agent_class=agent_class,
         project_root=root,
     )
@@ -227,9 +226,50 @@ def load_agent(source: str | Path) -> Any:
     try:
         return agent_class(**agent_kwargs)
     except ValidationError as exc:
-        raise JSONProjectError(_format_validation_error(path, exc)) from exc
+        raise JSONProjectError(_format_validation_error(source_label, exc)) from exc
     except Exception as exc:
-        raise JSONProjectError(f"{path}: failed to load agent: {exc}") from exc
+        raise JSONProjectError(f"{source_label}: failed to load agent: {exc}") from exc
+
+
+def load_agent(source: str | Path) -> Any:
+    """Load an existing ``Agent`` from a ``.json`` / ``.jsonc`` definition file."""
+    path = Path(source)
+    defn = _expect_object(load_jsonc_file(path), path)
+    root = path.parent.parent if path.parent.name == "agents" else path.parent
+    return _instantiate_agent_from_data(defn, str(path), root)
+
+
+def load_agent_from_definition(
+    definition: dict[str, Any] | Any,
+    *,
+    source: str | Path = "<inline agent>",
+    project_root: str | Path | None = None,
+) -> tuple[Any, type[BaseModel] | None]:
+    """Load an ``Agent`` and optional kickoff response model from an inline definition."""
+    from crewai.project.crew_definition import AgentDefinition
+
+    root = Path(project_root) if project_root is not None else Path.cwd()
+    source_label = str(source)
+    agent_definition = (
+        definition
+        if isinstance(definition, AgentDefinition)
+        else AgentDefinition.model_validate(definition)
+    )
+    definition_data = agent_definition.model_dump(mode="python", exclude_none=True)
+    response_format_ref = definition_data.pop("response_format", None)
+    definition_data.pop("input", None)
+
+    agent = _instantiate_agent_from_data(definition_data, source_label, root)
+
+    response_format = None
+    if response_format_ref is not None:
+        response_format = _resolve_model_class(
+            response_format_ref,
+            f"{source_label}: response_format",
+            root,
+        )
+
+    return agent, response_format
 
 
 def validate_crew_project(

lib/crewai/src/crewai/tools/base_tool.py

@@ -33,6 +33,8 @@ from typing_extensions import TypeIs
 from crewai.tools.structured_tool import (
     CrewStructuredTool,
     _deserialize_schema,
+    _format_tool_output_for_agent,
+    _infer_result_schema_from_callable,
     _serialize_schema,
     build_schema_hint,
 )
@@ -149,6 +151,11 @@ class BaseTool(BaseModel, ABC):
         validate_default=True,
         description="The schema for the arguments that the tool accepts.",
     )
+    result_schema: type[PydanticBaseModel] | None = Field(
+        default=None,
+        validate_default=True,
+        description="The schema for the output that the tool returns.",
+    )
 
     @field_serializer("args_schema", when_used="json")
     def _serialize_args_schema(
@@ -156,6 +163,12 @@ class BaseTool(BaseModel, ABC):
     ) -> dict[str, Any] | None:
         return _serialize_schema(schema)
 
+    @field_serializer("result_schema", when_used="json")
+    def _serialize_result_schema(
+        self, schema: type[PydanticBaseModel] | None
+    ) -> dict[str, Any] | None:
+        return _serialize_schema(schema)
+
     description_updated: bool = Field(
         default=False, description="Flag to check if the description has been updated."
     )
@@ -233,6 +246,17 @@ class BaseTool(BaseModel, ABC):
 
         return create_model(f"{cls.__name__}Schema", **fields)
 
+    @field_validator("result_schema", mode="before")
+    @classmethod
+    def _default_result_schema(
+        cls, v: type[PydanticBaseModel] | dict[str, Any] | None
+    ) -> type[PydanticBaseModel] | None:
+        if isinstance(v, dict):
+            return _deserialize_schema(v)
+        if v is not None:
+            return v
+        return _infer_result_schema_from_callable(cls._run)
+
     @field_validator("max_usage_count", mode="before")
     @classmethod
     def validate_max_usage_count(cls, v: int | None) -> int | None:
@@ -340,6 +364,10 @@ class BaseTool(BaseModel, ABC):
             "Override _arun for async support or use run() for sync execution."
         )
 
+    def format_output_for_agent(self, raw_result: Any) -> str:
+        """Format a raw tool result into the string representation sent to an agent."""
+        return _format_tool_output_for_agent(self, raw_result)
+
     def reset_usage_count(self) -> None:
         """Reset the current usage count to zero."""
         self.current_usage_count = 0
@@ -369,6 +397,7 @@ class BaseTool(BaseModel, ABC):
             name=self.name,
             description=self.description,
             args_schema=self.args_schema,
+            result_schema=self.result_schema,
             func=self._run,
             result_as_answer=self.result_as_answer,
             max_usage_count=self.max_usage_count,
@@ -390,6 +419,9 @@ class BaseTool(BaseModel, ABC):
             raise ValueError("The provided tool must have a callable 'func' attribute.")
 
         args_schema = getattr(tool, "args_schema", None)
+        result_schema = getattr(tool, "result_schema", None)
+        if result_schema is None:
+            result_schema = _infer_result_schema_from_callable(tool.func)
 
         if args_schema is None:
             func_signature = signature(tool.func)
@@ -420,6 +452,7 @@ class BaseTool(BaseModel, ABC):
             description=getattr(tool, "description", ""),
             func=tool.func,
             args_schema=args_schema,
+            result_schema=result_schema,
         )
 
     def _set_args_schema(self) -> None:
@@ -568,6 +601,9 @@ class Tool(BaseTool, Generic[P, R]):
             raise ValueError("The provided tool must have a callable 'func' attribute.")
 
         args_schema = getattr(tool, "args_schema", None)
+        result_schema = getattr(tool, "result_schema", None)
+        if result_schema is None:
+            result_schema = _infer_result_schema_from_callable(tool.func)
 
         if args_schema is None:
             func_signature = signature(tool.func)
@@ -598,6 +634,7 @@ class Tool(BaseTool, Generic[P, R]):
             description=getattr(tool, "description", ""),
             func=tool.func,
             args_schema=args_schema,
+            result_schema=result_schema,
         )
 
 
@@ -621,6 +658,7 @@ def tool(
     name: str,
     /,
     *,
+    result_schema: type[BaseModel] | None = ...,
     result_as_answer: bool = ...,
     max_usage_count: int | None = ...,
 ) -> Callable[[Callable[P2, R2]], Tool[P2, R2]]: ...
@@ -629,6 +667,7 @@ def tool(
 @overload
 def tool(
     *,
+    result_schema: type[BaseModel] | None = ...,
     result_as_answer: bool = ...,
     max_usage_count: int | None = ...,
 ) -> Callable[[Callable[P2, R2]], Tool[P2, R2]]: ...
@@ -636,6 +675,7 @@ def tool(
 
 def tool(
     *args: Callable[P2, R2] | str,
+    result_schema: type[BaseModel] | None = None,
     result_as_answer: bool = False,
     max_usage_count: int | None = None,
 ) -> Tool[P2, R2] | Callable[[Callable[P2, R2]], Tool[P2, R2]]:
@@ -649,6 +689,7 @@ def tool(
     Args:
         *args: Either the function to decorate or a custom tool name.
         result_as_answer: If True, the tool result becomes the final agent answer.
+        result_schema: Optional schema for the output that the tool returns.
         max_usage_count: Maximum times this tool can be used. None means unlimited.
 
     Returns:
@@ -690,12 +731,16 @@ def tool(
 
             class_name = "".join(tool_name.split()).title()
             args_schema = create_model(class_name, **fields)
+            resolved_result_schema = (
+                result_schema or _infer_result_schema_from_callable(f)
+            )
 
             return Tool(
                 name=tool_name,
                 description=f.__doc__,
                 func=f,
                 args_schema=args_schema,
+                result_schema=resolved_result_schema,
                 result_as_answer=result_as_answer,
                 max_usage_count=max_usage_count,
                 current_usage_count=0,

lib/crewai/src/crewai/tools/structured_tool.py

@@ -5,7 +5,8 @@ from collections.abc import Callable
 import inspect
 import json
 import textwrap
-from typing import TYPE_CHECKING, Annotated, Any, get_type_hints
+from typing import TYPE_CHECKING, Annotated, Any, cast, get_type_hints
+import warnings
 
 from pydantic import (
     BaseModel,
@@ -36,6 +37,52 @@ def _deserialize_schema(v: Any) -> type[BaseModel] | None:
     return None
 
 
+def _infer_result_schema_from_callable(
+    func: Callable[..., Any],
+) -> type[BaseModel] | None:
+    try:
+        return_annotation = get_type_hints(func).get("return", inspect.Signature.empty)
+    except Exception:
+        return_annotation = inspect.signature(func).return_annotation
+
+    if isinstance(return_annotation, type) and issubclass(return_annotation, BaseModel):
+        return return_annotation
+
+    return None
+
+
+def _format_tool_output_for_agent(tool: Any, raw_result: Any) -> str:
+    original_tool = getattr(tool, "_original_tool", None)
+    if original_tool is not None:
+        return cast(str, original_tool.format_output_for_agent(raw_result))
+
+    result_schema = getattr(tool, "result_schema", None)
+    if not (isinstance(result_schema, type) and issubclass(result_schema, BaseModel)):
+        return str(raw_result)
+
+    try:
+        validation_input = raw_result
+        if isinstance(raw_result, BaseModel) and not isinstance(
+            raw_result, result_schema
+        ):
+            validation_input = raw_result.model_dump()
+
+        validated = result_schema.model_validate(validation_input)
+        return validated.model_dump_json()
+    except Exception as exc:
+        warnings.warn(
+            (
+                f"Failed to validate or serialize output from tool "
+                f"'{getattr(tool, 'name', '<unknown>')}' using result_schema "
+                f"'{result_schema.__name__}': {exc.__class__.__name__}. "
+                "Falling back to str(raw_result)."
+            ),
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        return str(raw_result)
+
+
 if TYPE_CHECKING:
     pass
 
@@ -81,6 +128,11 @@ class CrewStructuredTool(BaseModel):
         BeforeValidator(_deserialize_schema),
         PlainSerializer(_serialize_schema),
     ] = Field(default=None)
+    result_schema: Annotated[
+        type[BaseModel] | None,
+        BeforeValidator(_deserialize_schema),
+        PlainSerializer(_serialize_schema),
+    ] = Field(default=None)
     func: Any = Field(default=None, exclude=True)
     result_as_answer: bool = Field(default=False)
     max_usage_count: int | None = Field(default=None)
@@ -103,6 +155,7 @@ class CrewStructuredTool(BaseModel):
         description: str | None = None,
         return_direct: bool = False,
         args_schema: type[BaseModel] | None = None,
+        result_schema: type[BaseModel] | None = None,
         infer_schema: bool = True,
         **kwargs: Any,
     ) -> CrewStructuredTool:
@@ -114,6 +167,7 @@ class CrewStructuredTool(BaseModel):
             description: The description of the tool. Defaults to the function docstring
             return_direct: Whether to return the output directly
             args_schema: Optional schema for the function arguments
+            result_schema: Optional schema for the function output
             infer_schema: Whether to infer the schema from the function signature
             **kwargs: Additional arguments to pass to the tool
 
@@ -149,10 +203,16 @@ class CrewStructuredTool(BaseModel):
             name=name,
             description=description,
             args_schema=schema,
+            result_schema=result_schema or _infer_result_schema_from_callable(func),
             func=func,
             result_as_answer=return_direct,
+            **kwargs,
         )
 
+    def format_output_for_agent(self, raw_result: Any) -> str:
+        """Format a raw tool result into the string representation sent to an agent."""
+        return _format_tool_output_for_agent(self, raw_result)
+
     @staticmethod
     def _create_schema_from_function(
         name: str,

lib/crewai/src/crewai/tools/tool_usage.py

@@ -62,6 +62,9 @@ OPENAI_BIGGER_MODELS: list[
 ]
 
 
+_RAW_RESULT_UNSET = object()
+
+
 class ToolUsageError(Exception):
     """Exception raised for errors in the tool usage."""
 
@@ -106,6 +109,7 @@ class ToolUsage:
         self.action = action
         self.function_calling_llm = function_calling_llm
         self.fingerprint_context = fingerprint_context or {}
+        self.last_raw_result: Any = _RAW_RESULT_UNSET
 
         if (
             self.function_calling_llm
@@ -120,6 +124,11 @@ class ToolUsage:
         """Parse the tool string and return the tool calling."""
         return self._tool_calling(tool_string)
 
+    def get_last_raw_result(self, fallback: Any) -> Any:
+        if self.last_raw_result is _RAW_RESULT_UNSET:
+            return fallback
+        return self.last_raw_result
+
     def use(
         self, calling: ToolCalling | InstructorToolCalling, tool_string: str
     ) -> str:
@@ -231,6 +240,7 @@ class ToolUsage:
                 result = I18N_DEFAULT.errors("task_repeated_usage").format(
                     tool_names=self.tools_names
                 )
+                self.last_raw_result = result
                 self._telemetry.tool_repeated_usage(
                     llm=self.function_calling_llm,
                     tool_name=sanitize_tool_name(tool.name),
@@ -298,6 +308,7 @@ class ToolUsage:
             )
             if usage_limit_error:
                 result = usage_limit_error
+                self.last_raw_result = result
                 self._telemetry.tool_usage_error(llm=self.function_calling_llm)
                 result = self._format_result(result=result)
             elif result is None:
@@ -359,7 +370,10 @@ class ToolUsage:
                         tool_name=sanitize_tool_name(tool.name),
                         attempts=self._run_attempts,
                     )
-                    result = self._format_result(result=result)
+                    self.last_raw_result = result
+                    result = self._format_result(
+                        result=tool.format_output_for_agent(result)
+                    )
                     data = {
                         "result": result,
                         "tool_name": sanitize_tool_name(tool.name),
@@ -421,6 +435,7 @@ class ToolUsage:
                         result = ToolUsageError(
                             f"\n{error_message}.\nMoving on then. {I18N_DEFAULT.slice('format').format(tool_names=self.tools_names)}"
                         ).message
+                        self.last_raw_result = result
                         if self.task:
                             self.task.increment_tools_errors()
                         if self.agent and self.agent.verbose:
@@ -430,7 +445,10 @@ class ToolUsage:
                             self.task.increment_tools_errors()
                         should_retry = True
             else:
-                result = self._format_result(result=result)
+                self.last_raw_result = result
+                result = self._format_result(
+                    result=tool.format_output_for_agent(result)
+                )
 
         finally:
             if started_event_emitted and not error_event_emitted:
@@ -460,6 +478,7 @@ class ToolUsage:
                 result = I18N_DEFAULT.errors("task_repeated_usage").format(
                     tool_names=self.tools_names
                 )
+                self.last_raw_result = result
                 self._telemetry.tool_repeated_usage(
                     llm=self.function_calling_llm,
                     tool_name=sanitize_tool_name(tool.name),
@@ -529,6 +548,7 @@ class ToolUsage:
             )
             if usage_limit_error:
                 result = usage_limit_error
+                self.last_raw_result = result
                 self._telemetry.tool_usage_error(llm=self.function_calling_llm)
                 result = self._format_result(result=result)
             elif result is None:
@@ -590,7 +610,10 @@ class ToolUsage:
                         tool_name=sanitize_tool_name(tool.name),
                         attempts=self._run_attempts,
                     )
-                    result = self._format_result(result=result)
+                    self.last_raw_result = result
+                    result = self._format_result(
+                        result=tool.format_output_for_agent(result)
+                    )
                     data = {
                         "result": result,
                         "tool_name": sanitize_tool_name(tool.name),
@@ -652,6 +675,7 @@ class ToolUsage:
                         result = ToolUsageError(
                             f"\n{error_message}.\nMoving on then. {I18N_DEFAULT.slice('format').format(tool_names=self.tools_names)}"
                         ).message
+                        self.last_raw_result = result
                         if self.task:
                             self.task.increment_tools_errors()
                         if self.agent and self.agent.verbose:
@@ -661,7 +685,10 @@ class ToolUsage:
                             self.task.increment_tools_errors()
                         should_retry = True
             else:
-                result = self._format_result(result=result)
+                self.last_raw_result = result
+                result = self._format_result(
+                    result=tool.format_output_for_agent(result)
+                )
 
         finally:
             if started_event_emitted and not error_event_emitted:

lib/crewai/src/crewai/utilities/agent_utils.py

@@ -1383,6 +1383,19 @@ class NativeToolCallResult:
     tool_message: LLMMessage = field(default_factory=dict)  # type: ignore[assignment]
 
 
+def format_native_tool_output_for_agent(tool: Any, raw_result: Any) -> str:
+    """Format native tool output when a tool explicitly defines a formatter."""
+    formatter = inspect.getattr_static(tool, "format_output_for_agent", None)
+    if formatter is None:
+        return str(raw_result)
+
+    runtime_formatter = getattr(tool, "format_output_for_agent", None)
+    if not callable(runtime_formatter):
+        return str(raw_result)
+
+    return str(runtime_formatter(raw_result))
+
+
 def execute_single_native_tool_call(
     tool_call: Any,
     *,
@@ -1456,18 +1469,24 @@ def execute_single_native_tool_call(
             original_tool = tool
             break
 
+    structured_tool: CrewStructuredTool | None = None
+    for structured in structured_tools or []:
+        if sanitize_tool_name(structured.name) == func_name:
+            structured_tool = structured
+            break
+
+    output_tool = original_tool or structured_tool
+
     from_cache = False
     input_str = json.dumps(args_dict) if args_dict else ""
     result = "Tool not found"
+    raw_tool_result: Any = result
 
-    if tools_handler and tools_handler.cache:
+    if tools_handler and tools_handler.cache and output_tool is not None:
         cached_result = tools_handler.cache.read(tool=func_name, input=input_str)
         if cached_result is not None:
-            result = (
-                str(cached_result)
-                if not isinstance(cached_result, str)
-                else cached_result
-            )
+            raw_tool_result = cached_result
+            result = format_native_tool_output_for_agent(output_tool, cached_result)
             from_cache = True
 
     started_at = datetime.now()
@@ -1486,12 +1505,6 @@ def execute_single_native_tool_call(
 
     track_delegation_if_needed(func_name, args_dict, task)
 
-    structured_tool: CrewStructuredTool | None = None
-    for structured in structured_tools or []:
-        if sanitize_tool_name(structured.name) == func_name:
-            structured_tool = structured
-            break
-
     hook_blocked = False
     before_hook_context = ToolCallHookContext(
         tool_name=func_name,
@@ -1512,11 +1525,13 @@ def execute_single_native_tool_call(
     error_event_emitted = False
     if hook_blocked:
         result = f"Tool execution blocked by hook. Tool: {func_name}"
+        raw_tool_result = result
     elif not from_cache:
-        if func_name in available_functions:
+        if func_name in available_functions and output_tool is not None:
             try:
                 tool_func = available_functions[func_name]
                 raw_result = tool_func(**args_dict)
+                raw_tool_result = raw_result
 
                 if tools_handler and tools_handler.cache:
                     should_cache = True
@@ -1529,11 +1544,10 @@ def execute_single_native_tool_call(
                             tool=func_name, input=input_str, output=raw_result
                         )
 
-                result = (
-                    str(raw_result) if not isinstance(raw_result, str) else raw_result
-                )
+                result = format_native_tool_output_for_agent(output_tool, raw_result)
             except Exception as e:
                 result = f"Error executing tool: {e}"
+                raw_tool_result = result
                 if task:
                     task.increment_tools_errors()
                 crewai_event_bus.emit(
@@ -1559,6 +1573,7 @@ def execute_single_native_tool_call(
         task=task,
         crew=crew,
         tool_result=result,
+        raw_tool_result=raw_tool_result,
     )
     try:
         for after_hook in get_after_tool_call_hooks():

lib/crewai/src/crewai/utilities/tool_utils.py

@@ -116,6 +116,7 @@ async def aexecute_tool_and_check_finality(
             logger.log("error", f"Error in before_tool_call hook: {e}")
 
         tool_result = await tool_usage.ause(tool_calling, agent_action.text)
+        raw_tool_result = tool_usage.get_last_raw_result(tool_result)
 
         after_hook_context = ToolCallHookContext(
             tool_name=sanitized_tool_name,
@@ -125,6 +126,7 @@ async def aexecute_tool_and_check_finality(
             task=task,
             crew=crew,
             tool_result=tool_result,
+            raw_tool_result=raw_tool_result,
         )
 
         after_hooks = get_after_tool_call_hooks()
@@ -234,6 +236,7 @@ def execute_tool_and_check_finality(
             logger.log("error", f"Error in before_tool_call hook: {e}")
 
         tool_result = tool_usage.use(tool_calling, agent_action.text)
+        raw_tool_result = tool_usage.get_last_raw_result(tool_result)
 
         after_hook_context = ToolCallHookContext(
             tool_name=sanitized_tool_name,
@@ -243,6 +246,7 @@ def execute_tool_and_check_finality(
             task=task,
             crew=crew,
             tool_result=tool_result,
+            raw_tool_result=raw_tool_result,
         )
 
         after_hooks = get_after_tool_call_hooks()

lib/crewai/tests/agents/test_native_tool_calling.py

@@ -7,6 +7,7 @@ when the LLM supports it, across multiple providers.
 from __future__ import annotations
 
 from collections.abc import Generator
+import json
 import os
 import threading
 import time
@@ -20,7 +21,7 @@ from crewai import Agent, Crew, Task
 from crewai.agents.parser import AgentFinish
 from crewai.events import crewai_event_bus
 from crewai.hooks import register_after_tool_call_hook, register_before_tool_call_hook
-from crewai.hooks.tool_hooks import ToolCallHookContext
+from crewai.hooks.tool_hooks import ToolCallHookContext, clear_after_tool_call_hooks
 from crewai.llm import LLM
 from crewai.tools.base_tool import BaseTool
 
@@ -1197,6 +1198,76 @@ class TestNativeToolCallingJsonParseError:
 
         assert result["result"] == "ran: print(1)"
 
+    def test_typed_output_is_json_agent_text(self) -> None:
+        class SearchOutput(BaseModel):
+            query: str
+            score: float
+
+        class TypedSearchTool(BaseTool):
+            name: str = "typed_search"
+            description: str = "Search for information"
+            result_schema: type[BaseModel] = SearchOutput
+
+            def _run(self, query: str) -> SearchOutput:
+                return SearchOutput(query=query, score=0.8)
+
+        tool = TypedSearchTool()
+        executor = self._make_executor([tool])
+
+        from crewai.utilities.agent_utils import convert_tools_to_openai_schema
+
+        _, available_functions, _ = convert_tools_to_openai_schema([tool])
+
+        result = executor._execute_single_native_tool_call(
+            call_id="call_typed",
+            func_name="typed_search",
+            func_args='{"query": "crew"}',
+            available_functions=available_functions,
+        )
+
+        assert json.loads(result["result"]) == {"query": "crew", "score": 0.8}
+
+    def test_typed_output_after_hook_includes_raw_tool_result(self) -> None:
+        from crewai.utilities.agent_utils import convert_tools_to_openai_schema
+
+        class SearchOutput(BaseModel):
+            query: str
+            score: float
+
+        class TypedSearchTool(BaseTool):
+            name: str = "typed_search"
+            description: str = "Search for information"
+            result_schema: type[BaseModel] = SearchOutput
+
+            def _run(self, query: str) -> SearchOutput:
+                return SearchOutput(query=query, score=0.8)
+
+        seen_results: list[tuple[str | None, object]] = []
+
+        def after_hook(context: ToolCallHookContext) -> None:
+            seen_results.append((context.tool_result, context.raw_tool_result))
+
+        tool = TypedSearchTool()
+        executor = self._make_executor([tool])
+        _, available_functions, _ = convert_tools_to_openai_schema([tool])
+
+        clear_after_tool_call_hooks()
+        register_after_tool_call_hook(after_hook)
+        try:
+            result = executor._execute_single_native_tool_call(
+                call_id="call_typed",
+                func_name="typed_search",
+                func_args='{"query": "crew"}',
+                available_functions=available_functions,
+            )
+        finally:
+            clear_after_tool_call_hooks()
+
+        assert json.loads(result["result"]) == {"query": "crew", "score": 0.8}
+        assert seen_results == [
+            ('{"query":"crew","score":0.8}', SearchOutput(query="crew", score=0.8))
+        ]
+
     def test_native_tool_loop_falls_back_when_provider_rejects_tools(self) -> None:
         """Unsupported native tools errors should continue through ReAct."""
 

lib/crewai/tests/hooks/test_tool_hooks.py

@@ -91,20 +91,24 @@ class TestToolCallHookContext:
         assert context.task == mock_task
         assert context.crew == mock_crew
         assert context.tool_result is None
+        assert context.raw_tool_result is None
 
     def test_context_with_result(self, mock_tool):
         """Test that context includes result when provided."""
         tool_input = {"arg1": "value1"}
         tool_result = "Test tool result"
+        raw_tool_result = {"value": 42}
 
         context = ToolCallHookContext(
             tool_name="test_tool",
             tool_input=tool_input,
             tool=mock_tool,
             tool_result=tool_result,
+            raw_tool_result=raw_tool_result,
         )
 
         assert context.tool_result == tool_result
+        assert context.raw_tool_result == raw_tool_result
 
     def test_tool_input_is_mutable_reference(self, mock_tool):
         """Test that modifying context.tool_input modifies the original dict."""

lib/crewai/tests/project/test_json_loader.py

@@ -7,6 +7,7 @@ from pathlib import Path
 import sys
 
 import pytest
+from pydantic import BaseModel
 
 from crewai.llms.base_llm import BaseLLM
 from crewai.project.json_loader import (
@@ -14,6 +15,7 @@ from crewai.project.json_loader import (
     _looks_like_windows_absolute_path,
     find_json_project_file,
     load_agent,
+    load_agent_from_definition,
     strip_jsonc_comments,
 )
 
@@ -358,6 +360,30 @@ class TestLoadAgent:
             load_agent(Path("/nonexistent/agent.json"))
 
 
+class TestLoadAgentFromDefinition:
+    def test_resolves_response_format_from_project_module(self, tmp_path: Path):
+        (tmp_path / "models.py").write_text(
+            "from pydantic import BaseModel\n"
+            "class AnswerModel(BaseModel):\n"
+            "    answer: str\n"
+        )
+
+        _, response_format = load_agent_from_definition(
+            {
+                "role": "Analyst",
+                "goal": "Analyze data",
+                "backstory": "Data expert.",
+                "input": "Summarize this",
+                "response_format": {"python": "models.AnswerModel"},
+            },
+            source="agent action",
+            project_root=tmp_path,
+        )
+
+        assert issubclass(response_format, BaseModel)
+        assert response_format.__name__ == "AnswerModel"
+
+
 class TestResolveTools:
     def test_unknown_tool_raises_with_guidance(self):
         from crewai.project.json_loader import JSONProjectError, _resolve_tools

lib/crewai/tests/test_checkpoint.py

@@ -631,7 +631,7 @@ class TestLegacyMethodOutputsRestore:
         assert restored.method_outputs == ["first", "second"]
 
     def test_restore_legacy_outputs_evaluates_expressions(self) -> None:
-        from crewai.flow.runtime._expressions import _expression_context
+        from crewai.flow.expressions import Expression
 
         flow = Flow()
         flow._method_outputs = ["legacy"]
@@ -642,7 +642,7 @@ class TestLegacyMethodOutputsRestore:
             cfg = CheckpointConfig(restore_from=loc)
             restored = Flow.from_checkpoint(cfg)
 
-        context = _expression_context(restored)
+        context = Expression._flow_context(restored)
         assert context["outputs"] == {"": "legacy"}
 
     def test_raw_legacy_outputs_property_remains_readable(self) -> None:

lib/crewai/tests/test_flow_definition.py

@@ -37,6 +37,7 @@ def test_flow_public_exports_are_explicit():
     }
     assert set(flow_definition.__all__) == {
         "FlowActionDefinition",
+        "FlowAgentActionDefinition",
         "FlowAtomicActionDefinition",
         "FlowCodeActionDefinition",
         "FlowConfigDefinition",
@@ -80,6 +81,10 @@ def test_flow_definition_json_schema_carries_reference_descriptions():
     assert "not interpolated" in script_properties["code"]["description"]
     assert "not sandboxed" in script_properties["code"]["description"]
 
+    agent_properties = defs["FlowAgentActionDefinition"]["properties"]
+    assert "Inline Agent definition" in agent_properties["with"]["description"]
+    assert "run an inline Agent" in agent_properties["call"]["description"]
+
     state_schema = next(
         branch
         for branch in schema["properties"]["state"]["anyOf"]
@@ -122,6 +127,7 @@ def test_flow_definition_json_schema_carries_field_examples_only():
         "FlowDefinition",
         "FlowCodeActionDefinition",
         "FlowToolActionDefinition",
+        "FlowAgentActionDefinition",
         "FlowCrewActionDefinition",
         "FlowExpressionActionDefinition",
         "FlowScriptActionDefinition",
@@ -157,6 +163,10 @@ def test_flow_definition_json_schema_carries_field_examples_only():
     ]
     assert action_properties["with"]["examples"] == [{"topic": "${state.topic}"}]
 
+    agent_properties = defs["FlowAgentActionDefinition"]["properties"]
+    assert agent_properties["call"]["examples"] == ["agent"]
+    assert agent_properties["with"]["examples"][0]["input"] == "${state.question}"
+
     each_properties = defs["FlowEachActionDefinition"]["properties"]
     assert each_properties["in"]["examples"] == ["state.rows"]
     assert each_properties["do"]["examples"][0][0]["name"] == "clean"

lib/crewai/tests/test_flow_from_definition.py

@@ -644,7 +644,7 @@ methods:
     assert flow.kickoff(inputs={"topic": "ai"}) == "found:ai agents"
 
 
-def test_tool_action_rejects_braces_in_embedded_cel_input():
+def test_tool_action_treats_embedded_cel_marker_as_literal():
     definition = FlowDefinition.from_dict(
         {
             "schema": "crewai.flow/v1",
@@ -660,16 +660,62 @@ def test_tool_action_rejects_braces_in_embedded_cel_input():
                             "prefix": "${'p}x'}",
                         },
                     },
-                }
+                },
             },
         }
     )
 
-    with pytest.raises(ValueError, match="cannot contain braces"):
-        Flow.from_definition(definition).kickoff()
+    assert Flow.from_definition(definition).kickoff() == "p}x:wrapped ${'a}b'} value"
 
 
-def test_tool_action_rejects_braces_in_full_cel_input():
+def test_tool_action_treats_marker_with_trailing_text_as_literal():
+    definition = FlowDefinition.from_dict(
+        {
+            "schema": "crewai.flow/v1",
+            "name": "ToolFlow",
+            "methods": {
+                "search": {
+                    "start": True,
+                    "do": {
+                        "call": "tool",
+                        "ref": f"{__name__}:StaticSearchTool",
+                        "with": {
+                            "search_query": "${state.topic} extra",
+                            "prefix": "p",
+                        },
+                    },
+                },
+            },
+        }
+    )
+
+    assert Flow.from_definition(definition).kickoff() == "p:${state.topic} extra"
+
+
+def test_tool_action_rejects_adjacent_markers_as_invalid_cel():
+    with pytest.raises(ValidationError, match="invalid CEL expression"):
+        FlowDefinition.from_dict(
+            {
+                "schema": "crewai.flow/v1",
+                "name": "ToolFlow",
+                "methods": {
+                    "search": {
+                        "start": True,
+                        "do": {
+                            "call": "tool",
+                            "ref": f"{__name__}:StaticSearchTool",
+                            "with": {
+                                "search_query": "${'a'}${'b'}",
+                                "prefix": "p",
+                            },
+                        },
+                    },
+                },
+            }
+        )
+
+
+def test_tool_action_accepts_braces_in_full_cel_marker():
     definition = FlowDefinition.from_dict(
         {
             "schema": "crewai.flow/v1",
@@ -682,16 +728,15 @@ def test_tool_action_rejects_braces_in_full_cel_input():
                         "ref": f"{__name__}:StaticSearchTool",
                         "with": {
                             "search_query": "${{'query': 'ai agents'}.query}",
-                            "prefix": "found",
+                            "prefix": "${'p}x'}",
                         },
                     },
-                }
+                },
             },
         }
     )
 
-    with pytest.raises(ValueError, match="cannot contain braces"):
-        Flow.from_definition(definition).kickoff()
+    assert Flow.from_definition(definition).kickoff() == "p}x:ai agents"
 
 
 def test_tool_action_renders_latest_output_by_method_name():
@@ -766,6 +811,166 @@ methods:
     )
 
 
+def test_agent_action_runs_inline_yaml_definition(monkeypatch: pytest.MonkeyPatch):
+    from crewai import Agent
+
+    async def fake_kickoff_async(
+        self: Agent, messages: str, **_kwargs: Any
+    ) -> dict[str, Any]:
+        return {"agent": self.role, "input": messages}
+
+    monkeypatch.setattr(Agent, "kickoff_async", fake_kickoff_async)
+
+    yaml_str = """
+schema: crewai.flow/v1
+name: AgentFlow
+methods:
+  answer:
+    do:
+      call: agent
+      with:
+        role: Analyst
+        goal: Answer questions
+        backstory: Knows things.
+        input: "${state.question}"
+    start: true
+"""
+
+    flow = Flow.from_definition(FlowDefinition.from_yaml(yaml_str))
+
+    assert flow.kickoff(inputs={"question": "What is CrewAI?"}) == {
+        "agent": "Analyst",
+        "input": "What is CrewAI?",
+    }
+
+
+def test_agent_action_runs_inside_each(monkeypatch: pytest.MonkeyPatch):
+    from crewai import Agent
+
+    async def fake_kickoff_async(
+        self: Agent, messages: str, **_kwargs: Any
+    ) -> str:
+        return f"{self.role}:{messages}"
+
+    monkeypatch.setattr(Agent, "kickoff_async", fake_kickoff_async)
+
+    yaml_str = """
+schema: crewai.flow/v1
+name: AgentEachFlow
+methods:
+  answer_each:
+    do:
+      call: each
+      in: state.questions
+      do:
+        - name: answer
+          action:
+            call: agent
+            with:
+              role: Analyst
+              goal: Answer questions
+              backstory: Knows things.
+              input: "${item}"
+    start: true
+"""
+
+    flow = Flow.from_definition(FlowDefinition.from_yaml(yaml_str))
+
+    assert flow.kickoff(inputs={"questions": ["one", "two"]}) == [
+        "Analyst:one",
+        "Analyst:two",
+    ]
+
+
+def test_agent_action_round_trips_with_inline_definition():
+    definition = FlowDefinition.from_dict(
+        {
+            "schema": "crewai.flow/v1",
+            "name": "AgentFlow",
+            "methods": {
+                "answer": {
+                    "start": True,
+                    "do": {
+                        "call": "agent",
+                        "with": {
+                            "role": "Analyst",
+                            "goal": "Answer questions",
+                            "backstory": "Knows things.",
+                            "settings": {"verbose": True},
+                            "input": "${state.question}",
+                        },
+                    },
+                }
+            },
+        }
+    )
+
+    round_trip = FlowDefinition.from_yaml(definition.to_yaml())
+    action = round_trip.to_dict()["methods"]["answer"]["do"]
+
+    assert action["call"] == "agent"
+    assert action["with"]["role"] == "Analyst"
+    assert action["with"]["input"] == "${state.question}"
+    assert action["with"]["settings"] == {"verbose": True}
+
+
+def test_agent_action_json_schema_describes_inline_agent_definitions():
+    schema_defs = FlowDefinition.json_schema()["$defs"]
+
+    assert set(schema_defs["AgentDefinition"]["properties"]) >= {
+        "role",
+        "goal",
+        "backstory",
+        "settings",
+        "input",
+        "response_format",
+    }
+
+
+def test_agent_action_rejects_non_string_input_in_definition():
+    with pytest.raises(ValidationError, match="agent.input must be a string"):
+        FlowDefinition.from_dict(
+            {
+                "schema": "crewai.flow/v1",
+                "name": "AgentFlow",
+                "methods": {
+                    "answer": {
+                        "start": True,
+                        "do": {
+                            "call": "agent",
+                            "with": {
+                                "role": "Analyst",
+                                "goal": "Answer questions",
+                                "backstory": "Knows things.",
+                                "input": 123,
+                            },
+                        },
+                    }
+                },
+            }
+        )
+
+
+def test_agent_action_reports_invalid_cel_expression():
+    yaml_str = """
+schema: crewai.flow/v1
+name: AgentFlow
+methods:
+  answer:
+    do:
+      call: agent
+      with:
+        role: Analyst
+        goal: Answer questions
+        backstory: Knows things.
+        input: "${state.}"
+    start: true
+"""
+
+    with pytest.raises(ValidationError, match="invalid CEL expression"):
+        FlowDefinition.from_yaml(yaml_str)
+
+
 def test_crew_action_runs_inline_yaml_definition(monkeypatch: pytest.MonkeyPatch):
     from crewai import Crew
 
@@ -1026,10 +1231,8 @@ methods:
     start: true
 """
 
-    flow = Flow.from_definition(FlowDefinition.from_yaml(yaml_str))
-
-    with pytest.raises(ValueError, match="failed to evaluate CEL expression"):
-        flow.kickoff()
+    with pytest.raises(ValidationError, match="invalid CEL expression"):
+        FlowDefinition.from_yaml(yaml_str)
 
 
 def test_code_action_renders_keyword_inputs():
@@ -1407,6 +1610,33 @@ methods:
     ) == ["kept:a", "skipped:b"]
 
 
+def test_each_action_accepts_expression_markers_in_explicit_cel_fields():
+    yaml_str = """
+schema: crewai.flow/v1
+name: EachIfFlow
+methods:
+  process_rows:
+    do:
+      call: each
+      in: "${state.rows}"
+      do:
+        - name: kind
+          action:
+            call: expression
+            expr: "${item.kind}"
+        - name: kept
+          if: "${outputs.kind == 'keep'}"
+          action:
+            call: expression
+            expr: "${item.value}"
+    start: true
+"""
+
+    flow = Flow.from_definition(FlowDefinition.from_yaml(yaml_str))
+
+    assert flow.kickoff(inputs={"rows": [{"kind": "keep", "value": "a"}]}) == ["a"]
+
+
 def test_each_action_skipped_if_keeps_previous_output():
     yaml_str = """
 schema: crewai.flow/v1
@@ -1690,8 +1920,28 @@ def test_expression_action_round_trips():
     assert Flow.from_definition(definition).kickoff(inputs={"score": 90}) == "qualified"
 
 
+def test_explicit_cel_fields_accept_expression_markers():
+    definition = FlowDefinition.from_dict(
+        {
+            "schema": "crewai.flow/v1",
+            "name": "ExpressionFlow",
+            "methods": {
+                "classify": {
+                    "start": True,
+                    "do": {
+                        "call": "expression",
+                        "expr": "${state.score >= 80 ? 'qualified' : 'nurture'}",
+                    },
+                }
+            },
+        }
+    )
+
+    assert Flow.from_definition(definition).kickoff(inputs={"score": 90}) == "qualified"
+
+
 def test_expression_local_context_recurses_into_dataclass_values():
-    from crewai.flow.runtime._expressions import evaluate_expression
+    from crewai.flow.expressions import Expression
 
     class Payload(BaseModel):
         name: str
@@ -1701,15 +1951,37 @@ def test_expression_local_context_recurses_into_dataclass_values():
         payload: Payload
 
     assert (
-        evaluate_expression(
-            Flow(),
+        Expression.from_flow(
             "item.payload.name",
+            Flow(),
             local_context={"item": Row(payload=Payload(name="qualified"))},
-        )
+        ).evaluate()
         == "qualified"
     )
 
 
+def test_expression_empty_context_overrides_stored_context():
+    from crewai.flow.expressions import Expression, ExpressionError
+
+    expression = Expression("state.score", context={"state": {"score": 90}})
+
+    assert expression.evaluate() == 90
+    with pytest.raises(ExpressionError):
+        expression.evaluate({})
+
+
+def test_expression_template_empty_context_overrides_stored_context():
+    from crewai.flow.expressions import Expression, ExpressionError
+
+    expression = Expression(
+        {"score": "${state.score}"}, context={"state": {"score": 90}}
+    )
+
+    assert expression.render_template() == {"score": 90}
+    with pytest.raises(ExpressionError):
+        expression.render_template({})
+
+
 def test_expression_action_can_route_like_if_else():
     yaml_str = f"""
 schema: crewai.flow/v1
@@ -1761,10 +2033,24 @@ methods:
     start: true
 """
 
-    flow = Flow.from_definition(FlowDefinition.from_yaml(yaml_str))
+    with pytest.raises(ValidationError, match="invalid CEL expression"):
+        FlowDefinition.from_yaml(yaml_str)
 
-    with pytest.raises(ValueError, match="failed to evaluate CEL expression"):
-        flow.kickoff()
+
+def test_expression_action_rejects_unknown_cel_root():
+    yaml_str = """
+schema: crewai.flow/v1
+name: ExpressionFlow
+methods:
+  classify:
+    do:
+      call: expression
+      expr: "score >= 80"
+    start: true
+"""
+
+    with pytest.raises(ValidationError, match="unknown CEL root"):
+        FlowDefinition.from_yaml(yaml_str)
 
 
 def test_tool_action_requires_module_qualname_ref():

lib/crewai/tests/tools/test_base_tool.py

@@ -1,12 +1,13 @@
 import asyncio
 from collections.abc import Callable
+import json
 from unittest.mock import patch
 
 from crewai.agent import Agent
 from crewai.crew import Crew
 from crewai.task import Task
 from crewai.tools import BaseTool, tool
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, RootModel
 import pytest
 
 
@@ -351,6 +352,262 @@ class TestToolDecoratorRunValidation:
         assert result == "Hello, World!"
 
 
+class SearchOutput(BaseModel):
+    query: str
+    score: float
+
+
+class SearchResults(RootModel[list[SearchOutput]]):
+    pass
+
+
+class ExplicitSearchTool(BaseTool):
+    name: str = "search"
+    description: str = "Search for a query"
+    result_schema: type[BaseModel] = SearchOutput
+
+    def _run(self, query: str) -> dict[str, object]:
+        return {"query": query, "score": 0.8}
+
+
+class InferredSearchTool(BaseTool):
+    name: str = "search"
+    description: str = "Search for a query"
+
+    def _run(self, query: str) -> SearchOutput:
+        return SearchOutput(query=query, score=0.7)
+
+
+class RootSearchTool(BaseTool):
+    name: str = "search"
+    description: str = "Search for a query"
+
+    def _run(self, query: str) -> SearchResults:
+        return SearchResults([SearchOutput(query=query, score=1.0)])
+
+
+class DictAnnotatedSearchTool(BaseTool):
+    name: str = "search"
+    description: str = "Search for a query"
+
+    def _run(self, query: str) -> dict[str, object]:
+        return {"query": query, "score": 0.5}
+
+
+def _make_explicit_decorator_tool() -> BaseTool:
+    @tool("search", result_schema=SearchOutput)
+    def search(query: str) -> dict[str, object]:
+        """Search for a query."""
+        return {"query": query, "score": 0.8}
+
+    return search
+
+
+def _make_inferred_decorator_tool() -> BaseTool:
+    @tool("search")
+    def search(query: str) -> SearchOutput:
+        """Search for a query."""
+        return SearchOutput(query=query, score=0.6)
+
+    return search
+
+
+def _make_root_decorator_tool() -> BaseTool:
+    @tool("search")
+    def search(query: str) -> SearchResults:
+        """Search for a query."""
+        return SearchResults([SearchOutput(query=query, score=1.0)])
+
+    return search
+
+
+class TestToolOutputSchema:
+    @pytest.mark.parametrize(
+        ("tool_cls", "expected_raw", "expected_agent_payload"),
+        [
+            pytest.param(
+                ExplicitSearchTool,
+                {"query": "crew", "score": 0.8},
+                {"query": "crew", "score": 0.8},
+                id="explicit-schema",
+            ),
+            pytest.param(
+                InferredSearchTool,
+                SearchOutput(query="crew", score=0.7),
+                {"query": "crew", "score": 0.7},
+                id="inferred-base-model",
+            ),
+            pytest.param(
+                RootSearchTool,
+                SearchResults([SearchOutput(query="crew", score=1.0)]),
+                [{"query": "crew", "score": 1.0}],
+                id="inferred-root-model",
+            ),
+        ],
+    )
+    def test_base_tools_return_raw_result_and_json_agent_text(
+        self,
+        tool_cls: type[BaseTool],
+        expected_raw: object,
+        expected_agent_payload: object,
+    ) -> None:
+        t = tool_cls()
+
+        raw_result = t.run(query="crew")
+
+        assert raw_result == expected_raw
+        assert json.loads(t.format_output_for_agent(raw_result)) == (
+            expected_agent_payload
+        )
+
+    def test_base_tool_does_not_infer_non_pydantic_return_annotation(self) -> None:
+        t = DictAnnotatedSearchTool()
+
+        raw_result = t.run(query="crew")
+
+        assert raw_result == {"query": "crew", "score": 0.5}
+        assert t.format_output_for_agent(raw_result) == str(raw_result)
+
+    @pytest.mark.parametrize(
+        ("make_tool", "expected_raw", "expected_agent_payload"),
+        [
+            pytest.param(
+                _make_explicit_decorator_tool,
+                {"query": "crew", "score": 0.8},
+                {"query": "crew", "score": 0.8},
+                id="explicit-schema",
+            ),
+            pytest.param(
+                _make_inferred_decorator_tool,
+                SearchOutput(query="crew", score=0.6),
+                {"query": "crew", "score": 0.6},
+                id="inferred-base-model",
+            ),
+            pytest.param(
+                _make_root_decorator_tool,
+                SearchResults([SearchOutput(query="crew", score=1.0)]),
+                [{"query": "crew", "score": 1.0}],
+                id="inferred-root-model",
+            ),
+        ],
+    )
+    def test_decorator_tools_return_raw_result_and_json_agent_text(
+        self,
+        make_tool: Callable[[], BaseTool],
+        expected_raw: object,
+        expected_agent_payload: object,
+    ) -> None:
+        search = make_tool()
+
+        raw_result = search.run(query="crew")
+
+        assert raw_result == expected_raw
+        assert json.loads(search.format_output_for_agent(raw_result)) == (
+            expected_agent_payload
+        )
+
+    def test_decorator_tool_does_not_infer_non_pydantic_return_annotation(
+        self,
+    ) -> None:
+        @tool("search")
+        def search(query: str) -> dict[str, object]:
+            """Search for a query."""
+            return {"query": query, "score": 0.5}
+
+        raw_result = search.run(query="crew")
+
+        assert raw_result == {"query": "crew", "score": 0.5}
+        assert search.format_output_for_agent(raw_result) == str(raw_result)
+
+    def test_explicit_result_schema_wins_over_return_annotation(self) -> None:
+        class AlternateOutput(BaseModel):
+            value: str
+
+        @tool("search", result_schema=AlternateOutput)
+        def search(query: str) -> SearchOutput:
+            """Search for a query."""
+            return SearchOutput(query=query, score=0.6)
+
+        raw_result = search.run(query="crew")
+
+        with pytest.warns(RuntimeWarning, match="AlternateOutput"):
+            agent_text = search.format_output_for_agent(raw_result)
+
+        assert raw_result == SearchOutput(query="crew", score=0.6)
+        assert agent_text == str(raw_result)
+
+    def test_invalid_typed_output_warns_and_uses_string_agent_text(
+        self,
+    ) -> None:
+        @tool("search", result_schema=SearchOutput)
+        def search(query: str) -> dict[str, object]:
+            """Search for a query."""
+            return {"query": query, "score": "not-a-float"}
+
+        raw_result = search.run(query="crew")
+
+        with pytest.warns(RuntimeWarning, match="Failed to validate or serialize"):
+            agent_text = search.format_output_for_agent(raw_result)
+
+        assert raw_result == {"query": "crew", "score": "not-a-float"}
+        assert agent_text == str(raw_result)
+
+    def test_unserializable_typed_output_warns_and_uses_string_agent_text(
+        self,
+    ) -> None:
+        class OpaqueOutput(BaseModel):
+            value: object
+
+        raw_result = OpaqueOutput(value=object())
+
+        @tool("opaque", result_schema=OpaqueOutput)
+        def opaque() -> OpaqueOutput:
+            """Return an opaque object."""
+            return raw_result
+
+        result = opaque.run()
+
+        with pytest.warns(RuntimeWarning, match="Failed to validate or serialize"):
+            agent_text = opaque.format_output_for_agent(result)
+
+        assert result is raw_result
+        assert agent_text == str(raw_result)
+
+    def test_result_schema_behavior_carries_over_to_structured_tool(self) -> None:
+        structured = ExplicitSearchTool().to_structured_tool()
+
+        raw_result = structured.invoke({"query": "crew"})
+
+        assert raw_result == {"query": "crew", "score": 0.8}
+        assert json.loads(structured.format_output_for_agent(raw_result)) == {
+            "query": "crew",
+            "score": 0.8,
+        }
+
+    def test_custom_agent_output_formatter_carries_over_to_structured_tool(
+        self,
+    ) -> None:
+        class MarkdownSearchTool(BaseTool):
+            name: str = "markdown_search"
+            description: str = "Search for information"
+            result_schema: type[BaseModel] = SearchOutput
+
+            def _run(self, query: str) -> SearchOutput:
+                return SearchOutput(query=query, score=0.8)
+
+            def format_output_for_agent(self, raw_result: object) -> str:
+                result = self.result_schema.model_validate(raw_result)
+                return f"### Search result\n\n- Query: `{result.query}`\n- Score: {result.score}"
+
+        structured = MarkdownSearchTool().to_structured_tool()
+
+        raw_result = structured.invoke({"query": "crew"})
+
+        assert raw_result == SearchOutput(query="crew", score=0.8)
+        assert structured.format_output_for_agent(raw_result) == (
+            "### Search result\n\n- Query: `crew`\n- Score: 0.8"
+        )
+
 # Async arun() Schema Validation Tests
 
 

lib/crewai/tests/tools/test_structured_tool.py

@@ -1,5 +1,7 @@
+import json
+
 from crewai.tools.structured_tool import CrewStructuredTool
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, RootModel
 import pytest
 
 
@@ -86,6 +88,118 @@ def test_from_function(basic_function):
     assert isinstance(tool.args_schema, type(BaseModel))
 
 
+class StructuredOutput(BaseModel):
+    value: str
+    count: int
+
+
+class StructuredOutputList(RootModel[list[StructuredOutput]]):
+    pass
+
+
+def _build_explicit_structured_value(value: str) -> dict[str, object]:
+    """Build a value."""
+    return {"value": value, "count": 1}
+
+
+def _build_inferred_structured_value(value: str) -> StructuredOutput:
+    """Build a value."""
+    return StructuredOutput(value=value, count=1)
+
+
+def _build_structured_values(value: str) -> StructuredOutputList:
+    """Build values."""
+    return StructuredOutputList([StructuredOutput(value=value, count=1)])
+
+
+def _build_plain_structured_value(value: str) -> dict[str, object]:
+    """Build a value."""
+    return {"value": value, "count": 1}
+
+
+@pytest.mark.parametrize(
+    ("func", "result_schema", "expected_raw", "expected_agent_payload"),
+    [
+        pytest.param(
+            _build_explicit_structured_value,
+            StructuredOutput,
+            {"value": "crew", "count": 1},
+            {"value": "crew", "count": 1},
+            id="explicit-schema",
+        ),
+        pytest.param(
+            _build_inferred_structured_value,
+            None,
+            StructuredOutput(value="crew", count=1),
+            {"value": "crew", "count": 1},
+            id="inferred-base-model",
+        ),
+        pytest.param(
+            _build_structured_values,
+            None,
+            StructuredOutputList([StructuredOutput(value="crew", count=1)]),
+            [{"value": "crew", "count": 1}],
+            id="inferred-root-model",
+        ),
+    ],
+)
+def test_from_function_returns_raw_result_and_json_agent_text(
+    func,
+    result_schema,
+    expected_raw,
+    expected_agent_payload,
+):
+    kwargs = {"result_schema": result_schema} if result_schema is not None else {}
+    tool = CrewStructuredTool.from_function(
+        func=func,
+        name="build_value",
+        **kwargs,
+    )
+
+    raw_result = tool.invoke({"value": "crew"})
+
+    assert raw_result == expected_raw
+    assert json.loads(tool.format_output_for_agent(raw_result)) == (
+        expected_agent_payload
+    )
+
+
+def test_from_function_does_not_infer_non_pydantic_result_schema():
+    tool = CrewStructuredTool.from_function(
+        func=_build_plain_structured_value,
+        name="build_value",
+    )
+
+    raw_result = tool.invoke({"value": "crew"})
+
+    assert raw_result == {"value": "crew", "count": 1}
+    assert tool.format_output_for_agent(raw_result) == str(raw_result)
+
+
+def test_invalid_typed_output_warns_and_uses_string_agent_text():
+    def build_value(value: str) -> dict[str, object]:
+        """Build a value."""
+        return {"value": value, "count": "wrong"}
+
+    tool = CrewStructuredTool.from_function(
+        func=build_value,
+        name="build_value",
+        result_schema=StructuredOutput,
+    )
+    raw_result = tool.invoke({"value": "crew"})
+
+    with pytest.warns(
+        RuntimeWarning, match="Failed to validate or serialize"
+    ) as warnings:
+        agent_text = tool.format_output_for_agent(raw_result)
+
+    assert raw_result == {"value": "crew", "count": "wrong"}
+    assert agent_text == str(raw_result)
+    warning_message = str(warnings[0].message)
+    assert "ValidationError" in warning_message
+    assert "wrong" not in warning_message
+
+
 def test_validate_function_signature(basic_function, schema_class):
     """Test function signature validation"""
     tool = CrewStructuredTool(

lib/crewai/tests/tools/test_tool_usage.py

@@ -1,4 +1,5 @@
 import datetime
+from collections.abc import Callable
 import json
 import random
 import threading
@@ -6,6 +7,9 @@ import time
 from unittest.mock import MagicMock, patch
 
 from crewai import Agent, Task
+from crewai.agents.cache.cache_handler import CacheHandler
+from crewai.agents.parser import AgentAction
+from crewai.agents.tools_handler import ToolsHandler
 from crewai.events.event_bus import crewai_event_bus
 from crewai.events.types.tool_usage_events import (
     ToolSelectionErrorEvent,
@@ -14,8 +18,15 @@ from crewai.events.types.tool_usage_events import (
     ToolUsageStartedEvent,
     ToolValidateInputErrorEvent,
 )
+from crewai.hooks.tool_hooks import (
+    ToolCallHookContext,
+    clear_after_tool_call_hooks,
+    register_after_tool_call_hook,
+)
 from crewai.tools import BaseTool
+from crewai.tools.tool_calling import ToolCalling
 from crewai.tools.tool_usage import ToolUsage
+from crewai.utilities.tool_utils import execute_tool_and_check_finality
 from pydantic import BaseModel, Field
 import pytest
 
@@ -38,6 +49,19 @@ class RandomNumberTool(BaseTool):
         return random.randint(min_value, max_value)  # noqa: S311
 
 
+class SearchOutput(BaseModel):
+    query: str
+    score: float
+
+
+class TypedSearchTool(BaseTool):
+    name: str = "typed_search"
+    description: str = "Search for a query"
+
+    def _run(self, query: str) -> SearchOutput:
+        return SearchOutput(query=query, score=0.7)
+
+
 # Example agent and task
 example_agent = Agent(
     role="Number Generator",
@@ -117,6 +141,126 @@ def test_tool_usage_render():
     assert '"description": "The maximum value of the range (inclusive)"' in rendered
 
 
+def test_tool_usage_returns_json_agent_text_for_typed_output():
+    tool = TypedSearchTool().to_structured_tool()
+    tool_usage = ToolUsage(
+        tools_handler=None,
+        tools=[tool],
+        task=None,
+        function_calling_llm=MagicMock(),
+        agent=None,
+        action=MagicMock(),
+    )
+
+    result = tool_usage.use(
+        calling=ToolCalling(
+            tool_name="typed_search",
+            arguments={"query": "crew"},
+        ),
+        tool_string='Action: typed_search\nAction Input: {"query": "crew"}',
+    )
+
+    assert json.loads(result) == {"query": "crew", "score": 0.7}
+
+
+def test_tool_usage_cache_callback_receives_raw_typed_output():
+    raw_results: list[object] = []
+
+    def cache_result(_args: object, result: object) -> bool:
+        raw_results.append(result)
+        return True
+
+    class CacheAwareTypedSearchTool(TypedSearchTool):
+        cache_function: Callable = cache_result
+
+    tools_handler = MagicMock()
+    tools_handler.cache = None
+    tools_handler.last_used_tool = None
+    tool = CacheAwareTypedSearchTool().to_structured_tool()
+    tool_usage = ToolUsage(
+        tools_handler=tools_handler,
+        tools=[tool],
+        task=None,
+        function_calling_llm=MagicMock(),
+        agent=None,
+        action=MagicMock(),
+    )
+
+    result = tool_usage.use(
+        calling=ToolCalling(
+            tool_name="typed_search",
+            arguments={"query": "crew"},
+        ),
+        tool_string='Action: typed_search\nAction Input: {"query": "crew"}',
+    )
+
+    assert json.loads(result) == {"query": "crew", "score": 0.7}
+    assert raw_results == [SearchOutput(query="crew", score=0.7)]
+    tools_handler.on_tool_use.assert_called_once()
+    assert tools_handler.on_tool_use.call_args.kwargs["output"] == SearchOutput(
+        query="crew",
+        score=0.7,
+    )
+
+
+def test_react_tool_hooks_receive_agent_text_and_raw_cached_typed_output():
+    structured_tool = TypedSearchTool().to_structured_tool()
+    tools_handler = ToolsHandler(cache=CacheHandler())
+    seen_results: list[tuple[str | None, object]] = []
+
+    def after_hook(context: ToolCallHookContext) -> None:
+        seen_results.append((context.tool_result, context.raw_tool_result))
+
+    clear_after_tool_call_hooks()
+    register_after_tool_call_hook(after_hook)
+
+    action = AgentAction(
+        thought="",
+        tool="typed_search",
+        tool_input='{"query": "crew"}',
+        text='Action: typed_search\nAction Input: {"query": "crew"}',
+    )
+
+    try:
+        first = execute_tool_and_check_finality(
+            agent_action=action,
+            tools=[structured_tool],
+            tools_handler=tools_handler,
+        )
+        tools_handler.last_used_tool = None
+        second = execute_tool_and_check_finality(
+            agent_action=action,
+            tools=[structured_tool],
+            tools_handler=tools_handler,
+        )
+    finally:
+        clear_after_tool_call_hooks()
+
+    assert json.loads(first.result) == {"query": "crew", "score": 0.7}
+    assert json.loads(second.result) == {"query": "crew", "score": 0.7}
+    assert seen_results == [
+        ('{"query":"crew","score":0.7}', SearchOutput(query="crew", score=0.7)),
+        ('{"query":"crew","score":0.7}', SearchOutput(query="crew", score=0.7)),
+    ]
+
+
+def test_last_raw_result_falls_back_only_until_recorded():
+    tool_usage = ToolUsage(
+        tools_handler=None,
+        tools=[],
+        task=None,
+        function_calling_llm=MagicMock(),
+        agent=None,
+        action=MagicMock(),
+    )
+
+    assert tool_usage.get_last_raw_result("formatted result") == "formatted result"
+
+    tool_usage.last_raw_result = None
+
+    assert tool_usage.get_last_raw_result("formatted result") is None
+
+
 def test_validate_tool_input_booleans_and_none():
     tool_usage = ToolUsage(
         tools_handler=MagicMock(),

lib/crewai/tests/utilities/test_agent_utils.py

@@ -3,12 +3,19 @@
 from __future__ import annotations
 
 import asyncio
+import json
 from typing import Any, Literal, Optional
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 from pydantic import BaseModel, Field
 
+from crewai.hooks.tool_hooks import (
+    ToolCallHookContext,
+    clear_after_tool_call_hooks,
+    clear_before_tool_call_hooks,
+    register_after_tool_call_hook,
+)
 from crewai.tools.base_tool import BaseTool
 from crewai.utilities.agent_utils import (
     _asummarize_chunks,
@@ -1030,6 +1037,142 @@ class TestParseToolCallArgs:
 class TestExecuteSingleNativeToolCall:
     """Tests for execute_single_native_tool_call."""
 
+    def test_typed_tool_output_is_json_agent_text(self) -> None:
+        clear_before_tool_call_hooks()
+        clear_after_tool_call_hooks()
+
+        class SearchOutput(BaseModel):
+            query: str
+            score: float
+
+        class TypedSearchTool(BaseTool):
+            name: str = "typed_search"
+            description: str = "Search for a query"
+            result_schema: type[BaseModel] = SearchOutput
+
+            def _run(self, query: str) -> SearchOutput:
+                return SearchOutput(query=query, score=0.9)
+
+        tool = TypedSearchTool()
+        tool_call = MagicMock()
+        tool_call.id = "call_1"
+        tool_call.function.name = "typed_search"
+        tool_call.function.arguments = '{"query": "crew"}'
+
+        result = execute_single_native_tool_call(
+            tool_call,
+            available_functions={"typed_search": tool._run},
+            original_tools=[tool],
+            structured_tools=[tool.to_structured_tool()],
+            tools_handler=None,
+            agent=None,
+            task=None,
+            crew=None,
+            event_source=MagicMock(),
+            printer=None,
+            verbose=False,
+        )
+
+        assert json.loads(result.result) == {"query": "crew", "score": 0.9}
+        assert json.loads(result.tool_message["content"]) == {
+            "query": "crew",
+            "score": 0.9,
+        }
+
+    def test_custom_agent_output_formatter_is_used_from_structured_tool(
+        self,
+    ) -> None:
+        clear_before_tool_call_hooks()
+        clear_after_tool_call_hooks()
+
+        class SearchOutput(BaseModel):
+            query: str
+            score: float
+
+        class MarkdownSearchTool(BaseTool):
+            name: str = "markdown_search"
+            description: str = "Search for a query"
+            result_schema: type[BaseModel] = SearchOutput
+
+            def _run(self, query: str) -> SearchOutput:
+                return SearchOutput(query=query, score=0.9)
+
+            def format_output_for_agent(self, raw_result: Any) -> str:
+                result = self.result_schema.model_validate(raw_result)
+                return f"### {result.query}\n\nScore: **{result.score}**"
+
+        tool = MarkdownSearchTool()
+        tool_call = MagicMock()
+        tool_call.id = "call_1"
+        tool_call.function.name = "markdown_search"
+        tool_call.function.arguments = '{"query": "crew"}'
+
+        result = execute_single_native_tool_call(
+            tool_call,
+            available_functions={"markdown_search": tool._run},
+            original_tools=[],
+            structured_tools=[tool.to_structured_tool()],
+            tools_handler=None,
+            agent=None,
+            task=None,
+            crew=None,
+            event_source=MagicMock(),
+            printer=None,
+            verbose=False,
+        )
+
+        assert result.result == "### crew\n\nScore: **0.9**"
+        assert result.tool_message["content"] == "### crew\n\nScore: **0.9**"
+
+    def test_after_hook_includes_raw_tool_result_for_typed_output(self) -> None:
+        clear_after_tool_call_hooks()
+
+        class SearchOutput(BaseModel):
+            query: str
+            score: float
+
+        class TypedSearchTool(BaseTool):
+            name: str = "typed_search"
+            description: str = "Search for a query"
+            result_schema: type[BaseModel] = SearchOutput
+
+            def _run(self, query: str) -> SearchOutput:
+                return SearchOutput(query=query, score=0.9)
+
+        seen_results: list[tuple[str | None, object]] = []
+
+        def after_hook(context: ToolCallHookContext) -> None:
+            seen_results.append((context.tool_result, context.raw_tool_result))
+
+        tool = TypedSearchTool()
+        tool_call = MagicMock()
+        tool_call.id = "call_1"
+        tool_call.function.name = "typed_search"
+        tool_call.function.arguments = '{"query": "crew"}'
+
+        register_after_tool_call_hook(after_hook)
+        try:
+            result = execute_single_native_tool_call(
+                tool_call,
+                available_functions={"typed_search": tool._run},
+                original_tools=[tool],
+                structured_tools=[tool.to_structured_tool()],
+                tools_handler=None,
+                agent=None,
+                task=None,
+                crew=None,
+                event_source=MagicMock(),
+                printer=None,
+                verbose=False,
+            )
+        finally:
+            clear_after_tool_call_hooks()
+
+        assert json.loads(result.result) == {"query": "crew", "score": 0.9}
+        assert seen_results == [
+            ('{"query":"crew","score":0.9}', SearchOutput(query="crew", score=0.9))
+        ]
+
     def test_result_as_answer_false_on_tool_error(self) -> None:
         """When a tool with result_as_answer=True raises, result_as_answer must be False.
 

lib/devtools/src/crewai_devtools/__init__.py

@@ -1,3 +1,3 @@
 """CrewAI development tools."""
 
-__version__ = "1.14.8a1"
+__version__ = "1.14.8a2"

uv.lock

@@ -117,7 +117,7 @@ wheels = [
 
 [[package]]
 name = "aiobotocore"
-version = "3.4.0"
+version = "3.5.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "aiohttp" },
@@ -129,9 +129,9 @@ dependencies = [
     { name = "typing-extensions", marker = "python_full_version < '3.11'" },
     { name = "wrapt" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/b8/50/a48ed11b15f926ce3dbb33e7fb0f25af17dbb99bcb7ae3b30c763723eca7/aiobotocore-3.4.0.tar.gz", hash = "sha256:a918b5cb903f81feba7e26835aed4b5e6bb2d0149d7f42bb2dd7d8089e3d9000", size = 122360, upload-time = "2026-04-07T06:12:24.884Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/e6/89/9533b377e9412013cc43a539d81bc5f8feeb4b6830643821ad612f78b09b/aiobotocore-3.5.0.tar.gz", hash = "sha256:d45d1c4659ad0e48b694a5aa4ff18829100386f7de96c8d146ec7757a6f12918", size = 123061, upload-time = "2026-04-21T07:25:26.993Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/df/d8/ce9386e6d76ea79e61dee15e62aa48cff6be69e89246b0ac4a11857cb02c/aiobotocore-3.4.0-py3-none-any.whl", hash = "sha256:26290eb6830ea92d8a6f5f90b56e9f5cedd6d126074d5db63b195e281d982465", size = 88018, upload-time = "2026-04-07T06:12:22.684Z" },
+    { url = "https://files.pythonhosted.org/packages/2d/05/6eeeadef45c24630af0ceae4d038b883e9a394786300529286ba8cc1e62d/aiobotocore-3.5.0-py3-none-any.whl", hash = "sha256:49ce35bb8b96b85d3251c2cbbb2ed7a028dc0cb0d0d0801f9ccca1ccd0d41ded", size = 88281, upload-time = "2026-04-21T07:25:25.258Z" },
 ]
 
 [[package]]
@@ -657,7 +657,7 @@ wheels = [
 
 [[package]]
 name = "bedrock-agentcore"
-version = "1.6.0"
+version = "1.7.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "boto3" },
@@ -669,9 +669,9 @@ dependencies = [
     { name = "uvicorn" },
     { name = "websockets" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/ca/f6/2884c954343e794e3419348f5ffb0276a26f57b30af11f9fe63c4ca535c0/bedrock_agentcore-1.6.0.tar.gz", hash = "sha256:7ea176c3226dc6af8c399a8f9abb58629948cd8ed8675ece9f2f32b94e861b92", size = 512010, upload-time = "2026-03-31T23:10:06.561Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/01/65/69a66d812c5f86b902234fe91146004efcea907444a60f024f9afe13d150/bedrock_agentcore-1.7.0.tar.gz", hash = "sha256:cf632892f6bd055ce047eb91fe4d72f86569234faf3eb5cd1b2b614261a77d7f", size = 540824, upload-time = "2026-04-28T19:29:02.749Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/a2/f8/bcf158979324f4f4d171588afffadb2154fa8499701290bfc7bdaf82bd3a/bedrock_agentcore-1.6.0-py3-none-any.whl", hash = "sha256:a4cd02f2bfb80fcc7a8c8835be8d55c778339f8286b071ac3aae579460dd2eb2", size = 164034, upload-time = "2026-03-31T23:10:04.902Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/9d/5f590afd5351e206d9a02f96777a69d1fc3edecfaa39bbba310248f21ea9/bedrock_agentcore-1.7.0-py3-none-any.whl", hash = "sha256:ee49695e613973baf01b4be400d3bc4b20ddedf3638765fb3bc6931a87fa0cd9", size = 178978, upload-time = "2026-04-28T19:29:00.944Z" },
 ]
 
 [[package]]
@@ -685,16 +685,16 @@ wheels = [
 
 [[package]]
 name = "boto3"
-version = "1.42.84"
+version = "1.42.91"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "botocore" },
     { name = "jmespath" },
     { name = "s3transfer" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/88/89/2d647bd717da55a8cc68602b197f53a5fa36fb95a2f9e76c4aff11a9cfd1/boto3-1.42.84.tar.gz", hash = "sha256:6a84b3293a5d8b3adf827a54588e7dcffcf0a85410d7dadca615544f97d27579", size = 112816, upload-time = "2026-04-06T19:39:07.585Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/a7/c0/98b8cec7ca22dde776df48c58940ae1abc425593959b7226e270760d726f/boto3-1.42.91.tar.gz", hash = "sha256:03d70532b17f7f84df37ca7e8c21553280454dea53ae12b15d1cfef9b16fcb8a", size = 113181, upload-time = "2026-04-17T19:31:06.251Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/2d/31/cdf4326841613d1d181a77b3038a988800fb3373ca50de1639fba9fa87de/boto3-1.42.84-py3-none-any.whl", hash = "sha256:4d03ad3211832484037337292586f71f48707141288d9ac23049c04204f4ab03", size = 140555, upload-time = "2026-04-06T19:39:06.009Z" },
+    { url = "https://files.pythonhosted.org/packages/02/29/faba6521257c34085cc9b439ef98235b581772580f417fa3629728007270/boto3-1.42.91-py3-none-any.whl", hash = "sha256:04e72071cde022951ce7f81bd9933c90095ab8923e8ced61c8dacfe9edac0f5c", size = 140553, upload-time = "2026-04-17T19:31:02.57Z" },
 ]
 
 [[package]]
@@ -718,16 +718,16 @@ bedrock-runtime = [
 
 [[package]]
 name = "botocore"
-version = "1.42.84"
+version = "1.42.91"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "jmespath" },
     { name = "python-dateutil" },
     { name = "urllib3" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/b4/b7/1c03423843fb0d1795b686511c00ee63fed1234c2400f469aeedfd42212f/botocore-1.42.84.tar.gz", hash = "sha256:234064604c80d9272a5e9f6b3566d260bcaa053a5e05246db90d7eca1c2cf44b", size = 15148615, upload-time = "2026-04-06T19:38:56.673Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/21/bc/a4b7c46471c2e789ad8c4c7acfd7f302fdb481d93ff870f441249b924ae6/botocore-1.42.91.tar.gz", hash = "sha256:d252e27bc454afdbf5ed3dc617aa423f2c855c081e98b7963093399483ecc698", size = 15213010, upload-time = "2026-04-17T19:30:50.793Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/e3/37/0c0c90361c8a1b9e6c75222ca24ae12996a298c0e18822a72ab229c37207/botocore-1.42.84-py3-none-any.whl", hash = "sha256:15f3fe07dfa6545e46a60c4b049fe2bdf63803c595ae4a4eec90e8f8172764f3", size = 14827061, upload-time = "2026-04-06T19:38:53.613Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/fc/24cc0a47c824f13933e210e9ad034b4fba22f7185b8d904c0fbf5a3b2be8/botocore-1.42.91-py3-none-any.whl", hash = "sha256:7a28c3cc6bfab5724ad18899d52402b776a0de7d87fa20c3c5270bcaaf199ce8", size = 14897344, upload-time = "2026-04-17T19:30:44.245Z" },
 ]
 
 [[package]]
@@ -1413,7 +1413,7 @@ watson = [
 [package.metadata]
 requires-dist = [
     { name = "a2a-sdk", marker = "extra == 'a2a'", specifier = "~=0.3.10" },
-    { name = "aiobotocore", marker = "extra == 'aws'", specifier = "~=3.4.0" },
+    { name = "aiobotocore", marker = "extra == 'aws'", specifier = "~=3.5.0" },
     { name = "aiocache", extras = ["memcached", "redis"], marker = "extra == 'a2a'", specifier = "~=0.12.3" },
     { name = "aiofiles", specifier = "~=24.1.0" },
     { name = "aiosqlite", specifier = "~=0.21.0" },
@@ -1421,8 +1421,8 @@ requires-dist = [
     { name = "appdirs", specifier = "~=1.4.4" },
     { name = "azure-ai-inference", marker = "extra == 'azure-ai-inference'", specifier = "~=1.0.0b9" },
     { name = "azure-identity", marker = "extra == 'azure-ai-inference'", specifier = ">=1.17.0,<2" },
-    { name = "boto3", marker = "extra == 'aws'", specifier = "~=1.42.79" },
-    { name = "boto3", marker = "extra == 'bedrock'", specifier = "~=1.42.79" },
+    { name = "boto3", marker = "extra == 'aws'", specifier = "~=1.42.90" },
+    { name = "boto3", marker = "extra == 'bedrock'", specifier = "~=1.42.90" },
     { name = "cel-python", specifier = ">=0.5.0,<0.6" },
     { name = "chromadb", specifier = "~=1.1.0" },
     { name = "click", specifier = ">=8.1.7,<9" },
@@ -1734,7 +1734,7 @@ requires-dist = [
     { name = "beautifulsoup4", specifier = "~=4.13.4" },
     { name = "beautifulsoup4", marker = "extra == 'beautifulsoup4'", specifier = ">=4.12.3" },
     { name = "beautifulsoup4", marker = "extra == 'bedrock'", specifier = ">=4.13.4" },
-    { name = "bedrock-agentcore", marker = "extra == 'bedrock'", specifier = ">=0.1.0" },
+    { name = "bedrock-agentcore", marker = "extra == 'bedrock'", specifier = ">=1.7.0,<1.8.0" },
     { name = "browserbase", marker = "extra == 'browserbase'", specifier = ">=1.0.5" },
     { name = "composio-core", marker = "extra == 'composio-core'", specifier = ">=0.6.11.post1" },
     { name = "contextual-client", marker = "extra == 'contextual'", specifier = ">=0.1.0" },