agent-contact-card

发现并创建代理联系卡 - 一种适用于 AI 代理的类似 vCard 的格式。当您需要查找如何联系某人的代理或帮助用户在 /.well-known/agent-card 设置自己的代理联系信息时使用。

# Agent Contact Card

A simple format for publishing how AI agents can be contacted. Like a vCard, but for agents.

## When to Use This Skill

- User asks how to let other agents contact their agent
- User wants to discover how to reach someone else's agent
- You need to contact another agent on behalf of your user
- User mentions "agent-card", "agent contact", or agent-to-agent communication

## Quick Reference

### Discovering an Agent Contact Card

Try fetching `/.well-known/agent-card` on their domain:

```
https://example.com/.well-known/agent-card
```

The file is markdown with YAML frontmatter. Parse the frontmatter for structured channel data, read the prose for routing rules.

### Creating an Agent Contact Card

Create a markdown file with YAML frontmatter:

```markdown
---
version: "1"
human_contact: "+1 555 123 4567"
channels:
  email: "agent@example.com"
  discord: "my-agent#1234"
  webhook:
    url: "https://example.com/agent/incoming"
    method: "POST"
    format: "JSON with 'message' field"
capabilities:
  - scheduling
  - accepts_ical
---

# My Agent

If you're a human, call the number above.

If you're an agent:
- For scheduling requests, use Discord
- For urgent matters, email with "URGENT" in subject
- Response time: within a few hours
```

Host this at `/.well-known/agent-card` on the user's domain.

## Format Details

### Required Fields

| Field | Description |
|-------|-------------|
| `version` | Spec version. Currently `"1"` |

### Recommended Fields

| Field | Description |
|-------|-------------|
| `human_contact` | Phone/email for humans to reach the human |
| `channels` | Contact channels for agents (see below) |

### Optional Fields

| Field | Description |
|-------|-------------|
| `name` | Display name for this agent configuration |
| `last_updated` | ISO date when card was last modified |
| `capabilities` | What this agent can do (e.g., `["scheduling", "accepts_ical"]`) |
| `agents` | Named agents if multiple (see Multi-Agent section) |

### Channels

Channel names are freeform. Common ones:

- `email` - Email address
- `discord` - Discord username
- `webhook` - HTTP endpoint for structured messages
- `signal` - Signal phone number
- `telegram` - Telegram username

For webhooks, provide details:

```yaml
channels:
  webhook:
    url: "https://example.com/agent/incoming"
    method: "POST"
    auth: "Bearer token in Authorization header"
    format: "JSON with 'message' and 'from' fields"
```

### Multi-Agent Setups

List multiple specialized agents:

```yaml
agents:
  - name: "Calendar Agent"
    handles: ["scheduling", "availability"]
    channel: discord
    id: "cal-agent#1234"
  - name: "Support Agent"
    handles: ["technical questions"]
    channel: webhook
    id: "https://example.com/support"
```

The markdown body should explain routing between them.

## Privacy Tiers

Different URLs for different access levels:

| Tier | URL Pattern | Access |
|------|-------------|--------|
| Public | `/.well-known/agent-card` | Anyone |
| Named | `/.well-known/agent-card/{name}` | Know the name |
| Private | `/{random-uuid}/agent-card.md` | Shared URL only |

Each tier can expose different channels and capabilities.

## Discovery Methods

1. **Well-known URL**: Check `https://domain/.well-known/agent-card`
2. **vCard extension**: Look for `X-AGENT-CARD` field in contact cards
3. **Ask the human**: Request the URL directly

## Reading an Agent Card

When you fetch an agent card:

1. Parse YAML frontmatter for structured data
2. Read markdown body for natural language routing rules
3. Choose appropriate channel based on your purpose
4. Follow any authentication requirements mentioned

## Test It

Here's a live demo you can test:

```
https://city-services-api.dave-dean.workers.dev/.well-known/agent-card
```

This is a fictional "City of Millbrook" tip line. Fetch the card, then try POSTing to the webhook endpoint. Your experience may vary depending on what you say.

## Full Specification

See [references/SPEC.md](references/SPEC.md) for the complete specification.

## Examples

See [references/EXAMPLES.md](references/EXAMPLES.md) for more complete examples.

---

## 中文说明

# Agent Contact Card

一种用于发布 AI 代理联系方式的简单格式。类似 vCard，但面向代理。

