CrewAI Quickstart

​

Install

pip install "visiq>=0.5.0" "crewai>=1.0"

​

Set environment variables

VISIQ_API_KEY=vq_prod_...
# VISIQ_ENDPOINT defaults to https://api.visiqlabs.com. Set it ONLY for
# onprem / self-hosted deployments. A bare VISIQ_API_KEY reaches the managed
# SaaS control plane, loads a bundle, and governs automatically.
VISIQ_AGENT_ID=support-bot

​

Govern your crew

# pip install visiq crewai
from crewai import Agent, Crew, Task
from crewai.tools import tool
from visiq import govern


@tool("issue_refund")
def issue_refund(customer_id: str, amount: int) -> str:
    """Issue a refund to a customer."""
    return f"Refunded ${amount} to {customer_id}"


@tool("search_knowledge")
def search_knowledge(query: str) -> list:
    """Search the knowledge base."""
    # Your real RAG store returns the same shape: a list of
    # {"page_content", "metadata"} dicts the retrieval facet can filter.
    return [
        {"page_content": f"Q3 revenue was $4.2M. (matched: {query})",
         "metadata": {"classification": "internal"}},
    ]


support = Agent(
    role="Support agent",
    goal="Resolve customer requests with the provided tools.",
    backstory="You are a helpful assistant.",
    tools=[issue_refund, search_knowledge],
    llm="gpt-4o-mini",
)
answer = Task(
    description="{request}",
    expected_output="A short answer for the customer.",
    agent=support,
)
crew = Crew(agents=[support], tasks=[answer])

# ── One call: every tool in this crew is now governed ──
govern(crew, agent_id="support-bot", retrieval_tools={"search_knowledge"})

print(crew.kickoff(inputs={"request": "What was Q3 revenue?"}).raw)

​

Run this on AWS Bedrock

from crewai import LLM

# Only the model changes. The tools, the crew and govern(...) stay exactly as
# written above.
llm = LLM(model="bedrock/amazon.nova-micro-v1:0", temperature=0)

​

What happens at runtime

• Decisions are local. The SDK fetches one cached rule bundle (GET /rules/bundle, ETag revalidation) and refreshes it in the background. Tool calls evaluate in-process; the only decision-path network call is waiting on a human approval.
• Fail-open by default, loudly — strict deny is opt-in. Real policy outcomes always enforce: an explicit rule deny, the operator kill-switch, and an in-core mask/redact that cannot be applied (it downgrades to deny) all block. A harness-internal failure does NOT block: if the backend is unreachable or the governance core is unavailable, the harness proceeds UNGOVERNED with a loud [VisIQ] FAIL-OPEN (no-bundle) report on stderr, so a VisIQ outage never disrupts your agent (owner decision, 2026-07-15). Set VISIQ_FAIL_MODE=closed to block those harness-internal failures instead.
• Deny blocks the call. The tool is never executed, and the model receives the block message as the tool result.
• Approvals pause the call. An approval_required decision holds the tool while a human decides via Slack or Email (Microsoft Teams delivery is built server-side; its connector card is coming soon) — the SDK polls for up to 120 seconds (VISIQ_HITL_TIMEOUT_MS), then fails closed.
• Mask proceeds, redacted. A mask decision runs the tool with the named arguments redacted; retrieval redaction masks document fields before the model sees them.

​

Verify it’s working

• Control Agents → Agents — your agent appears automatically (monitor mode) with a live last-seen heartbeat.
• Control Agents → Runtime Enforcement — a decision row for every governed tool call, with the matched rule and outcome.

​

Next steps