airtop-agents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Airtop Agents Skill

Airtop Agents 技能

You can list, run, monitor, and cancel Airtop agents using their REST API.

你可以通过REST API列出、运行、监控和取消Airtop Agent。

Authentication

身份验证

The Airtop API key is required for all operations. Resolve it in this order:

```
$AIRTOP_API_KEY
```
environment variable
A
```
.env
```
file in this skill's directory containing
```
AIRTOP_API_KEY=...
```
If neither is found, offer the user two options before proceeding:

Option A — Set it up yourself (recommended if you prefer not to share your key in chat):

Run these commands in your terminal:
cp "$(dirname "$SKILL_PATH")/.env.example" "$(dirname "$SKILL_PATH")/.env"
Then open the
.env
file and replace
your-api-key-here
with your key from https://portal.airtop.ai/api-keys.
Once done, say "done" and I'll pick it up automatically.

Option B — Paste it here and I'll save it for you:
Paste your API key (from https://portal.airtop.ai/api-keys) and I'll write it to the
.env
file so it's available for future use.

Print both options exactly as above (with the actual resolved path instead of the

$(dirname ...)

expression) and wait for the user to choose. Do not assume a preference.

所有操作都需要Airtop API密钥，按以下顺序获取：

```
$AIRTOP_API_KEY
```
环境变量
本技能目录下包含
```
AIRTOP_API_KEY=...
```
的
```
.env
```
文件
如果以上都未找到，在继续前向用户提供两个选项：

选项A — 自行设置（推荐，如果你不想在聊天中共享密钥）：

在终端中运行以下命令：
cp "$(dirname "$SKILL_PATH")/.env.example" "$(dirname "$SKILL_PATH")/.env"
然后打开
.env
文件，将
your-api-key-here
替换为你从https://portal.airtop.ai/api-keys获取的密钥。
设置完成后，回复“done”，我会自动读取密钥。

选项B — 在此粘贴密钥，我会帮你保存：

粘贴你的API密钥（来自https://portal.airtop.ai/api-keys），我会将其写入`.env`文件，方便后续使用。

请完全按照上述内容展示两个选项（将

$(dirname ...)

表达式替换为实际解析后的路径），然后等待用户选择，不要预设偏好。

Handling a pasted key (Option B)

处理粘贴的密钥（选项B）

Important — always load the key from the
.env
file, never use a pasted value directly.

When a user provides their API key interactively (e.g. pasting it into chat), text copied from web UIs or chat messages can contain invisible Unicode characters (zero-width spaces, byte-order marks, etc.) that silently break authentication. To avoid this:

Write the key to
.env
first — this round-trips it through file I/O which strips invisible characters:
bash
```
echo "AIRTOP_API_KEY=<pasted-value>" > "$(dirname "$SKILL_PATH")/.env"
```

Then read it back from the file to get a clean value:

bash

API_KEY=$(grep AIRTOP_API_KEY "$(dirname "$SKILL_PATH")/.env" | cut -d= -f2-)

Even when

$AIRTOP_API_KEY

is already set in the environment, prefer loading from

.env

if the file exists — the environment variable may have been set in the same shell session from a pasted value and could carry the same invisible characters.

Never assign a user-pasted key directly to a shell variable and use it in API calls (e.g.

API_KEY="<pasted-value>"

followed by

curl -H "Authorization: Bearer $API_KEY"

). Always go through the

.env

file write-then-read cycle to sanitize the value.

重要提示 — 始终从
.env
文件加载密钥，切勿直接使用粘贴的值。

当用户通过交互方式提供API密钥时（例如粘贴到聊天框），从网页UI或聊天消息复制的文本可能包含不可见的Unicode字符（零宽空格、字节顺序标记等），这些字符会导致身份验证静默失败。为避免此问题：

先将密钥写入
.env
文件 — 通过文件I/O往返处理可以去除不可见字符：
bash
```
echo "AIRTOP_API_KEY=<pasted-value>" > "$(dirname "$SKILL_PATH")/.env"
```

再从文件中读取 以获取干净的密钥值：

bash

API_KEY=$(grep AIRTOP_API_KEY "$(dirname "$SKILL_PATH")/.env" | cut -d= -f2-)

即使环境中已设置

$AIRTOP_API_KEY

，如果

.env

文件存在，也优先从该文件加载 — 环境变量可能是在同一个shell会话中从粘贴的值设置的，可能包含相同的不可见字符。

切勿将用户粘贴的密钥直接赋值给shell变量并用于API调用（例如

API_KEY="<pasted-value>"

后接

curl -H "Authorization: Bearer $API_KEY"

）。始终通过写入

.env

文件再读取的流程来清理值。

Loading and validating the key

加载并验证密钥

Once the

.env

file exists (whether set up by the user or written by you), load and validate:

bash

API_KEY=$(grep AIRTOP_API_KEY "$(dirname "$SKILL_PATH")/.env" | cut -d= -f2-)

Validate the key immediately after loading it:

bash

curl -sf -H "Authorization: Bearer ${API_KEY}" "https://api.airtop.ai/api/v2/agents?limit=1" > /dev/null

If this returns a non-zero exit code, tell the user their API key appears invalid and link them to https://portal.airtop.ai/api-keys.

一旦

.env

文件存在（无论是用户自行设置还是由你写入），加载并验证：

bash

API_KEY=$(grep AIRTOP_API_KEY "$(dirname "$SKILL_PATH")/.env" | cut -d= -f2-)

加载后立即验证密钥：

bash

curl -sf -H "Authorization: Bearer ${API_KEY}" "https://api.airtop.ai/api/v2/agents?limit=1" > /dev/null

如果返回非零退出码，告知用户其API密钥无效，并引导他们访问https://portal.airtop.ai/api-keys。

Base URL

基础URL

All authenticated API endpoints use:

https://api.airtop.ai/api

Webhook endpoints (run agent, poll result) use the public path:

https://api.airtop.ai/api/hooks/

所有需要身份验证的API端点使用：

https://api.airtop.ai/api

Webhook端点（运行Agent、轮询结果）使用公共路径：

https://api.airtop.ai/api/hooks/

Argument Parsing

参数解析

Parse

$ARGUMENTS

as follows:

list [--name <filter>]              List agents
run <agent-name-or-id> [--vars {}]  Run an agent with optional config variables
status <agentId> <invocationId>     Check invocation status
cancel <agentId> <invocationId>     Cancel a running invocation
history <agentId>                   View recent invocations

$ARGUMENTS

is empty or unrecognized, show the usage summary above and ask the user what they'd like to do.

按以下规则解析

$ARGUMENTS

：

list [--name <filter>]              列出Agent
run <agent-name-or-id> [--vars {}]  运行Agent，可附带配置变量
status <agentId> <invocationId>     检查调用状态
cancel <agentId> <invocationId>     取消正在运行的调用
history <agentId>                   查看近期调用记录

如果

$ARGUMENTS

为空或无法识别，展示上述使用说明并询问用户需求。

Commands

命令

1. List Agents

1. 列出Agent

bash

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://api.airtop.ai/api/v2/agents?limit=25&sortBy=lastRun&sortOrder=desc&createdByMe=true"

Always include

createdByMe=true

to show only agents owned by the current user (not the entire organization).

Optional query parameters to append:

```
&name=<filter>
```
— case-insensitive partial match (use when
```
--name
```
is provided)
```
&enabled=true
```
— filter to enabled agents only
```
&published=true
```
— filter to published agents only

Display: Format the response as a markdown table with columns: Name, ID, Enabled, Last Run. Show the

pagination.total

count in a header line.

Example output:

Found 3 agents:
| Name              | ID                                   | Enabled | Last Run    |
|-------------------|--------------------------------------|---------|-------------|
| Price Tracker     | 550e8400-e29b-41d4-a716-446655440000 | Yes     | 2 hours ago |
| Lead Enricher     | 6ba7b810-9dad-11d1-80b4-00c04fd430c8 | Yes     | Yesterday   |
| Competitor Monitor| 6ba7b811-9dad-11d1-80b4-00c04fd430c8 | No      | Never       |

bash

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://api.airtop.ai/api/v2/agents?limit=25&sortBy=lastRun&sortOrder=desc&createdByMe=true"

始终包含

createdByMe=true

以仅显示当前用户拥有的Agent（而非整个组织的）。

可选的查询参数：

```
&name=<filter>
```
— 不区分大小写的部分匹配（当提供
```
--name
```
时使用）
```
&enabled=true
```
— 仅筛选启用的Agent
```
&published=true
```
— 仅筛选已发布的Agent

展示方式：将响应格式化为Markdown表格，列包括：名称、ID、启用状态、最后运行时间。在表头行显示

pagination.total

的计数。

示例输出：

找到3个Agent：
| 名称              | ID                                   | 启用状态 | 最后运行时间 |
|-------------------|--------------------------------------|---------|-------------|
| 价格追踪器        | 550e8400-e29b-41d4-a716-446655440000 | 是      | 2小时前     |
| 线索丰富器        | 6ba7b810-9dad-11d1-80b4-00c04fd430c8 | 是      | 昨天        |
| 竞品监控器        | 6ba7b811-9dad-11d1-80b4-00c04fd430c8 | 否      | 从未运行    |

2. Run Agent

2. 运行Agent

This is a multi-step process:

Step 1 — Resolve agent by name or ID.

If the argument looks like a UUID, use it directly as the agent ID. Otherwise, search by name:

bash

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://api.airtop.ai/api/v2/agents?name=$(printf '%s' '<agent-name>' | jq -sRr @uri)&createdByMe=true"

If exactly one agent matches, use it (but still validate it in Step 2).
If multiple agents match, prefer enabled and published agents over disabled or draft-only ones. If there is still ambiguity, display them in a table (with Enabled and Published status columns) and ask the user to pick one.
If no agents match, tell the user no agent was found and suggest running
```
list
```
.

Step 2 — Validate the agent is runnable.

Fetch the full agent details (already available from step 1 if resolved by name, or fetch now):

bash

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://api.airtop.ai/api/v2/agents/<agentId>"

Check the following before proceeding:

Disabled agent (
```
enabled
```
is
```
false
```
): Tell the user the agent is disabled and cannot be run. Suggest they enable it in the Airtop portal.
Draft-only agent (
```
hasDraft
```
is
```
true
```
AND
```
publishedVersion
```
is absent): Tell the user the agent has only a draft version and has never been published. It must be published in the Airtop portal before it can be invoked via webhook.
Published agent with draft (
```
hasDraft
```
is
```
true
```
AND
```
publishedVersion
```
is present): The agent is runnable. Note to the user that the agent has unpublished draft changes, and the published version will be used. Use the
```
publishedVersion
```
value for the version parameter.
Published agent (
```
publishedVersion
```
is present,
```
hasDraft
```
is
```
false
```
): The agent is runnable. Use the
```
publishedVersion
```
value for the version parameter.

Step 3 — Check required configVars.

The agent details response includes a

versionData.configVarsSchema

field. Inspect it for

required

properties. If the user has not provided values for required configVars via

--vars

, prompt them for the missing values before invoking.

Display the required and optional parameters with their descriptions and defaults so the user knows what to provide.

Step 4 — Get the agent's webhook.

bash

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://api.airtop.ai/api/v2/agents/<agentId>/webhooks?limit=10"

Use the first webhook from the

webhooks

array. If no webhooks exist, tell the user the agent needs a webhook configured in the Airtop portal (https://portal.airtop.ai).

Step 5 — Invoke the webhook.

bash

curl -s -X POST "https://api.airtop.ai/api/hooks/agents/<agentId>/webhooks/<webhookId>" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "configVars": { <user-provided key-value pairs from --vars, or empty object {}> },
    "version": <publishedVersion from agent details>
  }'

Always use the

publishedVersion

value from the agent details as the

version

parameter — never hardcode it.

The response contains

{ "invocationId": "<uuid>" }

. Save this for polling.

Step 6 — Poll for the result.

bash

curl -s "https://api.airtop.ai/api/hooks/agents/<agentId>/invocations/<invocationId>/result" \
  -H "Authorization: Bearer $API_KEY"

Polling rules:

Poll every 5 seconds
Print a status update to the user after each poll (e.g., "Status: Running...")
Terminal statuses:
```
Completed
```
,
```
Failed
```
,
```
Cancelled
```
Timeout after 5 minutes (60 polls). If not complete, tell the user the invocation is still running and provide the invocation ID so they can check later with the
```
status
```
command.

Step 7 — Display the result.

On
```
Completed
```
: Show the
```
output
```
field. If it's JSON, format it nicely. If it's a string, display it directly.
On
```
Failed
```
: Show the
```
error
```
field and the full status.
On
```
Cancelled
```
: Inform the user the invocation was cancelled.

这是一个多步骤流程：

步骤1 — 通过名称或ID解析Agent。

如果参数看起来是UUID，直接将其作为Agent ID使用。否则，按名称搜索：

bash

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://api.airtop.ai/api/v2/agents?name=$(printf '%s' '<agent-name>' | jq -sRr @uri)&createdByMe=true"

如果恰好匹配一个Agent，使用该Agent（但仍需在步骤2中验证）。
如果匹配多个Agent，优先选择已启用且已发布的Agent，而非禁用或仅草稿的Agent。如果仍有歧义，将它们以表格形式展示（包含启用状态和发布状态列），并请用户选择一个。
如果没有匹配的Agent，告知用户未找到，并建议运行
```
list
```
命令。

步骤2 — 验证Agent是否可运行。

获取完整的Agent详情（如果是通过名称解析的，步骤1中已获取；否则现在获取）：

bash

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://api.airtop.ai/api/v2/agents/<agentId>"

继续之前检查以下内容：

禁用的Agent（
```
enabled
```
为
```
false
```
）：告知用户该Agent已禁用，无法运行。建议他们在Airtop门户中启用。
仅草稿Agent（
```
hasDraft
```
为
```
true
```
且
```
publishedVersion
```
不存在）：告知用户该Agent只有草稿版本，从未发布。必须先在Airtop门户中发布，才能通过Webhook调用。
有草稿的已发布Agent（
```
hasDraft
```
为
```
true
```
且
```
publishedVersion
```
存在）：该Agent可运行。告知用户该Agent有未发布的草稿变更，将使用已发布版本。使用
```
publishedVersion
```
值作为版本参数。
已发布Agent（
```
publishedVersion
```
存在，
```
hasDraft
```
为
```
false
```
）：该Agent可运行。使用
```
publishedVersion
```
值作为版本参数。

步骤3 — 检查必填configVars。

Agent详情响应包含

versionData.configVarsSchema

字段。检查其中的

required

属性。如果用户未通过

--vars

提供必填configVars的值，在调用前提示用户补充。

展示必填和可选参数及其描述和默认值，方便用户了解需要提供的内容。

步骤4 — 获取Agent的Webhook。

bash

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://api.airtop.ai/api/v2/agents/<agentId>/webhooks?limit=10"

使用

webhooks

数组中的第一个Webhook。如果没有Webhook，告知用户需要在Airtop门户（https://portal.airtop.ai）中为该Agent配置Webhook。

步骤5 — 调用Webhook。

bash

curl -s -X POST "https://api.airtop.ai/api/hooks/agents/<agentId>/webhooks/<webhookId>" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "configVars": { <用户通过--vars提供的键值对，或空对象{}> },
    "version": <Agent详情中的publishedVersion>
  }'

