AI Agent-Readable GIFs — Machine Layer Documentation

How AI agents read terminal GIFs through cast files, transcripts, .md endpoints, and structured APIs.

Проблема

GIF-изображения непрозрачны для ИИ-агентов. Когда README содержит терминальный демо-GIF, ИИ-агент видит двоичные пиксельные данные — он не может извлечь команды, понять вывод или сослаться на конкретные шаги. Это фундаментальное ограничение документации на основе изображений.

AgentGIF решает эту проблему, прикрепляя структурированные, машиночитаемые данные к каждому GIF.

Двухуровневая архитектура

Каждый GIF на AgentGIF имеет два уровня, сосуществующих по одному URL:

Уровень	Потребитель	Формат	Доступ
Визуальный	Люди	GIF / MP4	`media.agentgif.com/{id}.gif`
Машиночитаемый	ИИ-агенты	Cast / Transcript / JSON / Markdown	Эндпоинты API + суффикс .md

Человек видит анимированный терминал. ИИ-агент видит структурированные данные: команды, вывод, метки времени, метаданные и коды встраивания.

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 escape-коды для цветов

Разбор 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 escape-коды, сворачивают пробельные символы и представляют терминальный сеанс в виде читаемого текста. Они идеально подходят для:

Встраивания в контекстные окна LLM (минимум токенов)
Индексации для полнотекстового поиска
Генерации документации из записанных сеансов
Сравнения вывода терминала между GIF

.md Эндпоинты

Каждая страница 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 — чистый, структурированный текст, который 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.

Обнаружение контента

ИИ-агенты могут обнаруживать контент AgentGIF через несколько каналов:

Канал	URL	Лучше всего для
llms.txt	`/llms.txt`	Понимания структуры сайта
XML-карта сайта	`/sitemap.xml`	Сканирования всех страниц
RSS/Atom	`/feed/`, `/feed/atom/`	Отслеживания новых GIF
Search API	`/api/v1/search/?q=...`	Поиска конкретного контента
Список тегов	`/api/v1/tags/`	Просмотра по категориям
Индекс инструментов	`/tools/`	Просмотра по CLI-инструменту
Спецификация OpenAPI	`/api/openapi.json`	Понимания схемы API

Примеры из реальной практики

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

← Все руководства · Документация по интеграции агентов →