§ 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.
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_idder Crew beim Aufruf voninstrument_crew. - Python
>=3.10undcrewai >=0.80,<1. - JavaScript wird nicht unterstützt — CrewAI ist Python-only.
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]'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.
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-referenceSchnellstart
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()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 voninstrument_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.
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}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).