Skip to main content

CrewAI quickstart — governed bridge tools

This guide turns one tool advertised by cordum-mcp-bridge into a CrewAI BaseTool. Only calls through that generated tool are governed by Cordum.

Before you start​

  • Python 3.10+; Python 3.11 and 3.12 are CI-covered.
  • A configured CrewAI model provider.
  • Cordum bootstrapped with ./tools/scripts/quickstart.sh.
  • cordum-mcp-bridge on PATH.
  • The secure environment from Framework integrations.

1. Install​

python -m venv .venv
source .venv/bin/activate
pip install "cordum-adapters[crewai]"

:::note Windows / MSYS Put cordum-mcp-bridge.exe on PATH. The adapter starts it as a subprocess; do not hard-code a platform-specific executable path in the script. :::

2. Build a Crew around an advertised tool​

Save as crewai_quickstart.py:

import os

from crewai import Agent, Crew, Process, Task
from cordum_agent_adapters.crewai import build_crewai_tools
from cordum_agent_adapters.mcp_client import McpStdioClient

TOOL_NAME = "cordum.workflow.run"


def require_tool(tool_defs: list[dict], name: str) -> list[dict]:
    selected = [tool for tool in tool_defs if tool.get("name") == name]
    if not selected:
        advertised = sorted(str(tool.get("name")) for tool in tool_defs)
        raise RuntimeError(f"{name} is not advertised; got {advertised}")
    return selected


with McpStdioClient(
    command=["cordum-mcp-bridge"],
    env=os.environ.copy(),
) as client:
    selected = require_tool(client.list_tools(), TOOL_NAME)
    tools = build_crewai_tools(client, tools=selected)

    operator = Agent(
        role="Workflow operator",
        goal="Run only the requested Cordum workflow in dry-run mode",
        backstory="You use the single Cordum tool assigned to you.",
        tools=tools,
        allow_delegation=False,
        verbose=True,
    )
    task = Task(
        description=(
            "Use the Cordum workflow tool to start demo-workflow with "
            "dry_run=true and empty input. Report the returned governance "
            "outcome without inventing identifiers."
        ),
        expected_output="The actual bridge response or governance error.",
        agent=operator,
    )
    result = Crew(
        agents=[operator],
        tasks=[task],
        process=Process.sequential,
        verbose=True,
    ).kickoff()
    print(result)

Run it after loading the common TLS environment:

python crewai_quickstart.py

Replace demo-workflow with a workflow in your tenant. The script checks the live catalog before it creates the Crew, so a missing bridge tool is an explicit setup error rather than a fabricated example.

3. Add a v1 hard-deny rule​

The bridge maps each call to a Cordum job whose capability is the tool name:

version: v1
rules:
  - id: block-tutorial-workflow-run
    match:
      capabilities:
        - cordum.workflow.run
    decision: deny
    reason: "Tutorial hard-deny check"

Upload this bundle through the HTTPS policy-bundle API and run the script again. A hard deny returns isError: true; McpStdioClient raises McpToolError, and the CrewAI adapter returns the tool error through CrewAI's tool-result path.

4. Distinguish an approval hold​

The pack bridge leaves an approval-gated job nonterminal and blocks the original CrewAI tool call. Resolve the job in the dashboard before the bounded CORDUM_MCP_CALL_TIMEOUT; approval lets that same call continue. If the wait expires, the bridge returns a tool error. There is no approval-reference retry on this bridge.

Verify​

Use the dashboard to inspect events produced by this run. Confirm the tool name, capability, tenant, and actual decision. Do not infer that CrewAI calls made outside tools were intercepted.

What's next​