始终使用Agent详情中的

publishedVersion

值作为

version

参数 — 切勿硬编码。

响应包含

{ "invocationId": "<uuid>" }

。保存该ID用于轮询。

步骤6 — 轮询结果。

bash

curl -s "https://api.airtop.ai/api/hooks/agents/<agentId>/invocations/<invocationId>/result" \
  -H "Authorization: Bearer $API_KEY"

轮询规则：

每5秒轮询一次
每次轮询后向用户输出状态更新（例如：“状态：运行中...”）
终止状态包括：
```
Completed
```
（完成）、
```
Failed
```
（失败）、
```
Cancelled
```
（已取消）
5分钟后超时（60次轮询）。如果仍未完成，告知用户调用仍在运行，并提供调用ID，以便他们后续使用
```
status
```
命令检查。

步骤7 — 展示结果。

当状态为
```
Completed
```
：展示
```
output
```
字段。如果是JSON，进行格式化展示；如果是字符串，直接显示。
当状态为
```
Failed
```
：展示
```
error
```
字段和完整状态。
当状态为
```
Cancelled
```
：告知用户调用已取消。

3. Check Status

3. 检查状态

Poll a specific invocation's result:

bash

curl -s "https://api.airtop.ai/api/hooks/agents/<agentId>/invocations/<invocationId>/result" \
  -H "Authorization: Bearer $API_KEY"

