装甲IQ SDK (TypeScript)
建立加密意图验证的安全AI代理.
ArmorIQ SDK使开发者能够构建内置安全性和可审计性的AI代理. 只有一个API键 - 没有云的复杂性.
为什么是装甲部队?
- 简单 - 只有一个API键,没有云证明
- 安全 - 对每项行动进行加密核查
- 应审计 - 完整的行刑线索
- 快点 - 五分钟后开始
安装
npm install @armoriq/sdk
# or
yarn add @armoriq/sdk
快速启动
1. 获取您的 API 密钥
访问 (原始内容存档于2018-03-25) (英语). armariq.ai 生成您的 API 密钥.
2. 客户初始化
import { ArmorIQClient } from '@armoriq/sdk';
const client = new ArmorIQClient({
apiKey: 'ak_your_key_here',
userId: 'your-user-id',
agentId: 'your-agent-id',
});
3. 抓住你的计划
const plan = {
goal: 'Get weather forecast',
steps: [
{
action: 'get_weather',
tool: 'weather_api',
mcp: 'weather-mcp',
inputs: { city: 'Boston' },
},
],
};
const planCapture = client.capturePlan('gpt-4', "What's the weather in Boston?", plan);
4. 获得意向托肯
const token = await client.getIntentToken(planCapture);
5. 启动行动
const result = await client.invoke('weather-mcp', 'get_weather', token, {
city: 'Boston',
});
console.log(result);
环境变量
# Required
ARMORIQ_API_KEY=ak_your_key_here
USER_ID=your-user-id
AGENT_ID=your-agent-id
# Optional
ARMORIQ_ENV=production # or 'local' for local development
CONTEXT_ID=default
ARMORIQ_BACKEND_URL=https://api.armoriq.ai # read before BACKEND_ENDPOINT, by the CLI and the client
PROXY_ENDPOINT=https://proxy.armoriq.ai
IAP_ENDPOINT=https://iap.armoriq.ai
还没有, PROXY_ENDPOINT 财务报告和审定财务报表 IAP_ENDPOINT 跟随后端:一种生产,
中继或本地后端得到环境的代理和IAP. 任何其他
后端需要两个设置, 或者第一个使用失败的调用
缺少变量.
原生的 OpenTeleometry 可观察性
0.7.0版本每会话有一棵原生的OpenTeleometry横跨树. 它支持 完全有三个出口选择。 组织政策仍然支配着各种选择; 当可观察性被关闭或政策权威不存在时, SDK 不 出口遥测和代理执行仍在继续.
1. 装甲运兵车
ArmorIQ OTLP是默认的. 不需要端点配置 .
const session = client.startSession({ mode: 'sdk' });
2. 一般外部OTLP终点
通过选项或标准使用符合标准的 HTTP/ protobuf 端点 OpenTeleometry环境变量.
const client = new ArmorIQClient({
apiKey: 'ak_your_key_here',
observability: {
exporter: 'external',
endpoint: 'https://collector.example.com/v1/traces',
headers: { Authorization: 'Bearer token' },
},
});
OTEL_SERVICE_NAME=my-agent
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://observability.example.com/v1/traces
OTEL_EXPORTER_OTLP_TRACES_HEADERS=Authorization=Bearer%20token,x-tenant-id=my-tenant
你可以提供一个底端。 SDK 附件 /v1/traces 仅限
此基准窗体 :
OTEL_EXPORTER_OTLP_ENDPOINT=https://collector.example.com
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20token
追踪特定设置优先于一般设置:
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT > OTEL_EXPORTER_OTLP_ENDPOINT
OTEL_EXPORTER_OTLP_TRACES_HEADERS > OTEL_EXPORTER_OTLP_HEADERS
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL > OTEL_EXPORTER_OTLP_PROTOCOL
OTEL_EXPORTER_OTLP_TRACES_TIMEOUT > OTEL_EXPORTER_OTLP_TIMEOUT
3. 呼叫者拥有的追踪器供应商
当应用程序拥有提供者时, 通过您自己的 OpenTelemetry 跟踪器提供者 生命周期和出口商设置.
import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
const provider = new NodeTracerProvider();
const session = client.startSession({
observability: { exporter: 'provider', tracerProvider: provider },
});
仅 http/protobuf 支持SDK管理的外部出口商。 (原始内容存档于2018-03-26). GRPC,,
OTLP/JSON,压缩,HTTP代理配置,和mTLS配置是
未经该出口商支持.
在需要时将这些特性设置在 OpenTeleometry Collection 上. 这个
出口者失败打开:远程停用、反应不良或超时永远不会改变
代理请求的结果. content-type 由于
SDK总是发送 application/x-protobuf。 。 。 .
在第一次外部追踪之前,SDK最多等待1.4秒 组织政策权威。 此一次性约束可防止未经授权的数据 从到达第三方。 如果在约束范围内没有权力, 外部遥测在那个会话中仍然被禁用,代理机还在继续.
一个SDK运行时间有一个出口选择. 用于扇出到AmorIQ和外部 工具,使用 OpenTeleometry Collection 来引导允许的痕迹.
Langfuse 实例
Langfuse是一个与OTLP兼容的目的地. 配置其 OTLP 端点和 环境中的标准标题; 不添加 Langfuse 特定的运行时代码 给您的代理人 :
OTEL_SERVICE_NAME=my-agent
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://cloud.langfuse.com/api/public/otel/v1/traces
OTEL_EXPORTER_OTLP_TRACES_HEADERS=Authorization=Basic%20BASE64_PUBLIC_KEY_COLON_SECRET_KEY,x-langfuse-ingestion-version=4
对于另一个供应商,使用该供应商记录的OTLP跟踪终点和 头. SDK不推断出销售商的URL,证书,或私有字段.
外部输出什么
外部OTLP输出总是包括痕量分级,稳定跨度名称, 服务身份、支持GenAI模型和符号使用属性以及安全 资源属性。 API钥匙、政策有效载荷、私人ArmorIQ身份证以及 任意用户元数据永远不会导出到外部目标.
默认时不包含快速内容、输出和工具参数/结果.
只有在该组织的
政策租赁既允许获取内容,也允许获取外部内容
有效的捕获模式是 enhanced 或者说 debug - 其他组合
(包括目前不具有权威性的政策获取)
他们。 默认情况下, 不要依赖外部导出为无内容
组织运行这些赠款并启用抓取模式; 检查您
组织的可观察性政策,如果这保证了你的重要性.
支持的安全资源属性为:
OTEL_SERVICE_NAME=my-agent
OTEL_RESOURCE_ATTRIBUTES=service.namespace=education,deployment.environment.name=staging
不在资源属性中设置秘密或用户内容. 不支持的资源 属性、畸形属性和看起来像电话号码的值, SSN,或付款卡号码在导出前被忽略.
抓取模式和每次会议选择退出
捕捉模式是准确的 off, (中文(简体) ), metadata, (中文(简体) ), enhanced,以及 debug。 。 。 .
选择以 ARMORIQ_OTEL_CAPTURE_MODE 或者说
observability.captureMode;组织政策只能缩小.
串流聊天请求包括 stream_options: { include_usage: true } 以
默认( e)otel.streamUsage, (中文(简体) ), ARMORIQ_OTEL_STREAM_USAGE, 默认值)
使用方式是隐藏在呼叫者身上的只使用块。 设定
ARMORIQ_OTEL_STREAM_USAGE=0 (或 observability.streamUsage: false当a
网关拒绝 stream_options 或者生水流必须保持不动 一个
明确 stream_options 在请求中永远不变.
const noTelemetrySession = client.startSession({
observability: { enabled: false },
});
转写符号用途
托肯用法被存储在每个会话,模型,协调世界时的日期和协调世界时小时. 每个消息
以时间戳计算 通过会话的原生OTel桥
当你记录笔录使用时,模型符号就会变成 gen_ai.chat
在同一个跟踪.
await client.captureTranscriptTokens({
transcriptPath: '/tmp/transcript.jsonl',
product: 'armorclaude',
sessionId: session.sessionId,
otel: session.otelSession,
});
将克劳德代码会话 包括其子代理记录,
逐个小时总结一下,送一个过来 recordTokenUsage 每小时打电话.
usageDate (单位:千美元)YYYY-MM-DD和 usageHour 需要(0-23);无
有效对返回 { ok: false, reason } 并张贴什么.
import { summarizeSessionUsageByHour } from '@armoriq/sdk';
const seen = new Set<string>();
const { hours, repo } = summarizeSessionUsageByHour(mainTranscriptPath, { seen });
for (const { usageDate, usageHour, entries } of hours) {
await client.recordTokenUsage({
product: 'armorclaude',
sessionId,
usageDate,
usageHour,
entries,
repo,
});
}
每个员额都取代该会话的行,型号,日期,小时和设备. 份额
一个 seen 设定跨会话, 所以历史复制到一个要塞会话计数中
一次 一次吗.
0.7.0 断开更改
先前的管道选择器、JSON记录器和托运人API、记录器手柄,
计划和微量摘要出口,以及 defaultObservabilityConfig 被删除.
使用 session.otelSession 给土生土长。 参见0.7.0分折换附注
内 变动情况 用于完整的被移除的公共表面.
高级使用
代表团
import * as crypto from 'crypto';
// Generate delegate keypair
const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
const pubKeyHex = publicKey.export({ type: 'spki', format: 'der' }).toString('hex');
const delegation = await client.delegate(token, pubKeyHex, 1800);
console.log(`Delegated token: ${delegation.delegatedToken.tokenId}`);
自定义代理端点
const client = new ArmorIQClient({
apiKey: 'ak_your_key_here',
userId: 'user-123',
agentId: 'agent-456',
proxyEndpoints: {
'weather-mcp': 'https://weather-proxy.example.com',
'finance-mcp': 'https://finance-proxy.example.com',
},
});
处理错误
import {
InvalidTokenException,
MCPInvocationException,
PolicyBlockedException,
TokenExpiredException,
} from '@armoriq/sdk';
try {
const result = await client.invoke('weather-mcp', 'get_weather', token, { city: 'Boston' });
} catch (error) {
if (error instanceof TokenExpiredException) {
console.error('Token expired, please get a new one');
} else if (error instanceof PolicyBlockedException) {
// The backend refuses a step outside the anchored plan, or one a policy blocks.
console.error('Blocked:', error.reason);
} else if (error instanceof MCPInvocationException) {
console.error('MCP invocation failed:', error.message);
}
}
API 参考
ArmorIQClient
构造选项
interface SDKConfig {
apiKey: string; // Required: Your API key
userId: string; // Required: User identifier
agentId: string; // Required: Agent identifier
contextId?: string; // Optional: Context identifier (default: 'default')
useProduction?: boolean; // Optional: Use production endpoints (default: true)
iapEndpoint?: string; // Optional: Override IAP endpoint
proxyEndpoint?: string; // Optional: Override proxy endpoint
backendEndpoint?: string; // Optional: Override backend endpoint
proxyEndpoints?: Record<string, string>; // Optional: MCP-specific proxies
timeout?: number; // Optional: Request timeout in ms (default: 30000)
maxRetries?: number; // Optional: Max retry attempts (default: 3)
verifySsl?: boolean; // Optional: Verify SSL (default: true)
}
方法
capturePlan(llm, prompt, plan, metadata?)- 获取一个执行计划getIntentToken(planCapture, policy?, validitySeconds?)- 拿个签名的意向书invoke(mcp, action, intentToken, params?, userEmail?)- 启动MCP行动delegate(intentToken, delegatePublicKey, validitySeconds?, allowedActions?, targetAgent?, subtask?)- 另一名代理人的代表verifyToken(intentToken)- 在当地验证一个标志close()- 清理资源
文档
完整文件,访问 (原始内容存档于2017-09-26). docs.armoriq.ai
适用于原生框架适配器版本、生命周期钩、回调链和 已知界限,参见 框架相容性矩阵。 。 。 .
仅限 0.7.0 的放出序列,见 发布运行本。 。 。 .
链接
许可证
麻省理工学院执照 - 看 自由主义 详细文件.