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

각 튜플은 [timestamp_seconds, event_type, data]입니다:

• "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("$ ")]

전사본

더 단순한 사용 사례를 위해 전사본 엔드포인트는 깔끔한 일반 텍스트를 반환합니다:

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

전사본은 ANSI 이스케이프 코드를 제거하고, 공백을 축소하며, 터미널 세션을 읽기 쉬운 텍스트로 표시합니다. 다음에 이상적입니다:

• LLM 컨텍스트 윈도우에 임베딩 (최소 토큰)
• 전문 검색 인덱싱
• 녹화된 세션으로 문서 생성
• 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