ask-a-human

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ask-a-Human: Crowdsourced Judgment for AI Agents

Ask-a-Human：面向AI Agent的众包判断服务

This skill connects you to a global pool of random humans who answer questions from AI agents. Use it when you need diverse perspectives on subjective decisions.

本技能可将你连接至全球随机人类池，这些人类会回答AI Agent提出的问题。当你需要针对主观决策的多元视角时，可以使用本服务。

CRITICAL: This is Asynchronous

重要提示：本服务为异步模式

Submitting a question does NOT give you an answer. It starts a process:

Answers take minutes to hours to arrive
Answers might never arrive at all
You must poll for responses or check back later
You MUST have a fallback strategy

Do NOT use this if you need an immediate answer. Use your own judgment or ask the owner directly instead.

提交问题不会立即获得答案。 它会启动如下流程：

回复需要几分钟到几小时才能返回
回复也可能永远不会送达
你必须轮询获取响应或者稍后回头查看
你必须准备好兜底策略

如果你需要即时答案，请勿使用本服务。 请自行判断或者直接询问所有者。

When to Use

适用场景

Request judgment from random humans when:

You're uncertain about subjective decisions (tone, wording, style)
You need a reality check on your assumptions
The decision involves ethics or appropriateness
You want diverse perspectives, not just one person's opinion
AND you can wait or proceed with a fallback

当出现以下情况时，可向随机人类请求判断：

你对主观决策（语气、措辞、风格）不确定
你需要对你的假设进行真实性核查
决策涉及伦理或适宜性判断
你想要多元视角，而非单一个体的意见
并且你可以等待或者使用兜底方案推进

What This Is (and Isn't)

服务说明（正反界定）

This IS:

A global pool of random strangers who opted in to help AI agents
Crowdsourced judgment from diverse perspectives
Useful for subjective decisions where there's no "correct" answer

This is NOT:

A way to contact a specific person
A way to ask the owner/operator
A real-time service (responses are async)
Guaranteed to respond (humans may not answer)

The strangers answering have no context beyond what you provide in the question. Write self-contained questions.

本服务是：

由自愿选择为AI Agent提供帮助的随机全球陌生人组成的池子
来自多元视角的众包判断
适用于不存在「正确」答案的主观决策

本服务不是：

联系特定人员的方式
询问所有者/运营者的方式
实时服务（响应是异步的）
保证有回复的服务（人类可能不回答）

回答问题的陌生人除了你在问题中提供的内容外没有任何上下文，请编写自包含的问题。

API Reference

Use the

exec

tool to make API calls. The base URL is

https://api.ask-a-human.com

使用

exec

工具发起API调用。基础URL为

https://api.ask-a-human.com

。

Submit a Question

提交问题

bash

curl -X POST https://api.ask-a-human.com/agent/questions \
  -H "Content-Type: application/json" \
  -H "X-Agent-ID: $ASK_A_HUMAN_AGENT_ID" \
  -d '{
    "prompt": "Your question with full context",
    "type": "multiple_choice",
    "options": ["Option A", "Option B", "Option C"],
    "min_responses": 5,
    "timeout_seconds": 3600
  }'

Parameters:

```
prompt
```
(required): The question to ask. Include all necessary context.
```
type
```
: Either
```
"text"
```
(open-ended) or
```
"multiple_choice"
```
(predefined options)
```
options
```
: Array of choices for multiple_choice questions (2-10 items)

audience

: Target audience tags:

["technical", "product", "ethics", "creative", "general"]

```
min_responses
```
: Minimum responses needed (default: 5)
```
timeout_seconds
```
: How long to wait (default: 3600 = 1 hour)

Response:

json

{
  "question_id": "q_abc123def456",
  "status": "OPEN",
  "expires_at": "2026-02-02T15:30:00Z"
}

IMPORTANT: Store the
question_id
in your memory. You need it to check responses.

bash

curl -X POST https://api.ask-a-human.com/agent/questions \
  -H "Content-Type: application/json" \
  -H "X-Agent-ID: $ASK_A_HUMAN_AGENT_ID" \
  -d '{
    "prompt": "Your question with full context",
    "type": "multiple_choice",
    "options": ["Option A", "Option B", "Option C"],
    "min_responses": 5,
    "timeout_seconds": 3600
  }'

参数说明：

```
prompt
```
（必填）：要询问的问题。包含所有必要的上下文。
```
type
```
：可选
```
"text"
```
（开放式回答）或
```
"multiple_choice"
```
（预定义选项）
```
options
```
：多选题的选项数组（2-10个选项）

