IDFOR.AI SDK Documentation
Open platform Download SDK

Overview

Control and supervise your agents easily with the IDFOR.AI SDK

Connect the SDK once and let IDFOR review prompts, tool calls, documents, outputs, token usage and spend before any agent action reaches a model or external system.

Access key to governed action

Control governed actions across every agent with one access key

Use one IDFOR key for the police agent and pass an agentId for each supervised agent. IDFOR applies the right policy before the action continues.

ALLOW DEGRADE DENY REQUIRE_HUMAN

What IDFOR controls

One protection layer for every agent action

Connect once, then use agentId to apply the right policy to each supervised agent, workflow or department.

Input Output Tools Documents Cost Evidence

Execution flow

  1. Your app or agent sends the action through the SDK.
  2. IDFOR checks policy, budget, content, tools and context.
  3. You receive a clear decision with evidence, reasons and safe payloads.
  4. Only approved actions continue to the model, tool or external system.

Guard every entry point

Prompt, tool, output and document control

Use the same SDK surface to block risky actions before they leave your perimeter.

Control spend early

Token & cost guard before the model call

Estimate cost, enforce budgets, request human approval or block oversized requests in advance.

Keep policy traceability

Versioned YAML, evidence and approvals

Publish full policy versions and keep a durable audit trail per agent and decision.

How it works

How IDFOR controls an action before it runs

IDFOR sits between your agents and the systems they use, so every sensitive action can be checked for policy, cost, context and approval before execution.

Client agent Your app or agent

Sends a prompt, tool call, document or model request with an agentId.

IDFOR SDK Guard entry point

Normalizes metadata, preserves scope and sends the action to IDFOR for review.

Police agent Policy and budget control

Checks restrictions, jurisdiction, tool permissions, context size, cost and approvals.

External system Model, API or tool

Only receives approved or degraded payloads, never blocked requests.

ALLOW

Execute immediately and keep evidence attached to the response.

DEGRADE

Shrink context, sanitize fields or limit the execution path before continuing.

REQUIRE_HUMAN

Queue approval when policy or cost requires a human decision.

DENY

Block the action before tokens, credentials or external APIs are consumed.

Evidence ID generated Policy reasons recorded Usage and cost tracked Approval queue linked when needed

Core concepts

The operating model

IDFOR stays model-agnostic: keep your current providers and orchestration layer while adding one control point for policy, spend and evidence.

Access key

The API key identifies the police-agent scope that owns global policies, budget limits and audit records.

Client agent

agentId identifies the supervised agent that actually handles support, legal, coding or RAG tasks.

Policy version

Rules are published as full YAML revisions with history. You do not patch a single row in place.

Evidence

Each evaluated action can emit an evidence_id with decision metadata and a stable audit trail.

Approvals

Escalations can be listed and resolved from the SDK when the correct answer is human approval, not silent blocking.

Degrade path

The safe path is not always binary. IDFOR can shrink context, sanitize fields or lower scope before continuing.

What comes back from a guard

  • decision and human-readable summary
  • reasons with the policy basis for the action
  • effective_message when the request is sanitized or degraded
  • token_usage and estimated cost when token control is enabled
  • evidence_id for downstream logging, approvals and audit review

Install

Install from your IDFOR distribution or from a package file

Install the SDK from your IDFOR package links or from an internal package file, then connect it to the agent actions you want to govern.

Remote package

Install from deployment
Install from deployment

Package file

Install from file
Install from file

Quickstart

Guard the first prompt before it reaches a model

The fastest adoption path is to place IDFOR in front of a single action. Start with guardInput or guard_input, inspect the decision, and then move to wrapped model calls.

Important: the API key identifies the police agent. The agentId points to the client agent whose policy must be applied on this request.
Node.js quickstart
Python quickstart

Wrap model calls

Guard both input and output in one model wrapper

Use guardModelCall or guard_model_call when you want the SDK to supervise the full interaction: input guard, provider call, output guard, evidence continuity and token accounting.

Execution chain

  1. Guard the input and normalize the safe prompt.
  2. Inject the returned evidenceId into your provider metadata.
  3. Return text and optional provider usage to the SDK.
  4. Receive final output with blocking, degradation or approval outcomes.

Use this when

  • You already call OpenAI, Anthropic, Gemini or another model directly.
  • You need one wrapper instead of separate input and output hooks.
  • You want evidence, token control and provider usage merged in the same path.
Node.js wrapped model call
Python wrapped model call

Tool and document guards

Control outbound actions and inspect files before context expansion

Client agents do not only talk to models. They call tools, send emails, write tickets and ingest files. The same police layer can evaluate those actions with dedicated methods.

Guard tools

  • Validate send_email, create_ticket or custom tool names.
  • Attach metadata such as department, customer, channel or escalation surface.
  • Block, degrade or escalate before the action touches another system.

