Quick Start

Put an AI agent under your organization’s policy with the Humanos Agent SDK: install it, run npx humanos init, and have every tool call checked before it runs.

This page takes a TypeScript or JavaScript agent to its first checked tool calls. The agent holds its own key, tells Humanos which tools it has, and asks Humanos before every call. Your organization’s policy decides each call: allowed calls run, refused calls never reach the tool.

To ask people to fill forms, sign documents or approve data over the REST API instead, see Human Approvals.

​

Before you start

1. Create an API key. In the Humanos Dashboard, click API Keys in the sidebar and create one. Copy the API Key and the Signature Secret; the secret is shown once. See Authentication.
2. Node.js 22 or later.

​

1. Install the SDK

In your agent’s project:

npm install @humanos-ai/agent-sdk

The VIA protocol SDK it builds on, @humanos-ai/via-sdk, comes with it.

​

2. Add your API key

.env

HUMANOS_API_KEY=<your-api-key>
HUMANOS_SIGNATURE_SECRET=<your-signature-secret>

​

3. Run npx humanos init

npx humanos init

init finds your framework in package.json and asks you to confirm it. Then it registers your agent, declares the tools of the MCP servers in .mcp.json when there is one, and sets up the checks: for Claude Agent SDK it writes the hooks into .claude/settings.json; for the other frameworks it prints the lines to add.

The key is the agent. init creates the agent’s key in .humanos/agent-key.json and adds .humanos/ to .gitignore. Keep the file and back it up: a new key is a new agent, and its mandates stay with the old one.

npx humanos status shows the agent and each tool’s access. npx humanos restore undoes every file change init made; the key stays.

​

4. Add the lines for your framework

Framework	What you add
Claude Agent SDK	Nothing: init wrote the hooks.
Vercel AI SDK, OpenRouter, Cloudflare Agents	humanos.guard(tools, "Support desk") around your tools.
LangChain and LangGraph	humanos.gate() as middleware, or humanos.guard(tools, "Support desk").
Any other framework	guard.call around each tool.

The lines for each framework are on the Agent SDK page. With Vercel AI SDK, for example:

import { aiSdk } from "@humanos-ai/agent-sdk/ai-sdk";

const humanos = await aiSdk();

await generateText({ model, tools: humanos.guard(tools, "Support desk"), prompt });

This page follows an agent with no framework, which runs its own tools. It declares two tools and calls each through the guard:

import { via, ViaDeniedError } from "@humanos-ai/agent-sdk";

const humanos = await via();

await humanos.tools.add([
  {
    service: "Support desk",
    name: "lookup_order",
    description: "Read an order by id.",
    inputSchema: { type: "object", properties: { order_id: { type: "string" } }, required: ["order_id"] },
    annotations: { readOnlyHint: true },
  },
  {
    service: "Support desk",
    name: "issue_refund",
    description: "Refund an order, in euros.",
    inputSchema: {
      type: "object",
      properties: { order_id: { type: "string" }, amount_eur: { type: "number" } },
      required: ["order_id", "amount_eur"],
    },
    annotations: { destructiveHint: true },
  },
]);

const lookupOrder = async (args: Record<string, unknown>) => ({ id: args.order_id, total_eur: 40 });
const issueRefund = async (args: Record<string, unknown>) => ({ refunded: args.amount_eur });

const order = await humanos.guard.call("lookup_order", { order_id: "A-1" }, lookupOrder);
console.log(order.result); // { id: "A-1", total_eur: 40 }

try {
  const refund = await humanos.guard.call("issue_refund", { order_id: "A-1", amount_eur: 40 }, issueRefund);
  console.log(refund.result);
} catch (e) {
  if (e instanceof ViaDeniedError) console.log(`blocked: ${e.reason}`); // the tool never ran
  else throw e;
}

Run it once. Both calls run: until the policy is set, every call is allowed, and recorded. The declared tools now appear under the agent in the dashboard.

​

5. Set the policy

The policy is what enforces the agent’s calls. In the dashboard, open Policy, under Agents in the sidebar, and choose an access for each tool:

Tool access	The call
Allow	Runs.
Restrict	Runs within the rules of the control you choose for it, and is refused over them.
Delegate	Runs only under a mandate a person grants.
Deny	Never runs.

For this page, set lookup_order to Allow and issue_refund to Deny. Then publish the policy: nothing changes for your agents until you do, and the dashboard asks you to confirm with your passkey or a code sent to your email. Only a manager or an owner can publish.

To refuse every tool you have not set, change the policy’s default to deny.

​

6. See a call refused

Run the agent again. lookup_order runs; issue_refund is refused and never runs:

{ id: "A-1", total_eur: 40 }
blocked: policy_denied

Every call, the decision on it and the outcome of each one that ran are recorded on the agent’s signed audit trail, under Agents in the dashboard.

​

Next steps

• Agent SDK: the lines for each framework, the humanos command, and everything the SDK exports.
• Agent Governance: how each call is decided, controls, mandates a person grants, MCP servers you did not write, and agents that connect over MCP.