AI Agent-Readable GIFs — Machine Layer Documentation

Vấn đề

Hình ảnh GIF không trong suốt với tác nhân AI. Khi README chứa GIF demo terminal, tác nhân AI chỉ thấy dữ liệu pixel nhị phân — không thể trích xuất lệnh, hiểu đầu ra hay tham chiếu các bước cụ thể. Đây là giới hạn cơ bản của tài liệu dựa trên hình ảnh.

AgentGIF giải quyết vấn đề này bằng cách đính kèm dữ liệu có cấu trúc, có thể đọc bằng máy vào mỗi GIF.

Kiến trúc hai lớp

Mỗi GIF trên AgentGIF có hai lớp cùng tồn tại tại cùng một URL:

Con người thấy terminal hoạt hình. Tác nhân AI thấy dữ liệu có cấu trúc: lệnh, đầu ra, dấu thời gian, metadata và mã nhúng.

Tệp Cast (Asciinema v2)

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

Truy cập Cast

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

Cấu trúc tệp Cast

Dòng 1 là header JSON với metadata terminal:

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

Các dòng tiếp theo là các tuple sự kiện:

[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"]

Mỗi tuple là [timestamp_seconds, event_type, data]:

• "o" — output event (text written to the terminal screen)
• "i" — input event (user keystrokes, if captured)
• Dấu thời gian tính bằng giây từ khi bắt đầu ghi
• Dữ liệu có thể chứa mã escape ANSI cho màu sắc

Phân tích tệp 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("$ ")]

Bản ghi chép

Đối với các trường hợp sử dụng đơn giản hơn, endpoint bản ghi chép trả về văn bản thuần sạch:

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

Bản ghi chép loại bỏ mã escape ANSI, thu gọn khoảng trắng và trình bày phiên terminal dưới dạng văn bản có thể đọc. Chúng lý tưởng cho:

• Nhúng vào cửa sổ ngữ cảnh LLM (tối thiểu token)
• Lập chỉ mục tìm kiếm toàn văn
• Tạo tài liệu từ các phiên đã ghi
• So sánh đầu ra terminal trên các GIF

Endpoint .md

Mỗi trang trên AgentGIF đều có biến thể Markdown. Thêm .md vào bất kỳ URL nào:

# 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

Phản hồi là text/markdown; charset=utf-8 — văn bản sạch, có cấu trúc mà LLM có thể phân tích trực tiếp.

JSON API

REST API cung cấp dữ liệu có cấu trúc đầy đủ. Không cần xác thực để đọc:

# 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.

Khám phá nội dung

Tác nhân AI có thể khám phá nội dung AgentGIF qua nhiều kênh:

Ví dụ thực tế

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