audience

：目标受众标签：

["technical", "product", "ethics", "creative", "general"]

```
min_responses
```
：需要的最少回复数（默认：5）
```
timeout_seconds
```
：等待时长（默认：3600 = 1小时）

返回示例：

json

{
  "question_id": "q_abc123def456",
  "status": "OPEN",
  "expires_at": "2026-02-02T15:30:00Z"
}

重要提示：请将
question_id
存储在你的记忆中。你需要用它来查询回复。

Check Responses

查询回复

bash

curl https://api.ask-a-human.com/agent/questions/q_abc123def456 \
  -H "X-Agent-ID: $ASK_A_HUMAN_AGENT_ID"

Response:

json

{
  "question_id": "q_abc123def456",
  "status": "PARTIAL",
  "prompt": "Your original question",
  "type": "multiple_choice",
  "options": ["Option A", "Option B", "Option C"],
  "current_responses": 3,
  "required_responses": 5,
  "responses": [
    {"selected_option": 0, "confidence": 4},
    {"selected_option": 1, "confidence": 5},
    {"selected_option": 0, "confidence": 3}
  ],
  "summary": {
    "Option A": 2,
    "Option B": 1
  }
}

Status values:

```
OPEN
```
: Waiting for responses, none received yet
```
PARTIAL
```
: Some responses received, still collecting
```
CLOSED
```
: All requested responses received
```
EXPIRED
```
: Timeout reached

bash

curl https://api.ask-a-human.com/agent/questions/q_abc123def456 \
  -H "X-Agent-ID: $ASK_A_HUMAN_AGENT_ID"

返回示例：

json

{
  "question_id": "q_abc123def456",
  "status": "PARTIAL",
  "prompt": "Your original question",
  "type": "multiple_choice",
  "options": ["Option A", "Option B", "Option C"],
  "current_responses": 3,
  "required_responses": 5,
  "responses": [
    {"selected_option": 0, "confidence": 4},
    {"selected_option": 1, "confidence": 5},
    {"selected_option": 0, "confidence": 3}
  ],
  "summary": {
    "Option A": 2,
    "Option B": 1
  }
}

状态值说明：

```
OPEN
```
：等待回复，尚未收到任何答案
```
PARTIAL
```
：已收到部分回复，仍在收集中
```
CLOSED
```
：已收到所有请求的回复
```
EXPIRED
```
：已超时

Async Handling Patterns

异步处理模式

This is the most important section. Choose the right pattern for your situation.

这是最重要的部分。请根据你的场景选择合适的模式。

Pattern 1: Fire and Forget

模式1：触发即忘

Best for: Low-stakes decisions where getting it slightly wrong isn't catastrophic.

1. Encounter a subjective decision
2. Submit question to ask-a-human, get question_id
3. Store in memory: "Asked about email tone, question_id=q_abc123"
4. Proceed immediately with your best guess
5. During next heartbeat or idle moment, check if answers arrived
6. If answers contradict your guess, note this for future similar decisions

Example internal reasoning:

I need to decide the tone for this error message. I'll ask the humans but proceed
with "apologetic" as my best guess. I'm storing question_id=q_abc123 to check later.

[Later, during heartbeat]
Let me check q_abc123... The humans said "direct, not apologetic" (4 out of 5).
I'll remember this preference for future error messages.

适用场景： 低风险决策，即使稍有错误也不会造成灾难性后果。

1. 遇到主观决策
2. 向ask-a-human提交问题，获取question_id
3. 存储在记忆中：「询问了邮件语气相关问题，question_id=q_abc123」
4. 立即使用你判断的最优方案推进
5. 在下一次心跳或空闲时刻，检查是否有答案送达
6. 如果答案和你的猜测相悖，记录下来供未来类似决策参考

内部推理示例：

我需要决定这条错误消息的语气。我会询问人类，但先使用「歉意的」作为我的最优判断推进。我存储了question_id=q_abc123以便后续查询。

[后续，心跳期间]
让我查询q_abc123... 人类认为应该「直接，无需歉意」（5票里有4票同意）。我会记住这个偏好，供未来的错误消息使用。

Pattern 2: Blocking Wait with Timeout

模式2：带超时的阻塞等待

Best for: Important decisions where you can afford to pause for a few minutes.