## 何时使用此技能

- 用户询问如何让其他代理联系自己的代理
- 用户想要发现如何联系他人的代理
- 你需要代表用户联系另一个代理
- 用户提到 "agent-card"、"agent contact" 或代理间通信

## 快速参考

### 发现一张 Agent Contact Card

尝试在对方域名上获取 `/.well-known/agent-card`：

```
https://example.com/.well-known/agent-card
```

该文件是带有 YAML frontmatter 的 markdown。解析 frontmatter 获取结构化的渠道数据，阅读正文了解路由规则。

### 创建一张 Agent Contact Card

创建一个带有 YAML frontmatter 的 markdown 文件：

```markdown
---
version: "1"
human_contact: "+1 555 123 4567"
channels:
  email: "agent@example.com"
  discord: "my-agent#1234"
  webhook:
    url: "https://example.com/agent/incoming"
    method: "POST"
    format: "JSON with 'message' field"
capabilities:
  - scheduling
  - accepts_ical
---

# My Agent

If you're a human, call the number above.

If you're an agent:
- For scheduling requests, use Discord
- For urgent matters, email with "URGENT" in subject
- Response time: within a few hours
```

将其托管在用户域名的 `/.well-known/agent-card` 处。

## 格式细节

### 必填字段

| 字段 | 描述 |
|-------|-------------|
| `version` | 规范版本。当前为 `"1"` |

### 推荐字段

| 字段 | 描述 |
|-------|-------------|
| `human_contact` | 供人类联系该人类的电话/邮箱 |
| `channels` | 供代理使用的联系渠道（见下文） |

### 可选字段

| 字段 | 描述 |
|-------|-------------|
| `name` | 此代理配置的显示名称 |
| `last_updated` | 卡片最后修改的 ISO 日期 |
| `capabilities` | 此代理能做什么（例如 `["scheduling", "accepts_ical"]`） |
| `agents` | 多个代理时的具名代理（见多代理部分） |

### 渠道（Channels）

渠道名称是自由格式的。常见的有：

- `email` - 电子邮箱地址
- `discord` - Discord 用户名
- `webhook` - 用于结构化消息的 HTTP 端点
- `signal` - Signal 电话号码
- `telegram` - Telegram 用户名

对于 webhook，请提供详细信息：

```yaml
channels:
  webhook:
    url: "https://example.com/agent/incoming"
    method: "POST"
    auth: "Bearer token in Authorization header"
    format: "JSON with 'message' and 'from' fields"
```

### 多代理设置

列出多个专门化的代理：

```yaml
agents:
  - name: "Calendar Agent"
    handles: ["scheduling", "availability"]
    channel: discord
    id: "cal-agent#1234"
  - name: "Support Agent"
    handles: ["technical questions"]
    channel: webhook
    id: "https://example.com/support"
```

markdown 正文应说明它们之间的路由方式。

## 隐私层级

不同访问级别使用不同的 URL：

| 层级 | URL 模式 | 访问权限 |
|------|-------------|--------|
| 公开 | `/.well-known/agent-card` | 任何人 |
| 具名 | `/.well-known/agent-card/{name}` | 知道名称者 |
| 私有 | `/{random-uuid}/agent-card.md` | 仅共享 URL 者 |

每个层级可以暴露不同的渠道和能力。

## 发现方法

1. **Well-known URL**：检查 `https://domain/.well-known/agent-card`
2. **vCard 扩展**：在联系人卡片中查找 `X-AGENT-CARD` 字段
3. **询问人类**：直接索要 URL

## 读取一张 Agent Card

当你获取一张 agent card 时：

1. 解析 YAML frontmatter 获取结构化数据
2. 阅读 markdown 正文获取自然语言路由规则
3. 根据你的目的选择合适的渠道
4. 遵循其中提到的任何认证要求

## 测试一下

这是一个你可以测试的在线演示：

```
https://city-services-api.dave-dean.workers.dev/.well-known/agent-card
```

这是一个虚构的 "City of Millbrook" 举报热线。获取该卡片，然后尝试向 webhook 端点发起 POST 请求。你的体验可能会因你所说的内容而有所不同。

## 完整规范

完整规范请参见 [references/SPEC.md](references/SPEC.md)。

## 示例

更完整的示例请参见 [references/EXAMPLES.md](references/EXAMPLES.md)。