SDK Quickstart: Wrap Your Agent in Minutes

Connecting your agent to Nomotic governance takes about two minutes. This guide walks you through the fastest path from a registered agent to a live governance evaluation using the managed-agents package.

Before you start

You will need:

• A Nomotic account (free at amp.nomotic.ai)
• Your API key from Settings → API Keys (use the Agentic scope)
• Your agent ID from Identity → Certificates (starts with nmc-)

Step 1 — Install

pip install "managed-agents>=2.0.0"

Step 2 — Create a harness

python

from managed_agents import NomoticHarness, GovernanceDenied

harness = NomoticHarness(
    api_key="nm_live_...",    # from amp.nomotic.ai/settings
    agent_id="nmc-...",       # from amp.nomotic.ai/identity
    platform="custom",        # tags evaluations in your audit trail
)

Step 3 — Govern your tool calls

Wrap every tool call with harness.govern() before it executes. If governance allows the action, execution proceeds. If it denies, GovernanceDenied is raised and the tool never runs.

python

async def execute_tool(tool_name: str, tool_input: dict) -> str:
    await harness.govern(tool_name, tool_input)
    return await your_runtime.execute(tool_name, tool_input)

try:
    await execute_tool("send_email", {"to": "customer@example.com"})
except GovernanceDenied as e:
    print(f"Blocked by governance: {e}")

How it works

Agent decides tool call
  → harness.govern() → POST /api/v1/govern
      ALLOW    → tool executes
      DENY     → GovernanceDenied raised (tool never executes)
      ESCALATE → routed to human review queue

Every evaluation is sealed in your audit trail automatically. Nothing else is required.

Step 4 — Verify it worked

After running your agent, go to Governance → Audit Trail in the platform. Your first evaluation should appear within a few seconds showing the action, verdict, UCS score, and full dimension breakdown.

Step 5 — Add prescreening (recommended)

For agents with access to shell commands, file systems, or email, add a prescreener. This blocks dangerous patterns in under 1 millisecond before any network call is made — no additional latency on safe operations.

python

from managed_agents import NomoticHarness, StandardPrescreener, GovernanceDenied

harness = NomoticHarness(
    api_key="nm_live_...",
    agent_id="nmc-...",
    platform="custom",
    prescreener=StandardPrescreener(
        block_destructive_shell=True,    # rm -rf, DROP TABLE, mkfs, fork bombs
        block_bulk_operations=True,      # >10 emails, >20 files, >5 calendar items
        escalate_credential_access=True, # .ssh/, .env, /etc/passwd, API keys
    ),
)

Step 6 — Apply a policy preset (optional)

Policy presets calibrate governance thresholds for your agent’s tool category. Without a preset, default thresholds apply. With one, dimension weights and veto rules are tuned for the specific risk profile of that tool type.

python

from managed_agents import NomoticHarness, ToolPolicy

harness = NomoticHarness(
    api_key="nm_live_...",
    agent_id="nmc-...",
    policy=ToolPolicy.EMAIL,       # trust_threshold=0.70, veto: data_sensitivity
    # policy=ToolPolicy.SHELL      # trust_threshold=0.85, veto: scope+ethics
    # policy=ToolPolicy.FILESYSTEM # trust_threshold=0.75, veto: reversibility
    # policy=ToolPolicy.BROWSER    # trust_threshold=0.75, veto: auth+sensitivity
    # policy=ToolPolicy.CALENDAR   # trust_threshold=0.60, no vetoes
    # policy=ToolPolicy.DEFAULT    # trust_threshold=0.65, no vetoes
)

Try it without an API key

You can run managed-agents before you have a Nomotic account. In pass-through mode, prescreening still blocks dangerous patterns and verdicts are logged locally to ~/.nomotic/managed-agents.log. Full governance evaluation requires an API key.

python

harness = NomoticHarness(
    agent_id="dev-agent",   # no api_key — pass-through mode
    prescreener=StandardPrescreener(),
    suppress_nudge=False,   # nudge suggests amp.nomotic.ai after 10 evals
)

Configuration options

Parameter	Default	Description
api_key	None	Nomotic API key. None enables pass-through mode
agent_id	required	Your agent’s Nomotic ID (nmc-…)
platform	"custom"	Framework tag for audit trail filtering
fail_open	True	Allow on governance service error
block_on_escalate	False	Raise GovernanceEscalated on ESCALATE
timeout	3.0	HTTP timeout in seconds
prescreener	None	StandardPrescreener or custom Prescreener subclass
policy	None	ToolPolicy preset for calibrated thresholds
tool_name_map	None	Override tool name → action verb mapping
circuit_breaker	None	CircuitBreaker for API resilience
local_log	True	Log verdicts to ~/.nomotic/managed-agents.log
suppress_nudge	False	Suppress amp.nomotic.ai registration nudge
on_verdict	None	Callback for every verdict
on_escalate	None	Callback for ESCALATE verdicts
on_deny	None	Callback for DENY verdicts

Sync usage

If your framework is not async, use govern_sync():

python

result = harness.govern_sync("bash", {"command": "ls -la"})

Next steps

See the full integration guides for LangChain, CrewAI, AutoGen, Claude, and OpenAI

Set your agent’s archetype in Identity to calibrate governance for its role

Add context profiles in Context to inject your organization’s guidelines

Configure policies in Governance to adjust thresholds for your use case