Display the

status

field. If terminal, also display

output

error

Note: This requires both the agent ID and invocation ID. If the user only provides one, ask for the other.

轮询特定调用的结果：

bash

curl -s "https://api.airtop.ai/api/hooks/agents/<agentId>/invocations/<invocationId>/result" \
  -H "Authorization: Bearer $API_KEY"

展示

status

字段。如果是终止状态，同时展示

output

或

error

。

注意：此命令需要Agent ID和调用ID。如果用户只提供了其中一个，询问另一个。

4. Cancel Invocation

4. 取消调用

bash

curl -s -X DELETE -H "Authorization: Bearer $API_KEY" \
  "https://api.airtop.ai/api/v2/agents/<agentId>/invocations/<invocationId>?reason=user_requested"

Confirm to the user that the cancellation was requested.

bash

curl -s -X DELETE -H "Authorization: Bearer $API_KEY" \
  "https://api.airtop.ai/api/v2/agents/<agentId>/invocations/<invocationId>?reason=user_requested"

向用户确认已请求取消调用。

5. View History

5. 查看调用记录

bash

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://api.airtop.ai/api/v2/agents/<agentId>/invocations?limit=10"

Display results as a table with columns: Invocation ID, Status, Trigger, Started At.

bash

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://api.airtop.ai/api/v2/agents/<agentId>/invocations?limit=10"

