AI Agent-Readable GIFs — Machine Layer Documentation

问题

GIF 图片对 AI 代理来说是不透明的。当 README 包含终端演示 GIF 时，AI 代理看到的只是二进制像素数据——它无法提取命令、理解输出或引用具体步骤。这是基于图片的文档的根本局限。

AgentGIF 通过为每个 GIF 附加结构化的机器可读数据来解决这个问题。

双层架构

AgentGIF 上的每个 GIF 在同一 URL 下共存两个层：

人类看到的是动画终端。AI 代理看到的是结构化数据：命令、输出、时间戳、元数据和嵌入代码。

Cast 文件（Asciinema v2）

The cast file is the richest data source. It's an asciinema v2 recording with precise timestamps for every terminal event.

访问 Cast

curl -s https://agentgif.com/api/v1/gifs/{id}/cast/

Cast 文件结构

第 1 行是包含终端元数据的 JSON 头：

{"version": 2, "width": 120, "height": 40, "timestamp": 1710000000, "env": {"SHELL": "/bin/zsh", "TERM": "xterm-256color"}}

后续行是事件元组：

[0.0, "o", "$ "]
[0.5, "o", "docker compose up -d\r\n"]
[1.2, "o", "\u001b[32mCreating network...\u001b[0m\r\n"]
[2.8, "o", "Container app-1  Started\r\n"]

每个元组的格式为 [时间戳（秒）, 事件类型, 数据]：

• "o" — output event (text written to the terminal screen)
• "i" — input event (user keystrokes, if captured)
• 时间戳以录制开始为起点，单位为秒
• 数据可能包含用于颜色显示的 ANSI 转义码

解析 Cast 文件

import json

# Read cast file
lines = cast_data.strip().split("\n")
header = json.loads(lines[0])
events = [json.loads(line) for line in lines[1:]]

# Extract all output text
output = "".join(data for ts, typ, data in events if typ == "o")

# Find commands (lines starting with $ or % prompt)
commands = [line for line in output.split("\n") if line.startswith("$ ")]

转录文本

对于更简单的用途，transcript 端点返回干净的纯文本：

curl -s https://agentgif.com/api/v1/gifs/{id}/transcript/

脚本记录会去除 ANSI 转义码、合并空白字符，并将终端会话呈现为可读文本。非常适合以下场景：

• 嵌入 LLM 上下文窗口（最少 token 消耗）
• 全文搜索索引
• 从录制会话生成文档
• 跨 GIF 比较终端输出

.md 端点

AgentGIF 上的每个页面都有 Markdown 版本。在任何 URL 后追加 .md：

# GIF detail → structured summary
curl https://agentgif.com/@agentgif/docker-compose/.md

# Tag listing → all GIFs with this tag
curl https://agentgif.com/explore/tags/docker/.md

# Tool page → all GIFs for this CLI tool
curl https://agentgif.com/tools/git/.md

# Collection → ordered GIF list
curl https://agentgif.com/@agentgif/collections/devops-essentials/.md

响应格式为 text/markdown; charset=utf-8——LLM 可以直接解析的干净结构化文本。

JSON API

REST API 提供完整的结构化数据。读取操作无需认证：

# Search for GIFs about a topic
curl -s "https://agentgif.com/api/v1/search/?q=kubernetes" | jq '.results[:3] | .[].title'

# Get full metadata for a specific GIF
curl -s "https://agentgif.com/api/v1/gifs/{id}/" | jq '{title, command, tags, gif_url}'

# Browse by tag
curl -s "https://agentgif.com/api/v1/tags/docker/gifs/" | jq '.count'

See the complete API Reference for all 30+ endpoints.

内容发现

AI 代理可以通过多种渠道发现 AgentGIF 内容：

实际示例

Agent: "Find a Docker demo and explain the steps"

# 1. Search for Docker GIFs
curl -s "https://agentgif.com/api/v1/search/?q=docker+compose" | jq '.results[0].id'
# → "xK9mQ2pL"

# 2. Get the transcript
curl -s "https://agentgif.com/api/v1/gifs/xK9mQ2pL/transcript/"
# → $ docker compose up -d
#   Creating network...
#   Container app-1  Started

# 3. Agent can now explain: "The demo shows docker compose up -d,
#    which starts services in detached mode..."

Agent: "Add a demo GIF to a README"

# 1. Search for the right tool
curl -s "https://agentgif.com/api/v1/search/?q=ripgrep" | jq '.results[0] | {id, gif_url, title}'

# 2. Generate embed code
# → [![ripgrep demo](https://media.agentgif.com/ID.gif)](https://agentgif.com/ID)

Agent: "Compare two terminal tools"

# Get GIFs for both tools
curl -s "https://agentgif.com/api/v1/tags/grep/gifs/" | jq '.results[].command'
curl -s "https://agentgif.com/api/v1/tags/ripgrep/gifs/" | jq '.results[].command'

# Compare the transcripts to understand different syntax