Integration Guide

@kobil:registry=https://gitlab.kobil.com/api/v4/groups/3778/-/packages/npm/
//gitlab.kobil.com/api/v4/groups/3778/-/packages/npm/:_authToken=${KOBIL_REGISTRY_TOKEN}

[global]
extra-index-url = https://${KOBIL_REGISTRY_USER}:${KOBIL_REGISTRY_TOKEN}@gitlab.kobil.com/api/v4/groups/3778/-/packages/pypi/simple

npm install @kobil/aitrust @kobil/kobil-agent-sdk @kobil/kobil-agent-audit --legacy-peer-deps

pip install kobil-aitrust kobil-agent-sdk kobil-agent-audit

"dependencies": {
  "@anthropic-ai/sdk": "^0.40.0",
  "pdf-lib": "^1.17.1"
}

"dependencies": {
  "@anthropic-ai/sdk": "^0.40.0",
  "pdf-lib": "^1.17.1",
  "@kobil/aitrust":           "0.2.20-rc.4",
  "@kobil/kobil-agent-sdk":   "0.2.20-rc.4",
  "@kobil/kobil-agent-audit": "0.2.20-rc.4"
}

dependencies = [
  "anthropic>=0.40.0",
  "reportlab>=4.2.0", "pypdf>=5.1.0",
]

dependencies = [
  "anthropic>=0.40.0",
  "reportlab>=4.2.0", "pypdf>=5.1.0",
  "kobil-aitrust", "kobil-agent-sdk", "kobil-agent-audit",
]

// No SDK — the agent has no platform identity.
// The Anthropic client is the only thing constructed.
const anthropic = new Anthropic();

import { AITrust } from "@kobil/aitrust";
import type { AITrustInstance } from "@kobil/aitrust";

let _sdk: AITrustInstance | null = null;
export async function getAgentSDK(): Promise<AITrustInstance> {
  if (_sdk) return _sdk;
  _sdk = AITrust({
    agentId: `agent:${process.env.AITRUST_CLIENT_ID}`,   // your client id — no fallback
    timeoutMs: 120_000,
    platformUrl:   process.env.AITRUST_MANAGEMENT_URL,
    managementUrl: process.env.AITRUST_MANAGEMENT_URL,
    auditUrl:      process.env.AITRUST_AUDIT_URL,
    idpUrl:        process.env.AITRUST_IDP_URL,
    clientId:      process.env.AITRUST_CLIENT_ID,
    clientSecret:  process.env.AITRUST_CLIENT_SECRET,
    realm:         process.env.AITRUST_REALM,
    // mutual TLS: a separate host, and the cert pair kobilctl mounts at /certs
    proxyUrl:      process.env.AITRUST_PROXY_URL,
    proxyCertPath: process.env.AITRUST_PROXY_CERT_PATH,
    proxyKeyPath:  process.env.AITRUST_PROXY_KEY_PATH,
  });
  return _sdk;
}

# No SDK — the agent has no platform identity.
anthropic = AsyncAnthropic()

from kobil_aitrust import AITrust, AITrustConfig, AITrustInstance

_sdk: AITrustInstance | None = None
async def get_agent_sdk() -> AITrustInstance:
    global _sdk
    if _sdk is not None:
        return _sdk
    client_id = os.environ["AITRUST_CLIENT_ID"]   # your client id — no fallback
    _sdk = AITrust(AITrustConfig(
        agent_id=f"agent:{client_id}",
        guard_policy="standard",
        timeout_ms=120_000,
        platform_url=os.environ.get("AITRUST_MANAGEMENT_URL"),
        management_url=os.environ.get("AITRUST_MANAGEMENT_URL"),
        audit_url=os.environ.get("AITRUST_AUDIT_URL"),
        idp_url=os.environ.get("AITRUST_IDP_URL"),
        client_id=client_id,
        client_secret=os.environ.get("AITRUST_CLIENT_SECRET"),
        realm=os.environ["AITRUST_REALM"],
    ))
    return _sdk

import { defineTool } from "./tools-runtime.js";
import type { ToolDefinition, ToolInput } from "./tools-runtime.js";

import { defineTool } from "@kobil/aitrust";
import type { ToolDefinition, ToolInput } from "@kobil/aitrust";

from .tools_runtime import ToolDefinition, ToolInput, define_tool

from typing import Any
from kobil_aitrust import ToolDefinition, define_tool

ToolInput = dict[str, Any]   # convenience alias; the Python package exports the TS
                             # equivalent of ToolInput as a plain dict

import { toAnthropicTools } from "./tools-runtime.js";

const tools = createInsuranceTools({ /* ctx */ });
const anthropicTools = toAnthropicTools(tools);
// ...
const resultText = await tools[name].execute(input);   // runs directly — no checks

import { registerTools, toAnthropicTools } from "@kobil/aitrust";

const ai = await getAgentSDK();
const defs = createInsuranceTools({ /* ctx */ });   // the same 5-field ctx the starter
                                                   // already builds at agent.ts:270 —
                                                   // claimsCtx, getAnthropic, visionModel,
                                                   // getFile, saveFile. Don't paste the
                                                   // comment literally; reuse that object.
const securedTools = registerTools(ai, defs);          // wraps each tool
const anthropicTools = toAnthropicTools(securedTools) as unknown as Anthropic.Tool[];
// The double cast bridges the SDK's loose return type to Anthropic's stricter Tool[].
// It is safe here (shapes match) but it does switch off type-checking on tool schemas —
// so a typo in a parameter name will surface at runtime, not at compile time.
// ...
const resultText = await securedTools[name].execute(input);  // full pipeline

from .tools_runtime import to_anthropic_tools

defs = create_insurance_tools(ctx)
anthropic_tools = to_anthropic_tools(defs)
# ...
result_text = await defs[name].execute(tool_input)     # runs directly — no checks

