CrewAI Integration Guide

This page is intentionally extensive. It is designed so a human or an LLM can use it as a single, authoritative reference to implement MachineID hard enforcement into CrewAI step-by-step, with minimal guesswork.

Everything reduces to one invariant:

Register. Validate. Work.

If validation fails, work does not begin.

In practice, this means you choose explicit boundaries in your CrewAI runtime where validation must occur. Those boundaries become your “stop points” for revocation, device limits, and org-wide disable.

This is the fastest path to a known-good integration: run the official CrewAI template, then confirm you can stop it remotely.

# Python 3.11 is recommended for CrewAI installs
git clone https://github.com/machineid-io/crewai-machineid-template.git
cd crewai-machineid-template

python3.11 -m venv venv311
source venv311/bin/activate
pip install -r requirements.txt

export MACHINEID_ORG_KEY=org_your_key_here
export OPENAI_API_KEY=sk_your_openai_key_here

# Optional: pick a deterministic device id
export MACHINEID_DEVICE_ID=crewai:dev:runner:01

python crewai_agent.py

In MachineID, a “device” is an identity representing an execution surface. In CrewAI, that maps cleanly to things like:

• One agent runner process (the Python process that calls crew.kickoff())
• One worker replica (multiple containers/instances running the same CrewAI code)
• One scheduled job instance (e.g. “nightly-run-01”)
• One event-consumer instance that triggers CrewAI execution

Device identity is not a secret. Your org key (org_...) is the credential. Device IDs are stable labels for audit and revoke.

CrewAI provides natural execution boundaries. Use them to make enforcement predictable.

Validation must be treated as safety-critical. Use a short timeout and fail closed. If you cannot confirm permission, do not execute.

If you want a known-good baseline, start here: machineid-io/crewai-machineid-template .

For most CrewAI projects, the Python SDK is the cleanest integration surface: machineid-io/python-sdk .

pip install machineid-io

import os
from machineid import MachineID

m = MachineID.from_env()

device_id = os.getenv("MACHINEID_DEVICE_ID", "crewai:dev:runner:01")

# Register device (idempotent)
m.register(device_id)

# HARD GATE — MUST stop execution if denied
decision = m.validate(device_id)

if not decision["allowed"]:
    print("Execution denied:", decision.get("code"), decision.get("request_id"))
    raise SystemExit(1)

print("Execution allowed")

Device IDs should be stable enough to audit, but specific enough to revoke. A common pattern is:

{framework}:{env}:{role}:{instance}

Examples that map cleanly to CrewAI execution surfaces:

• crewai:dev:researcher:01
• crewai:prod:planner:02
• crewai:prod:tool-runner:05
• crewai:prod:cron-nightly:01
• crewai:prod:event-consumer:07

This is the minimum CrewAI boundary. Always validate immediately before kickoff.

from machineid import MachineID

m = MachineID.from_env()
device_id = "crewai:prod:runner:01"

m.register(device_id)

# Gate BEFORE kickoff
decision = m.validate(device_id)
if not decision["allowed"]:
    raise SystemExit(1)

# Now kickoff
result = crew.kickoff(inputs={...})

CrewAI supports “before LLM call” hooks. This is a strong enforcement boundary because every reasoning step depends on LLM calls.

import os
from machineid import MachineID
from crewai.hooks import before_llm_call

m = MachineID.from_env()
DEVICE_ID = os.getenv("MACHINEID_DEVICE_ID", "crewai:prod:runner:01")

m.register(DEVICE_ID)

@before_llm_call
def machineid_gate_llm(context):
    decision = m.validate(DEVICE_ID)
    if not decision["allowed"]:
        print("MachineID denied LLM call:", decision.get("code"), decision.get("request_id"))
        return False
    return None  # allow

CrewAI supports “before tool call” hooks. This is one of the highest-leverage boundaries because tools are where side effects begin.

import os
from machineid import MachineID
from crewai.hooks import before_tool_call