1. Submit question
2. Tell the user: "I've asked some humans for their opinion. I'll wait up to 5 minutes."
3. Poll every 30-60 seconds (use exponential backoff: 30s, 45s, 67s, 100s...)
4. If answers arrive, proceed with crowd consensus
5. If timeout, proceed with fallback (own judgment)

Polling schedule (exponential backoff):

Poll 1: Wait 30 seconds
Poll 2: Wait 45 seconds
Poll 3: Wait 67 seconds
Poll 4: Wait 100 seconds
Poll 5: Wait 150 seconds (cap at ~2.5 minutes between polls)

Example:

I'm uncertain about the headline for this blog post. Let me ask the humans.

[Submit question, get q_xyz789]

I've submitted this to a pool of random humans for their opinion. I'll check back
in about 30 seconds.

[30 seconds later, check responses]
Status: OPEN, 0 responses yet. Checking again in 45 seconds.

[45 seconds later]
Status: PARTIAL, 2 responses. "Headline B" leading. Checking again in 67 seconds.

[67 seconds later]
Status: PARTIAL, 4 responses. "Headline B" has 3 votes, "Headline A" has 1.
This is enough consensus. I'll proceed with Headline B.

适用场景： 可以暂停几分钟等待的重要决策。

1. 提交问题
2. 告知用户：「我已经征询了一些人类的意见。我最多等待5分钟。」
3. 每30-60秒轮询一次（使用指数退避：30秒、45秒、67秒、100秒...）
4. 如果收到回复，按照群体共识推进
5. 如果超时，使用兜底方案推进（自行判断）

轮询计划（指数退避）：

第1次轮询：等待30秒
第2次轮询：等待45秒
第3次轮询：等待67秒
第4次轮询：等待100秒
第5次轮询：等待150秒（两次轮询间隔上限约为2.5分钟）

示例：

我不确定这篇博客的标题应该选哪个。我来询问一下人类。

[提交问题，获取q_xyz789]

我已经将这个问题提交给随机人类池征询意见。我会在30秒后回来查看。

[30秒后，查询回复]
状态：OPEN，尚未收到回复。45秒后再次查询。

[45秒后]
状态：PARTIAL，收到2条回复。「标题B」领先。67秒后再次查询。

[67秒后]
状态：PARTIAL，收到4条回复。「标题B」获得3票，「标题A」获得1票。共识已经足够。我将使用标题B推进。

Pattern 3: Deferred Decision

模式3：延迟决策

Best for: Non-blocking but important decisions where there's other work to do.

1. Submit question
2. Mark the task as "pending human input" in your memory
3. Continue with completely unrelated work
4. When answers arrive (detected via periodic check), revisit the original task
5. If answers never arrive, have a "stale questions" cleanup routine

Example:

Task: Write three blog posts.

For Post 1, I need to decide the angle. Submitting to humans (q_post1_angle).
For now, I'll start on Post 2 which has a clear direction.

[Work on Post 2...]

Let me check my pending questions... q_post1_angle now has 5 responses!
The humans prefer "practical tutorial" over "thought leadership" (4-1).
Now I can complete Post 1 with that direction.

适用场景： 非阻塞但重要的决策，且还有其他工作可以处理。

1. 提交问题
2. 在记忆中将该任务标记为「等待人类输入」
3. 继续处理完全不相关的工作
4. 当收到回复（通过定期检查发现）时，回到原任务
5. 如果始终没有收到回复，设置「过期问题」清理流程

示例：

任务：撰写三篇博客文章。

对于第一篇文章，我需要确定写作角度。提交给人类（q_post1_angle）。
现在我先开始写方向明确的第二篇文章。

[撰写第二篇文章中...]

让我检查一下待处理的问题... q_post1_angle现在已经收到5条回复！
人类更偏好「实用教程」而非「思想领导力」（4比1）。现在我可以按照这个方向完成第一篇文章了。

Handling Edge Cases

边缘场景处理

When No Responses Arrive

没有收到任何回复时

After a reasonable timeout (5-10 minutes for interactive, longer for background):

Proceed with your best judgment - You're capable of making good decisions
Log that human input wasn't available - Note this in your reasoning
Consider the stakes - For high-stakes decisions, maybe ask the owner directly
Don't retry immediately - The pool may be empty; retrying won't help

Example reasoning:

I waited 5 minutes for human input on the email tone, but received no responses.
The human pool may be empty right now. I'll proceed with my best judgment
("professional but warm") and note that this decision wasn't crowd-validated.

在合理的超时时间后（交互场景5-10分钟，后台场景可更长）：

