if (env.AGENT_ENGINE === 'pi') {
  return dispatchPiAgent(props);
}
// default 引擎：Plan + Step 编排

AGENT_ENGINE: z.enum(['default', 'pi']).default('default')

skill = (
  systemPrompt 中注入 skill 元数据  // <agent_skills><skill><name/></skill></agent_skills>
  + 6 个 sandbox tool 暴露给 LLM   // sandbox_read_file 等
  + sandbox 容器中放置 SKILL.md    // 容器内 /workspace/<skill>/SKILL.md
)

Tool/LLM 调用产生 ChatNodeUsageType{ inputTokens, outputTokens, totalPoints, moduleName, model }
   ↓
usagePush(usages: ChatNodeUsageType[])  // dispatchProps 透传下来的回调
   ↓
工作流上层结算

result.state.usage = {
  requests: number,
  inputTokens, outputTokens, totalTokens,
  inputTokensDetails: { cached_tokens?: number, ... },
  outputTokensDetails: { reasoning_tokens?: number, ... },
  requestUsageEntries: RequestUsage[]  // ← 每次 LLM 调用一条
}

type RequestUsage = {
  inputTokens, outputTokens, totalTokens,
  inputTokensDetails, outputTokensDetails,
  endpoint: 'responses.create' | 'responses.compact' | 'chat.completions' | ...
}

result.rawResponses: ModelResponse[]
// 每个 ModelResponse 自带 usage、responseId、requestId、providerData

import { Agent, Runner, OpenAIProvider, setOpenAIAPI } from '@openai/agents';
import OpenAI from 'openai';

setOpenAIAPI('chat_completions');  // 第三方兼容 endpoint 必须切这条路径

function makeRunner(cfg: { baseURL: string; apiKey: string; headers?: Record<string,string> }) {
  const client = new OpenAI({ apiKey: cfg.apiKey, baseURL: cfg.baseURL, defaultHeaders: cfg.headers });
  return new Runner({ modelProvider: new OpenAIProvider({ openAIClient: client }) });
}

import { tool } from '@openai/agents';
const myTool = tool({
  name: 'foo',
  description: 'do foo',
  parameters: { type: 'object', properties: {...}, additionalProperties: false },  // JSON Schema
  strict: false,                                                                    // 必须，因为现有 schema 不一定满足 OpenAI strict 规范
  async execute(input, runContext, details) {
    details?.signal?.throwIfAborted();
    return await fastgptDispatchTool({ callId: details!.toolCall.callId, toolId: 'foo', args: JSON.stringify(input) });
  },
  errorFunction: (ctx, err) => `tool error: ${err.message}`,
  timeoutMs: 60_000
});

const ctrl = new AbortController();
checkIsStopping 轮询 → ctrl.abort()
const result = await run(agent, input, { signal: ctrl.signal, maxTurns: 100 });

// 跨轮恢复
const snapshot = result.state.toString();   // 整个状态序列化为 JSON 字符串，存到 memories
const state = await RunState.fromString(agent, snapshot);
const resumed = await run(agent, state);

SDK: result.state.usage.requestUsageEntries[]
   ↓ 每条 RequestUsage → ChatNodeUsageType
FastGPT: usagePush([{ inputTokens, outputTokens, totalPoints, moduleName, model }])

// run 结束后
const entries = result.state.usage.requestUsageEntries ?? [];
const usages: ChatNodeUsageType[] = entries.map(e => {
  const totalPoints = userKey ? 0 : formatModelChars2Points({
    model: modelData,
    inputTokens: e.inputTokens,
    outputTokens: e.outputTokens
  }).totalPoints;
  return {
    moduleName: i18nT('account_usage:agent_call'),
    model: modelData.name,
    inputTokens: e.inputTokens,
    outputTokens: e.outputTokens,
    totalPoints
  };
});
usagePush(usages);

import { tool as oaiTool } from '@openai/agents';

