┌────────────────────┐      ┌──────────────────────┐      ┌─────────────────┐
│   智能体 (Agent)   │──────│   Integration 配置    │──────│  外部系统       │
│                    │      │  - type: api/db/openapi│     │  - REST API     │
│  LangChain Tools   │      │  - authMode           │     │  - PostgreSQL   │
│  DynamicStructured │      │  - s2sKey             │     │  - OpenAPI Spec │
│  Tool              │      │  - config             │     │                 │
└────────────────────┘      └──────────────────────┘      └─────────────────┘

// API 集成配置
interface ApiIntegrationConfig {
  baseUrl: string;       // 如 "https://erp.example.com/api"
  apiKey?: string;       // authMode 为 apikey 时使用
  headers?: Record<string, string>; // 自定义请求头
}

curl -X POST https://agent.tos.run/api/integrations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ERP 系统",
    "type": "api",
    "authMode": "jwt",
    "config": {
      "baseUrl": "https://erp.example.com/api",
      "headers": {
        "X-S2S-Key": "sk-your-s2s-key"
      }
    },
    "s2sKey": "sk-your-s2s-key",
    "enabled": true
  }'

// 数据库集成配置
interface DatabaseIntegrationConfig {
  connectionUrl: string;    // PostgreSQL 连接串
  dbType: 'postgresql';     // 目前支持 PostgreSQL
  readOnly: boolean;        // 默认 true，限制只读查询
  tableMetadata?: Array<{   // introspect 后自动填充
    table: string;
    schema: string;
    columns: Array<{
      name: string;
      type: string;
      nullable: boolean;
      comment: string | null;
    }>;
  }>;
}

# 1. 创建数据库集成
curl -X POST https://agent.tos.run/api/integrations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "业务数据库",
    "type": "database",
    "authMode": "none",
    "config": {
      "connectionUrl": "postgres://user:pass@db.example.com:5432/mydb",
      "readOnly": true
    }
  }'

# 2. 自动 introspect 表结构
curl -X POST https://agent.tos.run/api/integrations/{id}/introspect \
  -H "Authorization: Bearer $TOKEN"

# 返回: { "tables": [{ "table": "orders", "schema": "public", "columns": [...] }] }

// OpenAPI 集成配置
interface OpenApiIntegrationConfig {
  specUrl?: string;                   // OpenAPI Spec 的 URL
  specContent?: Record<string, any>;  // 或直接提供 Spec JSON 内容
  baseUrl?: string;                   // 覆盖 Spec 中的 servers[0].url
}

# 1. 创建 OpenAPI 集成
curl -X POST https://agent.tos.run/api/integrations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM API",
    "type": "openapi",
    "authMode": "jwt",
    "config": {
      "specUrl": "https://crm.example.com/openapi.json",
      "baseUrl": "https://crm.example.com"
    },
    "s2sKey": "sk-crm-secret"
  }'

# 2. 导入并生成工具
curl -X POST https://agent.tos.run/api/integrations/{id}/import-openapi \
  -H "Authorization: Bearer $TOKEN"

# 返回: { "tools": [...], "count": 12 }

┌──────────────┐     ┌──────────────────┐     ┌─────────────────┐
│ 管理员       │     │ Tensor Agent     │     │  外部系统       │
│              │     │ 服务端           │     │                 │
│ 1. 创建      │────▶│ 2. 存储 s2sKey   │     │                 │
│    Integration│    │    (加密)        │     │                 │
│    + s2sKey   │    │                  │     │                 │
│              │     │ 3. 智能体调用工具 │────▶│ 4. 验证 JWT     │
│              │     │    签发 JWT      │     │    处理请求     │
│              │     │    Bearer token  │     │    返回结果     │
└──────────────┘     └──────────────────┘     └─────────────────┘

// http-executor 内部逻辑
// 1. 检测工具 endpoint.headers 中是否包含 X-S2S-Key
const s2sKeyHeader = endpoint.headers?.['X-S2S-Key'];

// 2. 如果有 S2S Key，签发 JWT
if (s2sKeyHeader && context.userId) {
  const jwt = issueJwt(s2sKeyHeader, {
    userId: context.userId,
    orgId: context.orgId,
    expiresIn: 3600,
  });
  // 3. 通过 {{auth.jwt}} 模板变量注入到请求头
  // Authorization: Bearer {{auth.jwt}}
}

import jwt from 'jsonwebtoken';

function verifyAgentJwt(token, s2sSecret) {
  const decoded = jwt.verify(token, s2sSecret, { algorithms: ['HS256'] });
  // decoded.sub — 发起对话的用户 ID
  // decoded.org — 组织 ID
  return decoded;
}

// 在路由中间件中使用
app.use('/api/agent/*', (req, res, next) => {
  const token = req.headers.authorization?.replace('Bearer ', '');
  try {
    req.agentUser = verifyAgentJwt(token, process.env.S2S_SECRET);
    next();
  } catch {
    res.status(401).json({ error: 'Invalid agent JWT' });
  }
});

// 工具配置定义
interface AgentToolConfig {
  id: string;
  name: string;
  description?: string;
  type: 'http' | 'builtin' | 'database';
  inputSchema?: Record<string, unknown>;  // JSON Schema 格式
  endpoint?: {
    url: string;
    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
    headers?: Record<string, string>;
    bodyTemplate?: string;
    responseMapping?: string;
    queryParams?: Record<string, string>;
  };
  integrationId?: string;  // 关联的 Integration
}

