> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 执行 Skill 与工具

> 把工作流步骤连接到已有 Agent、工具或本地业务函数，并回报实际结果。

你已有生成报告的 Agent 和发布报告的工具，希望按工作流调用它们。为每项能力注册处理函数，Runtime 就能根据步骤的 `ref` 找到对应执行入口。

先完成 [快速接入](/zh/sdk/quickstart.md)。本页沿用其中的 `workflow`、`host` 和 `runtime`，代码片段替换对应配置。

## 选择步骤类型

```js theme={null}
import { skill, tool } from '@rpamis/comet/runtime';

const steps = {
  draft: skill({ ref: 'draft-report' }),
  publish: tool({ ref: 'publish-report', retry: 'reconcile' }),
};
```

`skill` 声明由 Agent 平台执行 Skill，动作类型为 `invoke_skill`；`tool` 声明工具调用，动作类型为 `call_tool`。它们不会自动搜索本地 Skill，也不会替你连接模型或 MCP。处理函数的名称必须与 `ref` 一致。

## 校验输入，取得上游结果

下面是可直接注册的本地处理函数。它读取 `draft` 步骤的真实输出；你可以在验证输入后接入自己的发布接口。

```js theme={null}
import { createRuntimeExecutor, defineRuntimeHandler } from '@rpamis/comet/runtime';

const host = createRuntimeExecutor({
  id: 'host',
  handlers: {
    'publish-report': defineRuntimeHandler({
      type: 'call_tool',
      parseInput: ({ outputs }) => {
        if (typeof outputs.draft !== 'string') {
          throw new Error('Expected a report from draft');
        }
        return { report: outputs.draft };
      },
      execute: ({ report }, { action }) => {
        console.log(action.id, report);
        return { status: 'succeeded', output: { published: true } };
      },
    }),
  },
});
```

`parseInput` 接收当前输入 `input`、本次激活的上游输出 `outputs` 和可选的激活输入 `activation`。这里的 `outputs.draft` 是业务值；读取 Run 中的输出时，值位于 `run.outputs.draft.value`。

`execute` 的第二个参数提供原 Action 和执行器上下文。接入外部服务时保存服务返回的收据，并关联这个 Action，便于中断后查询。TypeScript 可以推导单个处理函数的输入类型；跨步骤的 JSON 仍要校验。

## 注册并推进

将执行器放入 `createRuntime({ executors: [host], ... })`，再调用：

```js theme={null}
const progress = await runtime.runUntilBlocked({
  runId: 'report-1',
  executorId: 'host',
  maxActions: 20,
});
console.log(progress.reason, progress.actionsExecuted);
```

`maxActions` 限制本次调用尝试执行的动作数，不限制单个模型或工具调用的耗时。超时、取消和模型预算需要由执行器实现。返回 `executor-required` 时检查处理函数的 `ref`、`type` 和执行器支持的能力。

## 回报成功、失败和未知结果

| 实际情况 | 处理方式 |
| - | - |
| 已取得成功结果 | 返回 `status: 'succeeded'` 和实际输出。 |
| 已确认业务失败 | 返回 `status: 'failed'` 和错误详情；沿声明的失败路径处理。 |
| 派发后断连，无法判断是否成功 | 保留未知结果，查询原操作后再恢复。 |

外部操作完成后，处理函数仍可能抛错，Runtime 会保守处理。不要通过重复发布、付款或发消息来试探原操作是否成功。接入方法见 [恢复与未知结果](/zh/sdk/recovery.md)。

模型密钥和工具凭据由执行器闭包或当前执行环境提供，不放进 Workflow、Run、输出或审批提案。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.