function buildOpenAITools(ctx: ToolDispatchContext) {
  const executeTool = getExecuteTool(ctx);
  return ctx.completionTools
    .filter(t => t.function.name !== SubAppIds.plan)  // 看决策点 §6.1
    .map(t => oaiTool({
      name: t.function.name,
      description: t.function.description ?? '',
      parameters: (t.function.parameters as any) ?? { type: 'object', properties: {} },
      strict: false,
      execute: async (input, _runCtx, details) => {
        const callId = details?.toolCall.callId ?? getNanoid(8);
        const { response, usages, nodeResponse, capabilityAssistantResponses } = await executeTool({
          callId,
          toolId: t.function.name,
          args: JSON.stringify(input)
        });
        // 工具内部产生的 usage 立刻 push（沙箱、子工作流、子工具会带）
        if (usages?.length) ctx.usagePush(usages);
        if (nodeResponse) ctx.nodeResponses.push(nodeResponse);
        if (capabilityAssistantResponses?.length) ctx.capAssistantResponses.push(...capabilityAssistantResponses);
        return response;
      }
    }));
}

// 在 dispatchOpenAIAgent 里，照抄 piAgent/index.ts 的 capabilities 初始化逻辑
if (env.SHOW_SKILL) {
  const sandboxCap = await createSandboxSkillsCapability({
    skillIds: normalizedSkillIds,
    teamId, tmbId, sessionId, mode: sandboxMode,
    workflowStreamResponse,
    showSkillReferences,
    allFilesMap
  });
  capabilities.push(sandboxCap);
}

const capabilitySystemPrompt = capabilities.map(c => c.systemPrompt).filter(Boolean).join('\n\n');
const capabilityTools = capabilities.flatMap(c => c.completionTools ?? []);
const capabilityToolCallHandler = createCapabilityToolCallHandler(capabilities);

// 然后构造 Agent
const agent = new Agent({
  name: 'fastgpt-agent',
  instructions: parseUserSystemPrompt({
    userSystemPrompt: `${systemPrompt}\n\n${capabilitySystemPrompt}`.trim(),
    selectedDataset: datasetParams?.datasets
  }),
  tools: buildOpenAITools(toolCtx),  // ← 已含 capabilityTools（沙箱 skill 工具）
  model: cfg.model
});

// env.ts
AGENT_ENGINE: z.enum(['default', 'pi', 'openai']).default('default')

// dispatch/ai/agent/index.ts
if (env.AGENT_ENGINE === 'pi') return dispatchPiAgent(props);
if (env.AGENT_ENGINE === 'openai') return dispatchOpenAIAgent(props);
// 否则走 default Plan+Master

packages/service/core/workflow/dispatch/ai/agent/
├─ openaiAgent/                         (新增目录，参照 piAgent/)
│  ├─ index.ts                          (主调度入口)
│  ├─ modelBridge.ts                    (OpenAI 客户端构建 + Provider 注入)
│  ├─ toolAdapter.ts                    (ChatCompletionTool[] → tool[])
│  ├─ usageBridge.ts                    (RequestUsageEntry[] → ChatNodeUsageType[])
│  └─ streamBridge.ts                   (run_item_stream_event → SSE)
└─ index.ts                             (顶部多加一个 if 分支)

import OpenAI from 'openai';
import { OpenAIProvider, setOpenAIAPI, setTracingDisabled } from '@openai/agents';
import { getLLMModel } from '../../../../../ai/model';

setOpenAIAPI('chat_completions');  // 全局：兼容第三方 endpoint
setTracingDisabled(true);          // 全局：禁止 trace 外发到 OpenAI

const aiProxyBaseUrl = process.env.AIPROXY_API_ENDPOINT ? `${process.env.AIPROXY_API_ENDPOINT}/v1` : undefined;
const defaultBaseUrl = aiProxyBaseUrl || process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1';
const defaultApiKey = process.env.AIPROXY_API_TOKEN || process.env.CHAT_API_KEY || '';

