Skip to content
Zurück zur Startseite

§ INTEGRATION · CREWAI

CrewAI-Instrumentierung

Ein einziger Aufruf verdrahtet Execlave mit Step- und Task-Callbacks, erhält Ihre bestehenden Callbacks und erzwingt Tool-Allowlist-Policies vor jedem Tool-Call.

§ 01

Voraussetzungen

  • Execlave-Konto mit aktivem API-Schlüssel — Einstellungen → API-Schlüssel.
  • Ein registrierter Agent / eine registrierte Crew in Execlave. Verwenden Sie die kleingeschriebene Kebab-Case-agent_id der Crew beim Aufruf von instrument_crew.
  • Python >=3.10 und crewai >=0.80,<1.
  • JavaScript wird nicht unterstützt — CrewAI ist Python-only.
§ 02

Installation

CrewAI wird als optionales Extra bereitgestellt, sodass die Standardinstallation des SDK crewai nicht als transitive Abhängigkeit mit installiert.

Python

pip install 'execlave-sdk[crewai]'
§ 03

Sofort einrichten mit einem Copilot

Fügen Sie diesen Prompt in Ihren KI-Coding-Assistenten ein. Er fügt einen einzigen Aufruf vor kickoff() ein, ohne Agent-, Task- oder Tool-Definitionen zu verändern.

§ Copy prompt · paste into your AI coding assistant
You are adding Execlave (an AI agent governance platform) to an existing Python project that uses CrewAI. Do not rewrite existing Agents, Tasks, or Crews — only attach instrumentation. Rules you MUST follow:1. Install the correct extra: `pip install 'execlave-sdk[crewai]'`. Add it to requirements.txt / pyproject.toml.2. Read `EXECLAVE_API_KEY` from environment variables. Never hardcode keys. Add it to `.env.example`.3. Create exactly ONE Execlave client per process and reuse it: `exe = Execlave(api_key=os.environ["EXECLAVE_API_KEY"])`.4. Call `instrument_crew(crew, exe, agent_id="<stable-kebab-id>")` immediately before `crew.kickoff()`. The import is `from execlave.integrations.crewai import instrument_crew`. The `agent_id` is a stable kebab-case string identifying this crew in the Execlave dashboard — NOT a CrewAI role name.5. `instrument_crew` CHAINS onto any existing `step_callback` / `task_callback`. It never overwrites user callbacks. Do NOT remove or replace callbacks the project already has set.6. `instrument_crew` is IDEMPOTENT — a `_execlave_instrumented` marker is set on the crew so calling it twice is a no-op. Do not guard it with your own "already instrumented" check.7. Wrap `crew.kickoff()` in try/except for `execlave.errors.PolicyBlockedError`. On block, return a structured 4xx payload containing `exc.violations`. Do NOT swallow the error silently.8. Do NOT manually call `exe.enforce_policy` for tool calls — the wrapped `step_callback` enforces before each tool step. Enforcement runs only for steps with a non-empty `tool` attribute; pure-reasoning steps are recorded but not enforced.9. Each `Agent` inside the crew is instrumented in addition to the crew itself, so sub-agent tool calls are captured. You do NOT need to pass each agent separately.10. On process shutdown (ASGI lifespan / SIGTERM handler), call `exe.flush()` so in-flight spans are not dropped.11. JavaScript is NOT supported — CrewAI is Python-only. If the project is Node/TS, stop and tell me. Deliverables:- Edit only the file that builds and kicks off the Crew. One diff per file.- Do not touch Agent, Task, or tool definitions.- Add `EXECLAVE_API_KEY` and optional `EXECLAVE_BASE_URL` to `.env.example`. Reference: https://www.execlave.com/docs/integrations/crewaiAPI reference: https://www.execlave.com/docs/sdk-reference
§ 04

Schnellstart

Erstellen Sie die Crew wie gewohnt, rufen Sie einmal instrument_crew() auf und dann kickoff(). Jeder Agent-Schritt, Tool-Call und Task-Abschluss landet im Dashboard unter einer einzigen Trace-ID.

Python

from crewai import Agent, Crew, Taskfrom execlave import Execlavefrom execlave.integrations.crewai import instrument_crew exe = Execlave(api_key="exe_prod_...") researcher = Agent(role="Researcher", goal="Find Q3 pipeline facts", backstory="…")writer     = Agent(role="Writer",     goal="Summarise for leadership",  backstory="…") task1 = Task(description="Pull pipeline from Salesforce", agent=researcher, expected_output="csv")task2 = Task(description="Write 5-bullet summary",        agent=writer,     expected_output="md") crew = Crew(agents=[researcher, writer], tasks=[task1, task2]) # Idempotent — safe to call repeatedly. Chains onto any existing# step_callback / task_callback rather than replacing it.instrument_crew(crew, exe, agent_id="q3-review-crew") result = crew.kickoff()
§ 05

Callback-Verkettung (keine Ersetzung)

Wenn eine Crew oder ein Agent bereits step_callback oder task_callback gesetzt hat, umschließt Execlave den bestehenden Callback, statt ihn zu überschreiben — Ihre Hooks werden weiterhin ausgeführt.

Verkettungssemantik

  • Der Callback von Execlave läuft zuerst; löst er eine Policy-Blockierung aus, bricht der Crew-Lauf ab, bevor Ihr Callback den Schritt sieht.
  • War der Callback von Execlave erfolgreich, wird Ihr bereits bestehender Callback mit demselben Payload aufgerufen.
  • Eine _execlave_instrumented-Markierung auf der Crew macht wiederholte Aufrufe von instrument_crew() zu einem No-op — sicher für Hot Paths oder Auto-Reloader.
  • Reine Attribut-Erkennung — keine strukturellen Annahmen über CrewAI-Step-Objekte. Kleinere CrewAI-Updates erfordern kein Execlave-Release.
§ 06

Tool-Enforcement

CrewAI-Step-Objekte stellen die Attribute tool und tool_input bereit. Execlave erkennt Tool-Steps und führt enforce_policy aus, bevor das Tool ausgeführt wird, sodass Block-Modus-Policies die Crew stoppen, bevor das Tool aufgerufen wird.

Eine Blockierung abfangen

from execlave.errors import PolicyBlockedError try:    result = crew.kickoff()except PolicyBlockedError as exc:    # A block-mode policy matched a tool call inside the crew; kickoff aborts    # BEFORE the tool was executed. exc.violations holds the matches.    return {"error": "blocked", "violations": exc.violations}
§ 07

Betriebsgarantien

Garantien

  • Enforcement-Ausnahmen werden weitergeworfen, sodass Block-Modus-Policies die Crew stoppen; alle anderen Ausnahmen innerhalb der Callbacks von Execlave werden protokolliert und abgefangen.
  • Jeder Agent innerhalb der Crew wird zusätzlich zur Crew selbst instrumentiert, sodass Tool-Calls von Sub-Agenten ohne zusätzliche Aufrufe erfasst werden.
  • Verhindern Pydantic-Freezes das Setzen der Markierung, degradiert der Doppel-Wrap-Schutz kontrolliert (protokolliert, nicht fatal).
§ 08

Wie geht es weiter?

CrewAI-Integration — Execlave Docs