* Fix Anthropic native provider to include cache tokens in input totals.
Anthropic reports cache read and cache creation separately from input_tokens; fold them into input_tokens and total_tokens so billed usage is not underreported on cached workloads.
* Reconcile unreconciled Anthropic cache tokens in UsageMetrics.
LiteLLM and flow event paths can pass raw Anthropic usage where input_tokens excludes cache counters; fold them into prompt and total tokens without double-counting native provider payloads.
Co-authored-by: Cursor <cursoragent@cursor.com>
* Document UsageMetrics token field semantics for flows and crews.
Clarify that total_tokens is prompt plus completion, breakdown fields are not additive, and Anthropic cache counters are folded into prompt_tokens.
Co-authored-by: Cursor <cursoragent@cursor.com>
* Document Anthropic cache token accounting in LLM provider docs.
Explain how split Anthropic input counters map to UsageMetrics and link to the flows field semantics section.
Co-authored-by: Cursor <cursoragent@cursor.com>
* Restore cache_creation_tokens breakdown in UsageMetrics normalization.
Keep cache writes as a separate breakdown field while they remain folded into prompt_tokens for billed totals.
* Replace cross-page doc links with plain-text section references.
Avoid internal hyperlinks between concept pages for SEO; point readers to section names in prose instead.
* Apply ruff formatting to usage metrics helpers.
* Sync ar, ko, and pt-BR docs for Anthropic usage metrics updates.
Translate UsageMetrics semantics and Anthropic cache token accounting changes in crews, flows, and llms concept pages.
---------
Co-authored-by: Cursor <cursoragent@cursor.com>
* feat: emit FlowFailedEvent when a flow execution fails
A failed flow never emitted a terminal lifecycle event, so the
`flow_started` scope stayed open and consumers such as tracing closed the
root span with a generic orphaned message instead of the real error.
`kickoff_async` and the resume path now emit `FlowFailedEvent`, paired
with `flow_started` and carrying the exception, after draining pending
handlers and background memory writes. The resume path also emits the
`MethodExecutionStartedEvent` it was missing for the method being resumed,
so its finished or failed event pairs with its own scope instead of
popping the flow's.
* fix: skip FlowFailedEvent when the run never opened a scope
The `kickoff_async` try block starts before `FlowStartedEvent` is emitted,
so an abort in the execution-start hooks, in input handling or in state
restore emitted a `flow_failed` with no opener, which pops an unrelated
scope and warns about an empty scope stack. The failure event is now
gated on the flow scope actually being open, either from this kickoff's
`flow_started` or from a restored deferred session scope.
* feat(skills)!: promote Skills Repository out of experimental
The registry-backed Skills Repository (crewai skill create/publish/
install/list, @org/name refs, global cache) is now mainline:
- CLI: `crewai skill ...` is a top-level group; the CREWAI_EXPERIMENTAL
gate and the now-empty `crewai experimental` group are removed.
- Runtime: registry.py, cache.py, and events.py move from
crewai.experimental.skills into crewai.skills next to the loader;
the require_experimental_skills() gate is gone.
crewai.experimental.skills remains as a deprecated re-export shim.
- Docs: concepts/skills now leads with the CLI workflow and documents
the create -> publish -> install lifecycle.
Linear: n/a (requested promotion)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(skills): org-scoped publish only + docs in all languages
Skills are always scoped to the publishing organization, like tools:
drop the --public/--private flags from `crewai skill publish` and
always send is_public=False to the registry. CLI tests assert the flag
is rejected and the API never receives a public publish.
Translate the new CLI-first Quick Start and the create -> publish ->
install lifecycle section into ar, pt-BR, and ko concepts/skills docs.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(skills): address review comments on the promotion PR
- Back-compat shim now aliases the old submodules in sys.modules so
`crewai.experimental.skills.registry/cache/events` imports (and patch
targets) resolve to the real crewai.skills modules, not just the
package-root re-exports.
- `crewai skill publish` actually enforces the git-state check that
--force claims to skip: unsynced repos block publishing (mirroring
tool publish); standalone skill dirs outside any git repo publish
without a check.
- Explicit UTF-8 encoding on SKILL.md and cache-metadata reads/writes.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(skills): fail closed when git state cannot be validated on publish
Follow deploy's pattern: construct git.Repository(fetch=False) and only
treat "not a Git repository" as skippable — any other git error
(fetch/auth/misconfiguration) now blocks publish with a --force escape
hatch instead of silently bypassing the sync check.
Also single-style imports in the shim test (CodeQL) with the dotted
shim import covered via importlib.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(skills): fetch before sync check on publish; bump mcp past advisories
Publish now refreshes remote-tracking refs (repository.fetch()) before
is_synced(), so ahead/behind is judged against the actual remote rather
than stale local refs; a failing fetch blocks publish with the --force
escape hatch. Adds a fail-closed test for fetch errors.
Raise mcp to >=1.28.1,<2 (locks 1.28.1): the ~=1.26.0 pin blocked
GHSA-hvrp-rf83-w775 / GHSA-jpw9-pfvf-9f58 (fixed 1.27.2) and
GHSA-vj7q-gjh5-988w (fixed 1.28.1), which were failing pip-audit on
this PR.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Vinicius Brasil <vini@hey.com>
* feat: adopt directory-based docs versioning with Edge channel
Switch docs.crewai.com from navigation-only versioning (every version
selector entry rendered the same docs/<lang>/* source files) to
Mintlify's directory-based versioning so each version selector entry
renders its own snapshot. Add an "Edge" channel under docs/edge/<lang>/*
that always reflects main HEAD for unreleased work, eliminating
pre-release leakage onto frozen release labels. External links to
canonical /<lang>/* URLs are preserved via wildcard redirects that
always land on the current default version.
Layout:
- docs/edge/<lang>/* rolling source (you edit here)
- docs/edge/enterprise-api.*.yaml
- docs/v<X.Y.Z>/<lang>/* frozen, immutable snapshots
- docs/v<X.Y.Z>/enterprise-api.*.yaml
- docs/images/ shared, append-only
- docs/docs.json nav + redirects
URLs follow the Mintlify-idiomatic shape: /edge/<lang>/<page> for
Edge, /v<X.Y.Z>/<lang>/<page> for every frozen snapshot. The wildcard
redirects /<lang>/:slug* -> /<default>/<lang>/:slug* keep stale links
working, and every freeze rewrites them (plus all per-section/per-page
redirects) so destinations always resolve to the current default
without depending on a second redirect hop.
Release flow integration (devtools release):
- New module crewai_devtools.docs_versioning.freeze() materialises
docs/v<X.Y.Z>/ from docs/edge/, rewrites openapi: refs inside the
snapshot, inserts the version into every language block in
docs.json, and refreshes all redirect destinations.
- _update_docs_and_create_pr() in cli.py now calls that freeze during
Phase 2 of devtools release. Edge changelogs are updated first (so
the snapshot freeze picks them up), then the snapshot is staged
alongside docs.json, branched as docs/freeze-v<X.Y.Z>, and the PR
is titled [docs-freeze] docs: snapshot and changelog for v<X.Y.Z>
— the title prefix the new CI guard reads.
- The PR still gates tag, GitHub release, PyPI publish, and the
enterprise release as before; no new PRs are added.
- Pre-releases (1.X.YaN, 1.X.YbN, ...) skip the snapshot — they ride
Edge — and the docs PR title omits the [docs-freeze] prefix.
- docs_check (AI-generated docs scaffolding) writes to
docs/edge/<lang>/* so newly-generated unreleased docs land in Edge
and never accidentally touch a frozen snapshot.
Migration scripts (one-shot):
- scripts/docs/freeze_historical_versions.py reconstructs all 16
historical snapshots (v1.10.0 .. v1.14.7) from git tags via
git archive | tar, rewriting openapi: MDX refs so each snapshot
reads its own enterprise-api YAML rather than the live one.
- scripts/docs/prefix_version_paths.py one-shot-migrates docs.json:
rewrites every page path in 16 versioned blocks to point under
docs/v<X.Y.Z>/, inserts a new Edge entry per language, tags
v1.14.7 as Latest (default), prunes pages whose target file
doesn't exist in the snapshot (e.g. docs/ar/ didn't exist before
v1.12.0), and writes the wildcard + per-section redirects.
- scripts/docs/freeze_current_edge.py is now a thin CLI wrapper
around docs_versioning.freeze for manual one-off freezes (e.g.
retroactively snapshotting a forgotten release).
CI guards (.github/workflows/docs-snapshots.yml):
- Frozen snapshots under docs/v[0-9]*/ are immutable; only PRs whose
title contains [docs-freeze] (i.e. release-cut PRs generated by
devtools release or the manual wrapper) may modify them.
- Images under docs/images/ are append-only since snapshots share a
single image directory. Deleting or renaming an image breaks every
historical snapshot that still references it.
Restored docs/images/crewai-otel-export.png from PR #3673; it was
deleted in PR #4908 but v1.10.0 / v1.10.1 snapshots still reference
it. Restoring instead of editing the snapshots preserves historical
rendering fidelity and validates the new append-only rule
retroactively.
Tests:
- lib/devtools/tests/test_docs_versioning.py covers the freeze: file
copy, openapi rewrite, version insertion, default demotion, redirect
upserts, per-section redirect rewriting, idempotency, and invalid
inputs.
Verified locally with mintlify broken-links: 0 broken links across
the full site (Edge + 16 frozen versions, 4 locales).
AGENTS.md (repo root) is the contributor guide for the new model;
RELEASING.md is the release-cut runbook; README's Contribution
section links to both.
Co-authored-by: Cursor <cursoragent@cursor.com>
* style: resolve linter issues
---------
Co-authored-by: Cursor <cursoragent@cursor.com>