m = MachineID.from_env()
DEVICE_ID = os.getenv("MACHINEID_DEVICE_ID", "crewai:prod:runner:01")

m.register(DEVICE_ID)

HIGH_RISK_TOOLS = set([
    "send_email",
    "charge_card",
    "place_order",
    "write_to_production_db",
])

@before_tool_call
def machineid_gate_tool(context):
    decision = m.validate(DEVICE_ID)
    if not decision["allowed"]:
        print("MachineID denied tool call:", decision.get("code"), decision.get("request_id"))
        return False

    if context.tool_name in HIGH_RISK_TOOLS:
        # Optional: additional validate immediately before risk
        decision2 = m.validate(DEVICE_ID)
        if not decision2["allowed"]:
            print("MachineID denied high-risk tool:", decision2.get("code"), decision2.get("request_id"))
            return False

    return None

Tool hooks cover many cases, but you still need explicit enforcement around irreversible actions. This is especially important if your tools call other services that can cause spend or state change.

def commit_side_effect(m, device_id):
    decision = m.validate(device_id)
    if not decision["allowed"]:
        raise SystemExit(1)

    perform_irreversible_action()

This tier is enough to model a real “stop boundary” in a small system and to validate your enforcement placement.

This is where distributed execution becomes the default: multiple runners, scheduled jobs, event consumers, and tool-heavy workers.

At this scale, the risk shifts from “one run lasts too long” to “many surfaces spawn and fan out under load.” Identity strategy and boundary placement become the control system.

At the upper end of standard caps, the dominant failure mode is systemic multiplication: retries, event storms, recursive task creation, and many simultaneous execution surfaces.

If your system requires device counts beyond standard tiers, MachineID supports custom device limits. The implementation pattern remains the same: identity per execution surface, and explicit validation boundaries.

MachineID includes a console at machineid.io/dashboard. This is intentionally separate from your agent runtime.

In addition to revoking individual devices, you can disable validation org-wide (a hard stop mechanism). This blocks execution across all devices at the next validate.

External control is designed for intervention from anywhere: a different laptop, a phone, or a secure ops environment that does not have access to the runtime.

These patterns defeat the entire purpose of external enforcement:

• “Proceed anyway but log a warning”
• “Continue for N minutes while validation is down”
• “Fallback to an internal env flag if validation fails”
• “Validate once at boot and never again in long-running loops”

In early prototypes, it can look like “kill switches” and internal flags are enough. As systems become more agentic and more distributed, the failure modes change: execution surfaces multiply, and control becomes a topology problem, not a single-process problem.

These prompts are designed so a user can paste them into an LLM and get an exact, step-by-step implementation plan. Replace the bracketed placeholders.

I have a Python CrewAI project. I want hard enforcement using MachineID.io

Constraints:
- I will use the MachineID Python SDK (pip install machineid-io).
- My org key is: [PASTE ORG KEY]
- My device id strategy should be: crewai:[env]:[role]:[instance]
- I want fail-closed behavior with a short timeout.
- I want validation at: (1) startup, (2) before crew.kickoff(), (3) before every tool call, (4) before every LLM call.

Please give me:
1) The exact files/locations to change
2) Copy/paste code blocks
3) Where to put environment variables
4) A test plan: revoke device + org disable from dashboard, and how the process should behave

I want to start from the official CrewAI template:
https://github.com/machineid-io/crewai-machineid-template

Goal:
- Add hard enforcement boundaries (startup + kickoff + tool-call hook + LLM-call hook)
- Keep device IDs deterministic and auditable

Please provide:
1) Exact terminal commands to run the template
2) The exact files to edit and the full copy/paste code changes
3) A test plan using the dashboard to revoke/unrevoke and org-disable

• CrewAI template: machineid-io/crewai-machineid-template
• Python SDK: machineid-io/python-sdk
• MachineID GitHub org: github.com/machineid-io
• Dashboard: machineid.io/dashboard
• Core operational guidance: Implementation Guide and Operational Guarantees

← Back to Docs