from kobil_aitrust import register_tools, to_anthropic_tools

ai = await get_agent_sdk()
defs = create_insurance_tools(ctx)
secured = register_tools(ai, defs)                     # wraps each tool
anthropic_tools = to_anthropic_tools(secured)
# ...
result_text = await secured[name].execute(tool_input) # full pipeline

generate_settlement_document: defineTool({
  name: "generate_settlement_document",
  parameters: { /* ... */ },
  execute: async (input) => { /* ... */ },
}),

generate_settlement_document: defineTool({
  name: "generate_settlement_document",
  scopes: ["insurance:write"],            // metadata: seeds FGA tuples + token scope
  parameters: { /* ... */ },
  execute: async (input) => { /* ... */ },
}),

"generate_settlement_document": define_tool(ToolDefinition(
    name="generate_settlement_document",
    parameters={...},
    execute=_generate_settlement_document,
)),

"generate_settlement_document": define_tool(ToolDefinition(
    name="generate_settlement_document",
    scopes=["insurance:write"],           # metadata: seeds FGA tuples + token scope
    parameters={...},
    execute=_generate_settlement_document,
)),

// delete_claim was blocked with a hard-coded throw in code:
execute: async () => { throw new Error("Deleting claims is blocked by policy"); }

import { NotAuthorized } from "@kobil/aitrust";
try {
  const resultText = await securedTools[name].execute(input);
} catch (e) {
  if (e instanceof NotAuthorized) {
    // DENIED centrally by FGA — no scope. Tell the model + audit captured it.
  } else throw e;
}

# delete_claim was blocked with a hard-coded raise in code:
async def _delete_claim(_inp): raise RuntimeError("Deleting claims is blocked by policy")

from kobil_aitrust import NotAuthorized
try:
    result_text = await secured[name].execute(tool_input)
except NotAuthorized:
    ...  # DENIED centrally by FGA — no scope

request_signature: defineTool({
  name: "request_signature",
  scopes: ["claims:sign"],
  execute: async (input) => { /* send for signing */ },
}),

request_signature: defineTool({
  name: "request_signature",
  scopes: ["claims:sign"],
  needsApproval: true,                                       // ← gate on a human
  approver: resolveApproverForPolicyholder,                 // string | (input) => string
  approvalMessage: (input) => buildCibaBindingMessage("request_signature", input),
  execute: async (input) => { /* send for signing */ },
}),

"request_signature": define_tool(ToolDefinition(
    name="request_signature",
    scopes=["claims:sign"],
    execute=_request_signature,
)),

"request_signature": define_tool(ToolDefinition(
    name="request_signature",
    scopes=["claims:sign"],
    needs_approval=True,                                     # ← gate on a human
    approver=resolve_approver_for_policyholder,             # str | (input) -> str
    approval_message=lambda inp: _build_ciba_binding_message("request_signature", inp),
    execute=_request_signature,
)),

// Nothing — there was no approval step.

import { ApprovalDenied, ApprovalTimeout } from "@kobil/aitrust";
// catch ApprovalDenied (approver said no) and ApprovalTimeout (nobody answered)

# Nothing — there was no approval step.

from kobil_aitrust import ApprovalDenied, ApprovalTimeout
# except ApprovalDenied / ApprovalTimeout

// No audit trail — events were only console.log'd locally.
console.log("[SIGNED]", instanceId);

await ai.audit.logEvent({
  action: "document_sign",                // required (top-level)
  eventType: "claims.document_signed",    // required (top-level)
  outcome: "success", resourceId: instanceId, details: {},
});  // agentId is filled from the SDK config

# No audit trail — events were only printed locally.
print("[SIGNED]", instance_id)

await ai.audit.log_event({
    "action": "document_sign",              # required (top-level)
    "eventType": "claims.document_signed",  # required (top-level)
    "outcome": "success", "resourceId": instance_id, "details": {}})
# agentId is filled from the SDK config

OIDC_CLIENT_ID=<your-web-login-client>
OIDC_AUTHORIZE_URL=https://<shift-idp-host>/auth/realms/agenttrust/protocol/openid-connect/auth
OIDC_TOKEN_URL=https://<shift-idp-host>/auth/realms/agenttrust/protocol/openid-connect/token
OIDC_REDIRECT_URI=https://<your-host>/auth/callback
KOBIL_SESSION_SECRET=<long random string — must be stable across restarts>

// Who is this? Nobody knows — every request is the same hardcoded user.
const userId = "claims-adjuster";

import { createKobilIdentity } from "@kobil/kobil-agent-sdk/web";

// null when OIDC_CLIENT_ID is unset — local runs keep working untouched.
const identity = process.env.OIDC_CLIENT_ID ? createKobilIdentity() : null;

// in the request handler:
if (identity && await identity.handle(req, res)) return;  // owns /auth/login + /auth/callback
const user = identity ? await identity.getUser(req) : null;   // { sub, email } | null
const userId = user?.email ?? "claims-adjuster";              // the policyholder

# Who is this? Nobody knows — every request is the same hardcoded user.
user_id = "claims-adjuster"

from kobil_agent_sdk.web import create_kobil_identity

# None when OIDC_CLIENT_ID is unset — local runs keep working untouched.
identity = create_kobil_identity() if os.environ.get("OIDC_CLIENT_ID") else None

# identity owns /auth/login + /auth/callback (see the module docstring for
# the FastAPI wiring); then per request:
user = await identity.get_user(request) if identity else None
user_id = user.email if user else "claims-adjuster"

GET {AITRUST_MGMT_URL}/agents/{AITRUST_CLIENT_ID}/route-approver?policyholder_email={userId}
# → { "approver_email": "..." }   Pass it as the CIBA login hint.