1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

graph LR
    A[에이전트 작업 시작] --> B[검색 API 호출]
    B --> C[후보 문서 URL 리스트 확보]
    C --> D[HTTP GET - Raw 텍스트]
    D --> E[토큰 카운트 계산]
    E --> F[컨텍스트 윈도우 초과?]
    F -->|Yes| G[문서 폐기]
    F -->|No| H[RAG 청크 분할]
    H --> I[임베딩 및 검색]
    I --> J[컨텍스트 윈도우에 삽입]
    J --> K[LLM 응답 생성]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# AI 에이전트의 내부 의사결정 과정 (의사코드)
def should_consume_document(url: str, context_budget: int) -> bool:
    """
    에이전트가 문서를 컨텍스트에 포함할지 결정하는 로직
    """
    # 1. HTTP 요청으로 raw 텍스트 가져오기
    raw_text = http_get(url)
    
    # 2. HTML → 마크다운/텍스트 변환
    clean_text = html_to_markdown(raw_text)
    
    # 3. 토큰 수 계산
    token_count = count_tokens(clean_text, model="gpt-4o")
    
    # 4. 현재 컨텍스트 예산 확인
    remaining_budget = context_budget - token_count
    
    # 5. 예산이 부족하면 조용히 폐기
    if remaining_budget < SAFETY_MARGIN:
        # 로그도 없이, 에러도 없이 그냥 스킵
        return False
    
    return True

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 나쁜 예: 하나의 긴 페이지
## API Reference
... (50,000 토큰의 내용이 연속적으로 배치)

# 좋은 예: 모듈식 구조
## API Reference Overview (500 토큰)
- 핵심 개념 요약
- 모듈별 링크

## Authentication Module (2,000 토큰)
- 별도 엔드포인트

## User Management Module (3,000 토큰)
- 별도 엔드포인트

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<!-- 기존 SEO 메타데이터 -->
<meta name="description" content="API documentation for developers">
<meta name="keywords" content="API, REST, documentation">

<!-- AEO 메타데이터 추가 -->
<meta name="x-ai-tokens" content="2500">
<meta name="x-ai-language" content="python">
<meta name="x-ai-complexity" content="intermediate">
<meta name="x-ai-updated" content="2024-12-01">
<link rel="ai-index" href="/api/ai-index.json">

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

{
  "schema_version": "1.0",
  "documentation": {
    "total_modules": 5,
    "estimated_tokens": 12000,
    "modules": [
      {
        "name": "authentication",
        "url": "/api/docs/auth.md",
        "tokens": 1500,
        "keywords": ["OAuth", "JWT", "API key"],
        "complexity": "beginner"
      },
      {
        "name": "users",
        "url": "/api/docs/users.md",
        "tokens": 2800,
        "keywords": ["CRUD", "pagination", "filtering"],
        "complexity": "intermediate"
      }
    ]
  },
  "quick_start": {
    "url": "/api/docs/quickstart.md",
    "tokens": 800,
    "language_examples": ["python", "javascript", "curl"]
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

# 토큰 효율성 검증 도구
import tiktoken

def analyze_document_efficiency(filepath: str) -> dict:
    """
    문서의 토큰 효율성을 분석합니다.
    """
    with open(filepath, 'r') as f:
        content = f.read()
    
    # 토크나이저 초기화
    encoding = tiktoken.encoding_for_model("gpt-4o")
    tokens = encoding.encode(content)
    token_count = len(tokens)
    
    # 정보 밀도 계산 (코드 블록, 예제 포함)
    code_blocks = content.count('```')
    api_endpoints = content.count('GET') + content.count('POST') + \
                    content.count('PUT') + content.count('DELETE')
    
    efficiency_score = (api_endpoints * 50 + code_blocks * 20) / token_count
    
    return {
        "token_count": token_count,
        "efficiency_score": round(efficiency_score, 4),
        "recommendation": "split" if token_count > 4000 else "optimal",
        "code_blocks": code_blocks // 2,
        "api_endpoints": api_endpoints
    }

# 실행 예시
result = analyze_document_efficiency("api_docs.md")
print(f"토큰 수: {result['token_count']}")
print(f"효율성 점수: {result['efficiency_score']}")
print(f"권장 사항: {result['recommendation']}")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "name": "User API Documentation",
  "description": "RESTful API for user management",
  "programmingLanguage": "Python",
  "codeSampleType": "API",
  "hasPart": [
    {
      "@type": "HowTo",
      "name": "Create User",
      "step": [
        {
          "@type": "HowToStep",
          "text": "POST /api/v1/users with JSON body"
        }
      ]
    }
  ]
}
</script>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

## AEO 문서 최적화 체크리스트

### 구조 최적화
- [ ] 각 섹션이 4,000 토큰 이하인가?
- [ ] 모듈별로 독립 접근 가능한가?
- [ ] 계층 구조가 명확한가?

### 메타데이터
- [ ] AI 인덱스 파일이 있는가?
- [ ] 각 문서의 토큰 수가 명시되었는가?
- [ ] 구조화된 데이터 마크업이 포함되었는가?

### 내용 최적화
- [ ] 코드 예제가 실행 가능한가?
- [ ] API 엔드포인트가 명확히 표시되었는가?
- [ ] 불필요한 장식적 텍스트가 제거되었는가?

### 추적 및 분석
- [ ] 서버 로그에 User-Agent별 접근 기록이 있는가?
- [ ] AI 에이전트 트래픽을 식별할 수 있는가?
- [ ] 문서별 API 호출 빈도를 모니터링하는가?

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

from fastapi import FastAPI, Request, Response
from starlette.middleware.base import BaseHTTPMiddleware
import time
import json

app = FastAPI()

class AIAgentDetectionMiddleware(BaseHTTPMiddleware):
    """
    AI 에이전트의 트래픽을 감지하고 로깅하는 미들웨어
    """
    
    KNOWN_AI_AGENTS = [
        "cursor", "github-copilot", "deeplearning-ai",
        "openai", "anthropic", "google-ai"
    ]
    
    async def dispatch(self, request: Request, call_next):
        start_time = time.time()
        
        # 응답 처리
        response = await call_next(request)
        
        # 처리 시간 계산
        process_time = (time.time() - start_time) * 1000
        
        # AI 에이전트 감지
        user_agent = request.headers.get("user-agent", "").lower()
        is_ai_agent = any(
            agent in user_agent for agent in self.KNOWN_AI_AGENTS
        )
        
        # HTTP 클라이언트 패턴 감지
        # (에이전트는 보통 python-requests, httpx 등 사용)
        http_client_patterns = [
            "python-requests", "httpx", "aiohttp", "node-fetch"
        ]
        is_automated = any(
            pattern in user_agent for pattern in http_client_patterns
        )
        
        # AI 트래픽 로깅
        if is_ai_agent or is_automated:
            log_entry = {
                "timestamp": time.strftime("%Y-%m-%d %H:%M:%S"),
                "path": str(request.url.path),
                "method": request.method,
                "user_agent": user_agent,
                "process_time_ms": round(process_time, 2),
                "is_ai_agent": is_ai_agent,
                "is_automated": is_automated
            }
            
            # 별도 로그 파일에 기록
            with open("ai_traffic.log", "a") as f:
                f.write(json.dumps(log_entry) + "
")
            
            # 응답 헤더에 AI 최적화 정보 추가
            if is_ai_agent:
                response.headers["X-AI-Optimized"] =