export function buildOpenAIRunner(modelNameOrId?: string) {
  const cfg = getLLMModel(modelNameOrId);
  const rawUrl = cfg?.requestUrl ?? '';
  const baseURL = rawUrl ? rawUrl.replace(/\/chat\/completions$/, '') : defaultBaseUrl;
  const apiKey = cfg?.requestAuth || defaultApiKey;

  const client = new OpenAI({ apiKey, baseURL });
  const provider = new OpenAIProvider({ openAIClient: client });

  return {
    provider,
    modelId: cfg?.model ?? 'gpt-4o',
    modelData: cfg
  };
}

import { tool as oaiTool } from '@openai/agents';
import { SubAppIds } from '@fastgpt/global/core/workflow/node/agent/constants';
import { SseResponseEventEnum } from '@fastgpt/global/core/workflow/runtime/constants';
import { getExecuteTool, type ToolDispatchContext } from '../utils';

export function buildOpenAITools({
  ctx,
  nodeResponses,
  capabilityAssistantResponses,
  usagePush
}: { ctx: ToolDispatchContext; nodeResponses: ChatHistoryItemResType[]; capabilityAssistantResponses: AIChatItemValueItemType[]; usagePush: (u: ChatNodeUsageType[]) => void }) {
  const executeTool = getExecuteTool(ctx);

  return ctx.completionTools
    .filter(t => t.function.name !== SubAppIds.plan)  // OAI-Agents 自管 reasoning,先不喂 plan
    .map(t => {
      const toolId = t.function.name;
      return oaiTool({
        name: toolId,
        description: t.function.description ?? '',
        parameters: (t.function.parameters as any) ?? { type: 'object', properties: {}, additionalProperties: false },
        strict: false,
        async execute(input, _ctx, details) {
          const callId = details?.toolCall.callId ?? '';
          const subInfo = ctx.getSubAppInfo(toolId);

          ctx.streamResponseFn?.({
            id: callId, event: SseResponseEventEnum.toolCall,
            data: { tool: { id: callId, toolName: subInfo?.name || toolId, toolAvatar: subInfo?.avatar || '', functionName: toolId, params: JSON.stringify(input) } }
          });

          const { response, usages = [], nodeResponse, capabilityAssistantResponses: capResps = [] } = await executeTool({
            callId, toolId, args: JSON.stringify(input)
          });

          if (nodeResponse) nodeResponses.push(nodeResponse);
          if (usages.length) usagePush(usages);
          if (capResps.length) capabilityAssistantResponses.push(...capResps);

          ctx.streamResponseFn?.({
            id: callId, event: SseResponseEventEnum.toolResponse,
            data: { tool: { response } }
          });

          return response;
        }
      });
    });
}

import type { ChatNodeUsageType } from '@fastgpt/global/support/wallet/bill/type';
import type { Usage as OAIUsage } from '@openai/agents';
import { formatModelChars2Points } from '../../../../../support/wallet/usage/utils';
import { i18nT } from '../../../../../../web/i18n/utils';

export function convertOAIUsageToChatNodeUsages({
  usage, modelData, userKey
}: { usage: OAIUsage; modelData: LLMModelItemType; userKey?: any }): ChatNodeUsageType[] {
  const entries = usage.requestUsageEntries ?? [];
  if (entries.length === 0) {
    // fallback: 总和当一条
    const totalPoints = userKey ? 0 : formatModelChars2Points({
      model: modelData,
      inputTokens: usage.inputTokens,
      outputTokens: usage.outputTokens
    }).totalPoints;
    return [{
      moduleName: i18nT('account_usage:agent_call'),
      model: modelData.name,
      inputTokens: usage.inputTokens,
      outputTokens: usage.outputTokens,
      totalPoints
    }];
  }

  return entries.map(e => {
    const totalPoints = userKey ? 0 : formatModelChars2Points({
      model: modelData,
      inputTokens: e.inputTokens,
      outputTokens: e.outputTokens
    }).totalPoints;
    return {
      moduleName: i18nT('account_usage:agent_call'),
      model: modelData.name,
      inputTokens: e.inputTokens,
      outputTokens: e.outputTokens,
      totalPoints
    };
  });
}

