Protect an action with the SDK
Use the client SDK to protect a business action before execution.
5 min readBefore you begin
- A registered agent, approved tool connection, published policy, workload credentials and supported Node.js version.
Prepare your integration
Use Node.js 22.22 or later and the SDK version supplied for your account. The npm install command applies after that version is published.
Configure the client
Supply the AgentGuard protection URL and a token provider from your server-side secret manager. The token provider must return only the token string.

Protect one intent
Build the registered action shape. Persist its original arguments and a stable intent ID with your business job before calling protect.
Handle the returned type
DENY or APPROVAL_REQUIRED returns a decision without execution. Successful execution returns executionState and targetStatus. Handle errors and unknown outcomes without automatic side-effect retries.
Code example
Save one intent ID per business operation. Inspect whether protect() returned a decision or an execution result.
import { AgentGuard, AgentGuardError } from '@oxigen/agentguard-sdk';
function required(name) {
const value = process.env[name];
if (!value) throw new Error(`Missing ${name}`);
return value;
}
const guard = new AgentGuard({
baseUrl: required('AGENTGUARD_URL'),
token: async () => required('AGENTGUARD_WORKLOAD_TOKEN')
});
const action = {
schemaVersion: '2026-11', tool: 'ledger.payments',
operation: 'create', resource: 'payments',
arguments: { amount: 12500, currency: 'CAD' }
};
// A stable ID from your persisted business job, not a new ID on each retry.
const intentId = required('ACTION_INTENT_ID');
try {
const result = await guard.protect(action, intentId);
if ('effect' in result) {
console.log({ decisionId: result.decisionId, effect: result.effect });
// Keep denied jobs stopped and approval-required jobs pending.
} else {
console.log({ decisionId: result.decisionId,
executionState: result.executionState, targetStatus: result.targetStatus });
}
} catch (error) {
if (error instanceof AgentGuardError) {
console.error({ code: error.problem.code,
executionState: error.execution?.executionState });
} else throw error;
// Never invoke the protected tool directly as a fallback.
}Expected result
{"decisionId":"example-decision","executionState":"succeeded","targetStatus":200}Check your setup
- Client credentials stay out of browser code and logs.
- A stable intent ID is saved; every decision and execution result is handled.