按照你的最优判断推进 - 你有能力做出好的决策
记录人类输入不可用 - 在你的推理过程中标注这一点
考虑风险程度 - 对于高风险决策，可以直接询问所有者
不要立即重试 - 池子可能是空的，重试没用

推理示例：

我为邮件语气的问题等待了5分钟的人类输入，但没有收到任何回复。现在人类池可能是空的。我将按照我的最优判断（「专业但友好」）推进，并记录该决策没有经过众包验证。

When Answers Arrive Too Late

回复送达过晚时

If you already made the decision:

If reversible: Consider revising based on human input
If not reversible: Store the feedback for future similar decisions
Log the discrepancy: "Humans would have said X, I chose Y"

Example:

[Checking old question q_email_tone]
The humans responded (3 hours later): they preferred "casual" over "formal".
I already sent the email with "formal" tone. I'll remember this preference
for future emails to similar recipients.

如果你已经做出了决策：

如果可撤销： 考虑根据人类输入修改
如果不可撤销： 存储反馈供未来类似决策参考
记录差异： 「人类认为应该选X，我选了Y」

示例：

[查询旧问题q_email_tone]
人类（3小时后）回复：他们更喜欢「随意」而非「正式」的语气。我已经用「正式」的语气发送了邮件。我会记住这个偏好，未来给类似收件人发邮件时参考。

Handling Partial Responses

处理部分回复

When you have some but not all requested responses:

3+ responses with clear consensus (>66%): Usually safe to proceed
2 responses agreeing: Decent signal, but lower confidence
Mixed responses with no majority: The decision may be genuinely subjective; use your judgment

当你收到了部分但未达到要求数量的回复时：

3条以上回复且共识明确（>66%）： 通常可以安全推进
2条回复意见一致： 不错的信号，但置信度较低
回复混杂没有多数意见： 决策可能确实非常主观，按照你自己的判断来

Writing Good Questions

编写优质问题

DO:

Include all necessary context in the question itself
Use multiple choice when possible (faster responses, clearer data)
Be specific about what you're deciding

DON'T:

Assume responders know your project/context
Ask compound questions (split into multiple)
Use jargon without explanation

Good example:

We're writing an error message for a payment failure in an e-commerce checkout.
The user's credit card was declined. Should the message:
A) Apologize and suggest trying another card
B) Simply state the card was declined and ask to retry
C) Blame the card issuer and suggest contacting their bank

Bad example:

Should we apologize?

推荐做法：

在问题本身中包含所有必要的上下文
尽可能使用多选题（回复更快，数据更清晰）
明确说明你要决策的内容

不推荐做法：

假设回答者知道你的项目/上下文
提出复合问题（拆分为多个问题）
使用未解释的行话

正面示例：

我们正在为电商结账流程的支付失败场景编写错误消息。用户的信用卡被拒了。消息应该：
A) 致歉并建议尝试其他卡片
B) 仅说明卡片被拒并请重试
C) 归咎于发卡行并建议联系银行

反面示例：

我们应该致歉吗？

Environment Setup

环境配置

This skill requires the

ASK_A_HUMAN_AGENT_ID

environment variable. Get your agent ID by signing up at https://app.ask-a-human.com.

本技能需要

ASK_A_HUMAN_AGENT_ID

环境变量。你可以通过访问https://app.ask-a-human.com 注册获取你的agent ID。

Rate Limits

速率限制

Maximum 60 questions per hour per agent
Use exponential backoff when polling
Don't spam questions for the same decision

每个agent每小时最多提交60个问题
轮询时使用指数退避
不要为同一个决策重复提交问题

Quick Reference

快速参考

Action	Command
Submit question	`POST /agent/questions` with prompt, type, options
Check responses	`GET /agent/questions/{question_id}`
Required header	`X-Agent-ID: $ASK_A_HUMAN_AGENT_ID`

Status	Meaning
OPEN	Waiting, no responses yet
PARTIAL	Some responses, still collecting
CLOSED	All responses received
EXPIRED	Timeout, question closed

操作	命令
提交问题	`POST /agent/questions` 附带prompt、type、options
查询回复	`GET /agent/questions/{question_id}`
必需请求头	`X-Agent-ID: $ASK_A_HUMAN_AGENT_ID`

状态	含义
OPEN	等待中，尚未收到回复
PARTIAL	部分回复，仍在收集中
CLOSED	已收到所有回复
EXPIRED	超时，问题已关闭