Connect your first agent

This guide routes your agent's tool calls through Nexus so every invocation passes AgentIAM verification, MCP Gateway inspection, and NPL policy evaluation.

Time to first gated call: under 3 minutes with a sandbox API key.

Prerequisites

API key from developers.hardalion.com (format hdl_live_…)
Node.js 22+
An existing agent with tool definitions (LangChain, CrewAI, or plain functions)

Step 1: Install the SDK

npm install @hardalion/sdk

The SDK wraps your agent's tool surface and evaluates NPL policies before each invoke, call, run, or execute.

Step 2: Issue an AgentIAM credential

curl -X POST "https://api.hardalion.com/api/v1/agentiam/credentials/issue" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_prod_f8a92b",
    "ttl_seconds": 86400
  }'

Requires scope agents:manage. Store the returned credential securely. It binds the agent identity to your tenant.

Step 3: Wrap your tools

import { NexusGateway } from '@hardalion/sdk'
import { myEnterpriseTools } from './tools'

const securedAgent = NexusGateway.wrap(
  { invoke: myEnterpriseTools.invoke.bind(myEnterpriseTools) },
  {
    tenantId: 'ten_your_workspace',
    agentId: 'agt_prod_f8a92b',
    apiKey: process.env.HARDALION_API_KEY,
    baseUrl: 'https://api.hardalion.com',
    policy: 'hardalion://nato-prou-strict-financial@1.0.0',
  },
)

// Pass securedAgent to LangChain, CrewAI, or your orchestrator.

Policy URIs resolve from the open npl-spec registry. View source policies: Reference policies.

Step 4: Verify a blocked call

Trigger a policy violation to confirm the gate is active:

npx @hardalion/npl-policy-engine --tool drop_table --policy nato-prou-strict-financial

Expected: BLOCK with stable rule ID and reason code. On Nexus, the same decision is audited before your agent receives the error.

Alternative: MCP Gateway inspect

For raw JSON-RPC payloads (MCP-native clients), call the inspect endpoint directly:

curl -X POST "https://api.hardalion.com/api/v1/mcp/gateway/inspect" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_prod_f8a92b",
    "server_id": "enterprise-db",
    "tool_name": "drop_table",
    "request": {
      "jsonrpc": "2.0",
      "id": 1,
      "method": "tools/call",
      "params": { "name": "drop_table", "arguments": {} }
    }
  }'

Requires scope agents:execute.

Step 5: Run in shadow mode (recommended)

Before enforcing blocks on production traffic, enable Shadow mode. Nexus logs counterfactual BLOCK decisions while allowing execution to proceed.

curl -X PATCH "https://api.hardalion.com/api/v1/execution-mode" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"execution_mode":"shadow","fail_closed":true}'

Sandbox path

No API key yet? Create a workspace at sandbox.nexus.hardalion.com in under 3 minutes. See Sandbox.

Next steps

Topic	Link
MCP Gateway internals	MCP Gateway
Agent identity	AgentIAM
Local policy testing	NPL Quickstart
API reference	Agents API