export const dispatchOpenAIAgent = async (props: DispatchAgentModuleProps): Promise<Response> => {
  // ... 文件、capabilities、systemPrompt、subapps 初始化（直接照抄 piAgent/index.ts:70-160）...

  const { provider, modelId, modelData } = buildOpenAIRunner(model);
  const runner = new Runner({ modelProvider: provider });

  const oaiMessagesKey = `oaiMessages-${nodeId}`;
  const lastHistory = chatHistories[chatHistories.length - 1];
  const restoredStateJSON = lastHistory?.obj === ChatRoleEnum.AI
    ? (lastHistory.memories?.[oaiMessagesKey] as string | undefined)
    : undefined;

  const tools = buildOpenAITools({ ctx: toolCtx, nodeResponses, capabilityAssistantResponses, usagePush });

  const agent = new Agent({
    name: 'fastgpt-agent',
    instructions: formatedSystemPrompt,
    model: modelId,
    tools
  });

  const ctrl = new AbortController();
  const stopPoller = setInterval(() => {
    if (checkIsStopping()) { ctrl.abort(); clearInterval(stopPoller); }
  }, 200);

  let answerText = '';
  let result;
  try {
    const input = restoredStateJSON
      ? await RunState.fromString(agent, restoredStateJSON)  // 续跑
      : formatUserChatInput;

    // 追加新输入到 state（如果是续跑场景）
    const stream = await runner.run(agent, input, {
      signal: ctrl.signal,
      maxTurns: 100,
      stream: true
    });

    for await (const event of stream) {
      if (event.type === 'raw_model_stream_event') {
        // 文本增量
        const delta = (event.data as any).delta;
        if (typeof delta === 'string') {
          answerText += delta;
          workflowStreamResponse?.({
            event: SseResponseEventEnum.answer,
            data: textAdaptGptResponse({ text: delta })
          });
        }
      }
      // tool_called / tool_output 事件已在 buildOpenAITools 内手动 emit，不重复
    }

    await stream.completed;
    result = stream;
  } finally {
    clearInterval(stopPoller);
  }

  // ===== 计费 =====
  usagePush(convertOAIUsageToChatNodeUsages({ usage: result.state.usage, modelData, userKey: externalProvider.openaiAccount }));

  // ===== 返回 =====
  if (answerText) assistantResponses.push({ text: { content: answerText } });

  return {
    data: { [NodeOutputKeyEnum.answerText]: answerText },
    [DispatchNodeResponseKeyEnum.memories]: {
      [oaiMessagesKey]: result.state.toString()  // 序列化全部状态用于跨轮恢复
    },
    [DispatchNodeResponseKeyEnum.assistantResponses]: assistantResponses,
    [DispatchNodeResponseKeyEnum.nodeResponses]: nodeResponses
  };
};

用户输入
   ↓
dispatchRunAgent (env.AGENT_ENGINE='openai')
   ↓
dispatchOpenAIAgent
   ├─ formatFileInput / capabilities / getSubapps   (复用)
   ├─ buildOpenAIRunner(model)                       (新)
   │     └─ new OpenAI({ baseURL, apiKey })
   │     └─ new OpenAIProvider({ openAIClient })
   ├─ buildOpenAITools(ctx)                          (新)
   │     └─ 每个 tool.execute → getExecuteTool(ctx) → 现有分发链
   ├─ runner.run(agent, input, { signal, stream })
   │     ↓
   │   SDK 内部多轮 LLM + tool_call
   │     ↓
   │   stream: raw_model_stream_event / run_item_stream_event
   │     ↓ (toolAdapter 内 emit SSE)
   │   workflowStreamResponse → 客户端
   ├─ convertOAIUsageToChatNodeUsages(result.state.usage)
   │     └─ usagePush(usages)                        (新桥接,复用 formatModelChars2Points)
   └─ result.state.toString() → memories             (跨轮恢复)

cd /Volumes/code/fastgpt-pro/FastGPT/packages/service && pnpm why openai