Strands Agents Quickstart

​

Install

pip install "visiq>=0.5.0" "strands-agents[openai]"

​

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 agent

from strands import Agent, tool
from strands.models.openai import OpenAIModel

from visiq import govern  # pip install visiq


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


@tool
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"}},
    ]


agent = Agent(
    model=OpenAIModel(model_id="gpt-4o-mini"),
    system_prompt="You are a helpful assistant.",
    tools=[issue_refund, search_knowledge],
)

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

print(agent("What was Q3 revenue?"))

from visiq.strands import VisiqGovernanceHooks

agent = Agent(
    model=OpenAIModel(model_id="gpt-4o-mini"),
    tools=[issue_refund, search_knowledge],
    hooks=[VisiqGovernanceHooks(agent_id="support-bot",
                                retrieval_tools={"search_knowledge"})],
)

​

Run this on AWS Bedrock

from strands import Agent
from strands.models import BedrockModel

from visiq import govern  # pip install visiq

agent = Agent(
    model=BedrockModel(model_id="amazon.nova-micro-v1:0", region_name="us-east-1"),
    tools=[issue_refund, search_knowledge],
)
govern(agent, agent_id="support-bot", retrieval_tools={"search_knowledge"})

​

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