AI Agent-Readable GIFs — Machine Layer Documentation

ปัญหา

ภาพ GIF ทึบแสงต่อ AI agents เมื่อ README มี terminal demo GIF AI agent จะเห็นข้อมูลพิกเซลแบบ binary — ไม่สามารถดึงคำสั่ง เข้าใจผลลัพธ์ หรืออ้างอิงขั้นตอนเฉพาะ นี่คือข้อจำกัดพื้นฐานของเอกสารที่ใช้รูปภาพ

AgentGIF แก้ปัญหานี้โดยแนบข้อมูลที่มีโครงสร้างและเครื่องอ่านได้กับ GIF ทุกไฟล์

สถาปัตยกรรมสองชั้น

GIF ทุกไฟล์บน AgentGIF มีสองชั้นที่อยู่ร่วมกันที่ URL เดียวกัน:

มนุษย์เห็น terminal เคลื่อนไหว AI agent เห็นข้อมูลที่มีโครงสร้าง: คำสั่ง ผลลัพธ์ timestamps metadata และ embed codes

ไฟล์ 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 header พร้อม metadata ของ terminal:

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

บรรทัดต่อไปคือ event tuples:

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

แต่ละ tuple คือ [timestamp_seconds, event_type, data]:

• "o" — output event (text written to the terminal screen)
• "i" — input event (user keystrokes, if captured)
• Timestamps เป็นวินาทีจากจุดเริ่มต้นการบันทึก
• ข้อมูลอาจมี ANSI escape codes สำหรับสี

การวิเคราะห์ไฟล์ 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("$ ")]

Transcripts

สำหรับกรณีการใช้งานที่ง่ายกว่า endpoint ของ transcript คืนข้อความธรรมดาที่สะอาด:

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

Transcripts ลบ ANSI escape codes ย่อ whitespace และนำเสนอ terminal session เป็นข้อความที่อ่านได้ เหมาะสำหรับ:

• การฝังใน context windows ของ LLM (tokens น้อยที่สุด)
• การทำดัชนีค้นหาเต็มรูปแบบ
• การสร้างเอกสารจาก sessions ที่บันทึกไว้
• การเปรียบเทียบ terminal output ระหว่าง GIFs

.md Endpoints

ทุกหน้าบน AgentGIF มีตัวแปรแบบ Markdown เพิ่ม .md ต่อท้าย URL ใดก็ได้:

# 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 — ข้อความที่สะอาดและมีโครงสร้างซึ่ง LLMs สามารถวิเคราะห์โดยตรง

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 agents สามารถค้นพบเนื้อหา 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