import { DynamicStructuredTool } from '@langchain/core/tools';
import { z } from 'zod';

// 1. JSON Schema → Zod Schema 转换
function zodSchemaFromJson(jsonSchema) {
  // 递归将 JSON Schema 转为 Zod 类型
  // 支持: string, number, integer, boolean, array, object, enum
}

// 2. 创建 LangChain 工具
function createLangChainTools(toolConfigs, executionContext) {
  return toolConfigs.map(config =>
    new DynamicStructuredTool({
      name: config.id ?? config.name,
      description: config.description,
      schema: zodSchemaFromJson(config.inputSchema),
      func: (input) => executeToolCall(config, input, executionContext),
    })
  );
}

Agent Runtime → tool-bridge → executeToolCall() → httpExecutor / dbExecutor → 目标服务

Agent Runtime → tool-bridge → httpExecutor → POST /api/s2s/... → 外部系统

// URL 模板
"url": "https://erp.example.com/api/orders/{{input.orderId}}"

// Body 模板
"bodyTemplate": "{\"name\":\"{{input.name}}\",\"amount\":\"{{input.amount}}\"}"

// Header 中使用 JWT
"headers": {
  "Authorization": "Bearer {{auth.jwt}}",
  "X-S2S-Key": "sk-your-secret"    // 触发 JWT 自动签发
}

// 查询参数
"queryParams": {
  "page": "{{input.page}}",
  "status": "{{input.status}}"
}

// 智能体生成 SQL → dbExecutor 执行
async function dbExecutor(config, input, context) {
  const connectionUrl = config.endpoint.url;
  const query = input.query;       // 智能体生成的 SQL
  const readOnly = config.endpoint.headers?.['X-Read-Only'] !== 'false';

  const result = await executeQuery(connectionUrl, query, readOnly);
  return JSON.stringify({
    columns: result.columns,
    rows: result.rows,           // 最多 500 行
    rowCount: result.rowCount,
  });
}

paths:
  /customers/{id}:
    get:
      operationId: getCustomer
      summary: 获取客户详情
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string

{
  "id": "getCustomer",
  "name": "getCustomer",
  "description": "获取客户详情",
  "type": "http",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": { "type": "string", "description": "id" }
    },
    "required": ["id"]
  },
  "endpoint": {
    "url": "https://crm.example.com/customers/{{input.id}}",
    "method": "GET"
  }
}

curl -X POST https://agent.tos.run/api/mcp-servers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "文件系统工具",
    "serverKey": "filesystem",
    "config": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"]
    },
    "enabled": true
  }'

组织级 MCP Servers → 部门级覆盖 → 智能体级覆盖

{
  "serverKey": "github",
  "config": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_TOKEN": "$credential{github-token}"
    }
  }
}

import { MultiServerMCPClient } from '@langchain/mcp-adapters';

const client = new MultiServerMCPClient({
  filesystem: { transport: 'stdio', command: 'npx', args: [...] },
  github: { transport: 'sse', url: 'https://mcp.example.com/sse' },
});

const tools = await client.getTools(); // StructuredToolInterface[]
// 超时限制: 10s

interface DataChangePayload {
  integration?: string;    // 集成来源标识
  resource: string;        // 资源类型，如 'orders', 'customers'
  action: 'create' | 'update' | 'delete';
  ids?: string[];          // 受影响的记录 ID
  timestamp: number;       // Unix 时间戳 (ms)
}

工具执行完成（数据变更）
  → iframe 发送 tensor-agent:data-change 消息
  → SDK 接收并验证 origin
  → 触发 onDataChange 回调
  → 宿主页面刷新数据

// postMessage 格式
{
  type: 'tensor-agent:data-change',
  payload: {
    resource: 'customer',
    action: 'create',
    ids: ['cust-123'],
    timestamp: 1713081600000
  }
}

// POST /api/integrations
{
  name: string;                              // 必填，集成名称
  description?: string;                      // 可选，描述
  type: 'api' | 'database' | 'openapi';     // 必填，集成类型
  authMode?: 'none' | 'apikey' | 'jwt';     // 默认 'none'
  config?: Record<string, unknown>;          // 类型相关配置
  s2sKey?: string;                           // S2S 密钥
  enabled?: boolean;                         // 默认 true
}

// PATCH /api/integrations/:id
{
  name?: string;
  description?: string | null;
  authMode?: 'none' | 'apikey' | 'jwt';
  config?: Record<string, unknown>;
  s2sKey?: string;                // 更新密钥（旧密钥自动作废）
  enabled?: boolean;
}

{
  "id": "a1b2c3d4-...",
  "orgId": "org-123",
  "name": "ERP 系统",
  "description": "企业资源管理系统集成",
  "type": "api",
  "authMode": "jwt",
  "config": { "baseUrl": "https://erp.example.com/api" },
  "s2sKeyPrefix": "sk-y****",
  "generatedTools": [],
  "enabled": true,
  "createdBy": "user-456",
  "createdAt": "2026-04-14T08:00:00.000Z",
  "updatedAt": "2026-04-14T08:00:00.000Z"
}