将结果以表格形式展示，列包括：调用ID、状态、触发方式、开始时间。

Error Handling

错误处理

401 Unauthorized: Tell the user their API key is invalid or expired. Direct them to https://portal.airtop.ai/api-keys.
404 Not Found: The agent or invocation doesn't exist. Suggest checking the ID or running
```
list
```
.
429 Rate Limited: Tell the user they've hit the rate limit and should wait before retrying.
No webhook configured: Explain that the agent needs a webhook set up in the Airtop portal before it can be invoked from the CLI.
Multiple name matches: List all matches and ask the user to pick one or use the agent ID directly.
Empty API key: Guide the user to set
```
AIRTOP_API_KEY
```
or provide it interactively.

401 Unauthorized：告知用户其API密钥无效或已过期。引导他们访问https://portal.airtop.ai/api-keys。
404 Not Found：Agent或调用不存在。建议检查ID或运行
```
list
```
命令。
429 Rate Limited：告知用户已达到速率限制，应等待后重试。
未配置Webhook：说明需要在Airtop门户中为Agent配置Webhook，才能从CLI调用。
多个名称匹配：列出所有匹配项并请用户选择一个，或直接使用Agent ID。
API密钥为空：引导用户设置
```
AIRTOP_API_KEY
```
或交互式提供密钥。

Important Notes

重要说明

Always use
```
curl -s
```
(silent mode) to avoid progress bars in output.
Parse all JSON responses with
```
jq
```
or inline JSON parsing in bash.
The webhook invoke and poll endpoints are under
```
/api/hooks/
```
(public path), NOT
```
/api/v2/
```
.
The list, webhooks, history, and cancel endpoints are under
```
/api/v2/
```
(authenticated path).
When displaying times, convert ISO timestamps to human-readable relative times (e.g., "2 hours ago").

始终使用
```
curl -s
```
（静默模式）以避免输出进度条。
使用
```
jq
```
或bash中的内联JSON解析来处理所有JSON响应。
Webhook调用和轮询端点位于
```
/api/hooks/
```
（公共路径），而非
```
/api/v2/
```
。
列表、Webhook、调用记录和取消端点位于
```
/api/v2/
```
（需身份验证的路径）。
展示时间时，将ISO时间戳转换为人类可读的相对时间（例如“2小时前”）。