Guard documents

  • Inspect PDFs before they enter prompt context.
  • Block confidential documents or risky identifiers early.
  • Keep a clean audit trail for file-intake decisions.
Node.js tool guard
Python tool guard
Node.js document guard
Python document guard

Token & cost guard

Decide before you pay the model bill

Token control is not a cosmetic metric layer. It is a preflight decision system that estimates size, cost and budget risk before the request is sent to a provider.

ALLOW

Safe to execute within token and spend thresholds.

WARNING / DEGRADE

Reduce scope, summarize context, switch model or limit the execution path.

DENY

Reject the request before it reaches the provider and consumes tokens.

REQUIRE_HUMAN

Escalate to approval when spend crosses a configured high-risk threshold.

What the token guard can evaluate

  • Estimated input tokens before the model call.
  • Projected spend by provider, model and attached context.
  • Budget caps per agent, department, workspace or environment.
  • Whether the same action should be degraded, confirmed or blocked entirely.
Node.js token guard
Python token guard

Programming cost guard

Detect high-cost coding prompts even when the prompt is short

A short request can still imply repository-wide reads, many file edits, test suites, migrations, CI or Docker changes. The programming cost guard scores that implied scope before an external coding agent burns context and budget.

Signals the guard can use

  • Multi-file change requests
  • Repository-wide context or file tree requests
  • Tests, Docker, CI and deployment instructions
  • Database migrations or large refactors

Typical outcomes

  • Request confirmation before calling the coding agent
  • Ask the operator to split the task into phases
  • Block the task until scope is narrowed
  • Keep evidence that the budget guard intervened
Node.js programming cost guard
Python programming cost guard

Policies and agents

Create client agents and publish policies from the SDK

Use the SDK to list client agents, create new ones and publish policy versions without leaving your integration workflow.

Policy lifecycle

To add or remove rules you publish a new full policy version with saveAgentPolicy or save_agent_policy. This preserves history and keeps the audit model clear.

Node.js agent operations
Python agent operations
Policy YAML example

Evidence and approvals

Keep audit continuity after the decision

The SDK can return the evidence trail for every evaluated decision and help you resolve escalations when an operation requires human review.

Evidence history

List recent decisions, then load a specific evidence item to inspect what happened and why.

Approval queue

List pending approvals, resolve them and keep the final operator action attached to the record.

Node.js evidence history
Python evidence history
Node.js approvals
Python approvals

Integrations

Connect IDFOR to the AI stack you already run

The SDK sits in front of existing providers and agent workflows. Use the same policy layer to govern prompts, tools, documents, output and spend across OpenAI, Claude, Gemini and custom flows.

How to read this section

“Cost & Guard active” means the current SDK already supports preventive checks for that surface. “Planned” means the connection model is designed, but the packaged provider bridge is not yet exposed in this release.

Reference

SDK surface

The JavaScript and Python clients expose the same conceptual capabilities with idiomatic method names.

Capability Node.js Python Purpose
Health health() health() Check connectivity with the main IDFOR platform.
SDK catalog sdkCatalog() sdk_catalog() Return package download URLs and installation commands.
Prompt guard guardInput() guard_input() Evaluate input before a provider or orchestrator is called.
Output guard guardOutput(), filterOutput() guard_output(), filter_output() Filter a model response before returning it.
Tool guard guardToolCall() guard_tool_call() Validate outbound tool executions.
Model wrapper guardModelCall() guard_model_call() Guard input and output inside one wrapped provider call.
Document guard guardDocument() guard_document() Inspect files before context ingestion.
List agents listAgents() list_agents() List client agents accessible from the police agent scope.
Create agent createAgent() create_agent() Create a new client agent under the workspace.
Publish policy saveAgentPolicy() save_agent_policy() Publish a new full YAML version for an agent.
Evidence listEvidence(), getEvidence() list_evidence(), get_evidence() Browse recent decisions and inspect specific evidence records.
Approvals listApprovals(), resolveApproval() list_approvals(), resolve_approval() Operate a human-in-the-loop review queue.

Rollout checklist

Practical order of operations

Teams usually adopt the SDK incrementally. Start with one path, validate the evidence and then expand coverage to the rest of your agents.

  1. Install the SDK from the hosted package or from a package file.
  2. Authenticate the police agent with an API key.
  3. Set a real client agent agentId for every guarded action.
  4. Start by guarding input on the highest-risk workflow.
  5. Turn on token and budget thresholds before large-context usage grows.
  6. Wrap model calls or add explicit output filtering once the input path is stable.
  7. Guard tool executions and document intake next.
  8. Publish policy versions through the SDK to preserve history.
  9. Connect evidence review and approval handling to your ops workflow.

Downloads

Package links and platform entry points

This documentation links directly to the hosted SDK artifacts and to the main application entry point. Use these URLs in onboarding guides, internal portals or deployment runbooks.