# Aither

> An AI-native Astro theme that believes text itself is beautiful.

---

## ✨ Astro-Theme-Aither를 선택한 이유

URL: https://astro-theme-aither.pages.dev/ko/posts/why-astro-theme-aither/
Date: 2026-01-03
Category: Design
Tags: Design, Astro
Description: 텍스트 자체가 아름답다고 믿는 AI 네이티브 Astro 테마.

텍스트 자체가 아름답다고 믿는 AI 네이티브 Astro 테마. Astro-Theme-Aither는 장식이 아닌 글을 위해 찾아오는 독자를 위해 만들어졌습니다.

## 디자인 철학

대부분의 블로그 테마는 히어로 이미지, 애니메이션, 사이드바, 팝업으로 시선을 끌려 합니다. 이런 것들은 읽기에 도움이 되지 않습니다 — 보기에 도움이 될 뿐이고, 그것은 완전히 다른 활동입니다.

Astro-Theme-Aither는 정반대의 접근을 취합니다: 미니멀한 디자인이지, 미니멀한 엔지니어링이 아닙니다. 문제를 가려줄 화려한 비주얼이 없으면 모든 타이포그래피 결함, 모든 로딩 지연, 모든 인터랙션 끊김이 증폭됩니다. 미니멀한 디자인은 더 낮은 것이 아닌 더 높은 엔지니어링 품질을 요구합니다.

## 타이포그래피

서체가 곧 시각적 아이덴티티입니다. 모든 페이지는 통합된 산세리프 시스템 폰트 스택을 사용합니다 — 깔끔하고, 빠르고, 플랫폼 간 일관적입니다. 타이포그래피 파라미터는 Apple Human Interface Guidelines를 따릅니다:

- **폰트 크기** — 17px 기본, 편안한 화면 읽기를 위한 최적점
- **행 높이** — 1.47, 읽기 흐름을 깨지 않으면서 각 줄에 여유를 줌
- **자간** — -0.022em, 본문 텍스트를 세련되게 만드는 미묘한 조임
- **제목 스케일** — 31px → 22px → 19px → 17px, 크기 극단 없이 명확한 계층
- **읽기 너비** — 줄당 65~75자로 제한, 눈이 가장 편안하게 추적하는 범위

이것들은 수십 년간의 화면 가독성 연구와 Apple 타이포그래피 표준에서 도출된 근거 기반 실천입니다.

## Astro 기반

Astro는 오늘날 콘텐츠 중심 사이트에 가장 적합한 프레임워크입니다. 기본적으로 정적 HTML을 출력합니다 — 명시적으로 선택하지 않는 한 클라이언트 사이드 JavaScript가 없습니다. 아일랜드 아키텍처는 인터랙티브 컴포넌트가 독립적으로 하이드레이트되고 나머지 페이지는 정적으로 유지됩니다.

Astro-Theme-Aither에서 인터랙티브 아일랜드는 최소화되어 있습니다:

- **테마 전환기** — View Transitions API 원형 공개 애니메이션을 사용한 라이트 / 다크 / 시스템 토글
- **언어 전환기** — localStorage 지속성을 가진 매끄러운 로케일 전환
- **로케일 감지** — 브라우저 언어를 자동 감지하고 전환을 제안
- **모바일 네비게이션** — 반응형 햄버거 메뉴

나머지는 모두 순수 HTML과 CSS로, 즉시 로드됩니다.

## 기능

- **Tailwind CSS v4** — 전체 라이트/다크 팔레트 커스터마이징이 가능한 `@theme` 디자인 토큰
- **Apple HIG 타이포그래피** — 17px / 1.47 / -0.022em 본문 텍스트 파라미터
- **View Transitions API** — 테마 전환을 위한 원형 공개 애니메이션
- **i18n** — 자동 브라우저 언어 감지를 포함한 다국어 지원
- **글 고정** — 중요한 글을 목록 상단에 고정
- **Content Collections** — 빌드 타임 프런트매터 유효성 검사를 포함한 타입 안전 Markdown
- **다크 모드** — localStorage 지속성을 가진 라이트 / 다크 / 시스템
- **SEO** — Open Graph, 정규 URL, 글별 메타 설명
- **RSS + 사이트맵** — 자동 생성, 설정 불필요
- **Google Analytics** — 선택 사항, Partytown Web Worker에서 실행
- **테스트** — Vitest 유닛 테스트 + Playwright E2E, CI에 통합
- **Cloudflare Pages** — PR 미리보기 URL이 포함된 배포 워크플로우

## 누구를 위한 것인가

좋은 글이 스스로 말하고 그 믿음을 존중하는 테마를 원한다면:

- **개인 블로거** — 글이 전면에 나오길 원하는 분
- **기술 작가** — 훌륭한 코드 블록 렌더링과 명확한 산문 서식이 필요한 분
- **다국어 저자** — 자동 브라우저 언어 감지가 포함된 내장 i18n이 필요한 분
- **개발자** — 자신 있게 확장할 수 있는 잘 엔지니어링된 코드베이스를 좋아하는 분

무엇이든 쓰세요 — 타이포그래피가 멋지게 만들어줄 것입니다.

---

## 📝 Markdown 스타일 가이드

URL: https://astro-theme-aither.pages.dev/ko/posts/markdown-guide/
Date: 2026-01-02
Category: Tutorial
Tags: Markdown, Guide
Description: Astro-Theme-Aither에서 지원하는 모든 Markdown 기능에 대한 종합 가이드

이 글은 Astro-Theme-Aither가 지원하는 모든 Markdown 기능을 보여줍니다. 글을 작성할 때 참고 자료로 활용하세요. 이 페이지를 북마크하세요 — 사용 가능한 모든 서식 옵션을 다룹니다.

## 제목

섹션 제목에는 `##`을, 하위 섹션에는 `###`을, 하위의 하위 섹션에는 `####`을 사용하세요. 글 내용에서는 `#`을 피하세요 — 글 제목이 이미 최상위 제목으로 렌더링됩니다.

### 3단계 제목

3단계 제목은 섹션을 뚜렷한 주제로 나누는 데 적합합니다. 너무 눈에 띄지 않으면서 시각적 계층을 만들어줍니다.

#### 4단계 제목

4단계 제목은 세부적인 하위 섹션에 적합합니다. 드물게 사용하세요 — 개요가 4단계보다 깊어진다면 콘텐츠 구조를 재검토하는 것이 좋습니다.

### 제목 모범 사례

효과적인 제목 사용을 위한 몇 가지 지침:

- **단계를 건너뛰지 마세요** — `##`에서 `###`으로, 절대 `##`에서 바로 `####`로 가지 마세요. 단계를 건너뛰면 문서 개요가 깨지고 스크린 리더를 혼란스럽게 할 수 있습니다.
- **제목을 설명적으로 유지하세요** — "설정 관련"보다 "환경 설정"이 좋습니다. 독자들은 섹션을 읽을지 결정하기 전에 제목을 훑어봅니다.
- **문장 표기법을 사용하세요** — 첫 단어와 고유명사만 대문자로 씁니다.

## 단락과 줄 바꿈

일반 단락 텍스트는 자연스럽게 흐릅니다. 단락을 구분하려면 빈 줄을 남기세요.

이것은 두 번째 단락입니다. 최상의 읽기 경험을 위해 단락은 하나의 아이디어에 집중하세요.

웹 글쓰기에서는 짧은 단락이 긴 텍스트 블록보다 잘 작동합니다. 화면에서 편안하게 읽을 수 있는 단위는 3~5문장입니다. 6~7문장을 넘어가면 분리를 고려하세요.

단락 내에서의 단일 줄 바꿈(빈 줄 없이)은 새 줄이 아닌 공백으로 처리됩니다. 새 단락 없이 강제 줄 바꿈이 필요하면 줄 끝에 공백 두 개를 넣거나 `<br>` 태그를 사용하세요 — 실제로는 거의 필요하지 않습니다.

## 강조

- **굵은 텍스트** `**이중 별표**`로 표시
- *기울임 텍스트* `*단일 별표*`로 표시
- ***굵은 기울임*** `***삼중 별표***`로 표시
- ~~취소선~~ `~~이중 물결표~~`로 표시

### 각 스타일 사용 시점

**굵게**는 핵심 용어, 중요한 경고, 정의 등 — 훑어봐도 놓치면 안 되는 것에 적합합니다. 단락에서 가장 중요한 문구에 사용하고, 전체 문장에는 사용하지 마세요.

*기울임*은 문장 내 강조, 책 및 출판물 제목, 처음 사용하는 기술 용어, 외국어 표현에 적합합니다. 굵게보다 부드러운 강조를 제공합니다.

~~취소선~~은 수정 사항, 더 이상 사용되지 않는 정보, 변경 로그의 완료 항목 표시에 유용합니다. 사용 범위는 좁지만 필요할 때 가치 있습니다.

## 링크

[인라인 링크](https://astro.build) `[텍스트](url)` 구문으로 작성합니다.

링크는 상대 경로를 사용하여 사이트의 다른 글을 참조할 수도 있습니다. 설명적인 링크 텍스트를 사용하세요 — "여기를 클릭하세요"보다 "마크다운 가이드를 읽어보세요"가 좋습니다. 좋은 링크 텍스트는 독자와 검색 엔진 모두 링크 목적지를 이해하는 데 도움이 됩니다.

문장 내에서 자연스럽게 읽히는 설명적 앵커 텍스트를 작성할 수도 있습니다. 예를 들어: [Astro 공식 문서](https://docs.astro.build)에서 모든 기능을 자세히 다룹니다.

## 목록

비순서 목록:

- 첫 번째 항목
- 두 번째 항목
  - 중첩 항목
  - 또 다른 중첩 항목
- 세 번째 항목

순서 목록:

1. 첫 번째 단계
2. 두 번째 단계
   1. 하위 단계 1
   2. 하위 단계 2
3. 세 번째 단계

작업 목록:

- [x] 프로젝트 설정
- [x] 첫 번째 글 작성
- [ ] 프로덕션 배포

### 목록 서식 팁

목록은 웹 글쓰기에서 가장 효과적인 도구 중 하나입니다. 밀도 높은 텍스트를 나누고, 정보를 훑어볼 수 있게 만들며, 순서나 항목 모음을 명확히 전달합니다.

**비순서 목록은** 항목에 순서가 없을 때 사용하세요 — 기능, 요구사항, 옵션, 예시.

**순서 목록은** 순서가 중요할 때 사용하세요 — 프로세스 단계, 순위, 순서대로 따라야 하는 지침.

**작업 목록은** 진행 상황 추적, 프로젝트 체크리스트, 할 일 항목에 사용하세요. 많은 Markdown 뷰어에서 인터랙티브 체크박스로 렌더링되지만, 정적 블로그에서는 시각적 지표로 나타납니다.

목록 항목의 구조를 일관되게 유지하세요. 첫 번째 항목이 동사로 시작하면 모든 항목이 동사로 시작해야 합니다. 첫 번째 항목이 명사구이면 그 패턴을 유지하세요.

## 인용문

> 추상화의 목적은 모호해지는 것이 아니라, 절대적으로 정확할 수 있는 새로운 의미 수준을 만드는 것이다.
>
> — Edsger W. Dijkstra

중첩 인용문:

> 첫 번째 단계
>
> > 두 번째 단계
> >
> > > 세 번째 단계

### 인용문 사용법

인용문은 유명인의 말을 인용하는 것 외에도 여러 목적으로 사용됩니다:

- **출처 인용** — 다른 기사, 책, 문서를 참조할 때
- **콜아웃** — 중요한 정보나 경고를 강조할 때
- **이메일 스타일 인용** — 응답하는 대화에서 상대방이 한 말을 표시할 때
- **풀 인용** — 자신의 글에서 핵심 구절에 주의를 끌 때

인용문에 저자를 표기할 때는 위의 Dijkstra 예시처럼 별도의 줄에 엠 대시를 붙여 표기하세요.

## 코드

백틱으로 인라인 `코드`를 표시합니다. `getPublishedPosts()` 같은 함수 이름, `src/content/posts/` 같은 파일 경로, `pnpm dev` 같은 명령줄 지시, 본문 중에 나타나는 리터럴 값에 인라인 코드를 사용하세요.

구문 하이라이팅이 적용된 코드 블록:

```typescript
interface Post {
  title: string;
  date: Date;
  description?: string;
  tags?: string[];
  draft?: boolean;
}

function getPublishedPosts(posts: Post[]): Post[] {
  return posts
    .filter((post) => !post.draft)
    .sort((a, b) => b.date.getTime() - a.date.getTime());
}
```

```css
@theme {
  --font-sans: 'system-ui', sans-serif;
  --font-serif: 'ui-serif', 'Georgia', serif;
}
```

### 코드 블록 팁

여는 삼중 백틱 뒤에 항상 언어 식별자를 지정하세요. 구문 하이라이팅이 활성화되어 가독성이 크게 향상됩니다. 일반적인 식별자로는 `typescript`, `javascript`, `css`, `html`, `bash`, `json`, `python`, `markdown`이 있습니다.

셸 명령에는 `bash` 또는 `sh`를 사용하세요:

```bash
# 의존성 설치
pnpm install

# 개발 서버 시작
pnpm dev

# 프로덕션 빌드
pnpm build
```

JSON 설정 파일:

```json
{
  "name": "my-blog",
  "version": "1.0.0",
  "scripts": {
    "dev": "astro dev",
    "build": "astro build"
  }
}
```

코드 블록은 집중적으로 유지하세요. 전체 파일을 붙여넣기보다 관련 줄만 보여주세요. 컨텍스트가 필요하면 코드가 어디에 있는지 주석을 추가하세요.

## 표

| 기능 | 상태 | 비고 |
|---|---|---|
| 다크 모드 | 지원 | 라이트 / 다크 / 시스템 |
| RSS 피드 | 내장 | `/rss.xml` |
| 사이트맵 | 자동 생성 | `@astrojs/sitemap` |
| SEO | 내장 | Open Graph + 정규 URL |

오른쪽 정렬 및 가운데 정렬 열:

| 왼쪽 | 가운데 | 오른쪽 |
|:---|:---:|---:|
| 텍스트 | 텍스트 | 텍스트 |
| 긴 텍스트 | 긴 텍스트 | 긴 텍스트 |

### 표 가이드라인

표는 명확한 열과 행이 있는 구조화된 데이터에 적합합니다. 기능 비교, 설정 옵션, API 매개변수, 참조 데이터에 이상적입니다.

표를 단순하게 유지하세요. 5~6개 이상의 열이 있는 표는 모바일 기기에서 읽기 어렵습니다. 복잡한 표는 여러 개의 작은 표로 나누거나 대신 목록 형식을 사용하세요.

열 정렬은 구분자 행의 콜론으로 제어합니다:

- `:---` 왼쪽 정렬 (기본)
- `:---:` 가운데 정렬
- `---:` 오른쪽 정렬

숫자 데이터에는 소수점이 시각적으로 정렬되도록 오른쪽 정렬을 사용하세요.

## 수평선

`---`를 사용하여 수평선을 만듭니다:

---

수평선 이후의 콘텐츠.

수평선은 글의 주요 섹션을 구분하거나, 주제 전환을 나타내거나, 매우 긴 글을 시각적으로 나누는 데 유용합니다. 적절히 사용하세요 — 빈번한 구분이 필요하다면 제목이 더 나은 구조적 선택일 수 있습니다.

## 이미지

이미지는 표준 Markdown 구문으로 지원됩니다:

```markdown
![대체 텍스트](./image.jpg)
```

이 테마는 타이포그래피 중심이지만, 필요할 때 이미지도 잘 동작합니다.

### 이미지 모범 사례

- **항상 대체 텍스트를 포함하세요** — 접근성에 필수적이며 이미지 로드 실패 시에도 나타납니다
- **설명적인 파일 이름을 사용하세요** — `screenshot-2.png`보다 `dashboard-error-state.png`이 좋습니다
- **파일 크기를 최적화하세요** — 저장소에 추가하기 전에 이미지를 압축하세요; 큰 이미지는 페이지 로드를 느리게 합니다
- **읽기 흐름을 고려하세요** — 이미지를 참조하는 텍스트 근처에 배치하세요, 여러 단락 떨어진 곳이 아니라

## 마무리

이 가이드에 설명된 Markdown 기능은 블로그 글쓰기에 필요한 대부분을 다룹니다. 좋은 Markdown의 핵심은 올바른 목적에 올바른 요소를 사용하는 것입니다: 구조를 위한 제목, 중요도를 위한 강조, 모음을 위한 목록, 기술 콘텐츠를 위한 코드 블록, 나머지를 위한 단락.

명확하게 쓰고, 일관되게 서식을 지정하고, 타이포그래피가 일하게 하세요.

---

## 👋 Hello World

URL: https://astro-theme-aither.pages.dev/ko/posts/hello-world/
Date: 2026-01-01
Category: Tutorial
Tags: Hello, Astro
Description: Astro-Theme-Aither에 오신 것을 환영합니다 — 타이포그래피가 디자인을 이끄는 블로그 테마

Astro-Theme-Aither에 오신 것을 환영합니다.

이것은 하나의 믿음 위에 만들어진 블로그 테마입니다: 좋은 글은 좋은 타이포그래피를 누릴 자격이 있다. 세리프 제목, 깔끔한 읽기 리듬, 그리고 방해하지 않는 레이아웃. 여기 있는 모든 것은 단 하나의 목표를 위해 존재합니다 — 당신의 글이 아름답게 보이고 느껴지도록 하는 것.

## 또 하나의 블로그 테마를 만든 이유

웹에는 블로그 테마가 넘쳐나니, 왜 또 하나를 만들었는지 묻는 것은 당연합니다. 답은 우선순위에 있습니다. 대부분의 테마는 시각적 임팩트에 최적화합니다 — 큰 히어로 이미지, 복잡한 레이아웃, 애니메이션 전환. 데모에서는 멋지게 보이지만, 누군가가 2,000단어 글을 읽으려 앉으면 오히려 방해가 됩니다.

Astro-Theme-Aither는 다른 전제에서 출발합니다. 콘텐츠가 곧 제품입니다. 테마의 역할은 그 콘텐츠를 정성껏 제공하는 것입니다: 세심한 폰트 조합, 넉넉한 여백, 그리고 장문의 읽기를 편안하게 만드는 수직 리듬.

이 철학은 기술적 결정에도 확장됩니다. 이 테마는 약 0.5 KB의 클라이언트 사이드 JavaScript만 전송합니다 — 테마 토글에 필요한 최소한만. 나머지는 모두 정적 HTML과 CSS입니다. 레이아웃 시프트도, 로딩 스피너도, 백그라운드에서 하이드레이팅하는 JavaScript 프레임워크도 없습니다. 페이지가 로드되면, 읽기만 하면 됩니다.

## 시작하기

설정하고 실행하는 데 몇 분이면 충분합니다. 전체 과정은 다음과 같습니다:

1. **저장소 복제** — GitHub 템플릿 버튼을 사용하거나 `git clone`으로 직접 복제
2. **의존성 설치** — `pnpm install`을 실행하여 모든 패키지 설치
3. **사이트 설정** — `src/config/site.ts`를 편집하여 사이트 제목, 설명, 네비게이션 링크 설정
4. **샘플 콘텐츠 교체** — `src/content/posts/`의 글을 자신의 Markdown 파일로 교체
5. **개발 시작** — `pnpm dev`를 실행하여 핫 리로딩이 되는 로컬 개발 서버 실행
6. **배포** — GitHub에 푸시하면 내장된 CI 워크플로우가 Cloudflare Pages 배포를 처리

### 프로젝트 구조

코드베이스는 즉시 이해할 수 있도록 구성되어 있습니다:

```
src/
├── components/     # 재사용 가능한 Astro 컴포넌트
├── config/         # 사이트 설정
├── content/        # Markdown 글과 콘텐츠
├── layouts/        # 페이지 레이아웃 (Layout.astro)
├── pages/          # 라우트 페이지
└── styles/         # Tailwind v4 토큰을 사용한 글로벌 CSS
```

각 디렉토리에는 명확한 역할이 있습니다. 컴포넌트는 작고 조합 가능합니다. 레이아웃은 문서 셸을 처리합니다. 페이지는 라우트를 정의합니다. 콘텐츠는 글을 담고 있습니다. 마법 같은 것은 없습니다 — 잘 정리된 파일들뿐입니다.

### 첫 번째 글 작성

`src/content/posts/`에 다음 프런트매터를 포함하는 새 `.md` 파일을 만드세요:

```markdown
---
title: 글 제목
date: 2026-01-15
category: General
description: SEO와 소셜 미리보기를 위한 간단한 요약
tags: [Topic, Another]
---

여기에 내용을 작성하세요.
```

`title`, `date`, `category` 필드는 필수입니다. `description` 필드는 메타 설명 태그와 Open Graph 미리보기를 채우기 때문에 작성을 강력히 권장합니다. 태그는 선택 사항이지만 독자들이 관련 콘텐츠를 발견하는 데 도움이 됩니다.

## 무엇이 포함되어 있나

즉시 사용 가능한 프로덕션 준비 블로깅 플랫폼으로, 필요한 모든 기능을 갖추고 불필요한 것은 없습니다.

### 콘텐츠 기능

- **RSS 피드** — `/rss.xml`에 자동 생성, 모든 피드 리더와 호환
- **사이트맵** — 검색 엔진 인덱싱을 위해 `@astrojs/sitemap`으로 자동 생성
- **SEO 메타 태그** — 모든 페이지에 Open Graph, Twitter 카드, 정규 URL
- **다크 모드** — `localStorage` 지속성을 가진 3단 토글 (라이트 / 다크 / 시스템)
- **카테고리 및 태그 페이지** — 독자들이 주제별로 탐색할 수 있는 정리된 아카이브

### 개발자 기능

- **전체 TypeScript** — strict 모드, 완전히 타입이 지정된 컴포넌트와 유틸리티
- **Content Collections** — 빌드 타임 프런트매터 유효성 검사를 포함한 Astro 내장 타입 안전 Markdown 시스템
- **Tailwind CSS v4** — 색상, 폰트, 간격의 손쉬운 커스터마이징을 위한 `@theme` 디자인 토큰 사용
- **Vitest + Playwright** — CI 파이프라인에 이미 연결된 유닛 테스트와 E2E 테스트
- **Cloudflare Pages** — 자동 PR 미리보기 URL이 포함된 배포 워크플로우
- **Google Analytics** — 선택 사항, 메인 스레드를 차단하지 않도록 Partytown Web Worker에서 격리 실행

### 성능

이 테마는 최소한의 JavaScript로 정적 HTML을 출력하기 때문에 기본적으로 뛰어난 성능을 제공합니다. Lighthouse 점수 전 항목 100점을 기대할 수 있습니다 — Performance, Accessibility, Best Practices, SEO. 불필요한 것이 없기 때문에 최적화할 것도 없습니다.

## 커스터마이징

이 테마는 여러분의 것이 되도록 설계되었습니다. 가장 일반적인 커스터마이징은 간단합니다:

- **색상** — `src/styles/global.css`의 CSS 커스텀 프로퍼티를 편집하여 전체 팔레트 변경
- **폰트** — Tailwind 테마 설정에서 font-family 값 교체
- **네비게이션** — `src/config/site.ts`의 네비게이션 링크 배열 업데이트
- **Analytics** — 사이트 설정에서 Google Analytics 측정 ID 추가

더 깊은 변경을 위해 컴포넌트 아키텍처는 의도적으로 단순합니다. 깊게 중첩된 추상화나 복잡한 상태 관리 패턴이 없습니다. 각 컴포넌트는 하나의 일을 하고, props를 읽고, HTML을 렌더링합니다.

## 디자인 철학에 대한 참고

이 테마의 시각적 단순함은 의도적이지만, 엔지니어링적 단순함과는 다릅니다. 내부적으로 이 테마는 놀라울 정도로 많은 것을 처리합니다: 반응형 타이포그래피 스케일, 라이트 및 다크 모드 모두에서의 접근 가능한 색상 대비, 올바른 시맨틱 HTML 구조, 올바른 제목 계층 구조, 그리고 휴대폰부터 울트라와이드 모니터까지 다양한 화면에서의 읽기 경험에 대한 세심한 주의.

좋은 디자인은 보이지 않습니다. 이 테마에서 글을 읽을 때 테마를 전혀 의식하지 않고 글 자체를 즐기게 된다면 — 바로 그것이 의도한 대로 디자인이 작동하는 것입니다.

즐거운 글쓰기 되세요.

---

## AI 에이전트와 도구 사용 (샘플)

URL: https://astro-theme-aither.pages.dev/ko/posts/ai-agents-and-tool-use/
Date: 2026-01-09
Category: AI
Tags: AI, Agents
Description: AI 모델이 채팅을 넘어 현실 세계에서 행동을 실행하는 방법

AI 에이전트는 단순히 텍스트를 생성하는 것이 아니라 행동을 취할 수 있는 언어 모델입니다. 웹을 검색하고, 코드를 실행하고, API를 호출하고, 파일을 읽고, 다음에 할 일을 결정할 수 있습니다. 수동적 텍스트 생성에서 능동적 문제 해결로의 이 전환은 응용 AI에서 가장 중요한 발전 중 하나입니다.

## 채팅에서 행동으로

챗봇은 질문에 답합니다. 에이전트는 문제를 해결합니다. 차이는 자율성입니다: 에이전트는 어떤 도구를 사용할지, 어떤 순서로, 에러를 어떻게 처리할지 결정합니다.

실제 차이를 생각해 보세요. 챗봇에게 "도쿄 날씨가 어때?"라고 물으면 학습 데이터 기반으로 답할 수 있지만 — 몇 달 또는 몇 년 전 데이터로 거의 확실히 부정확합니다. 에이전트에게 같은 질문을 하면 날씨 API를 호출하고 현재 데이터를 검색하여 정확하고 최신 답변을 반환합니다.

챗봇은 그럴듯한 텍스트를 생성합니다. 에이전트는 세계와 상호작용합니다.

### 자율성의 스펙트럼

모든 에이전트가 동일하게 자율적이지는 않습니다. 스펙트럼이 있습니다:

1. **도구 보조 채팅** — 모델이 도구를 호출할 수 있지만, 사용자 요청에 대한 직접 응답으로만. 턴당 하나의 도구 호출.
2. **다단계 에이전트** — 모델이 작업을 완수하기 위해 여러 도구 호출을 연쇄할 수 있으며, 순서를 스스로 결정.
3. **완전 자율 에이전트** — 모델이 장기간 독립적으로 운영하며, 결정을 내리고 에러를 처리하고 최소한의 인간 감독으로 목표를 추구.

현재 대부분의 프로덕션 시스템은 1-2 수준입니다. 완전 자율 에이전트는 아직 해결해야 할 중요한 안전 과제가 있는 활발한 연구 분야입니다.

## 도구 사용

도구 사용은 AI 모델이 외부 함수를 호출할 수 있게 합니다. 모델은 도구가 필요한 시점을 결정하고, 올바른 매개변수를 생성하고, 결과를 응답에 통합합니다.

### 도구 사용의 작동 방식

메커니즘은 간단합니다:

1. **도구 정의** — 이름, 매개변수, 역할을 포함하여 사용 가능한 도구를 모델에 설명합니다.
2. **결정** — 사용자 요청을 처리할 때 모델이 도구가 도움이 될지 결정합니다. 그렇다면 적절한 매개변수로 도구 호출을 생성합니다.
3. **실행** — 애플리케이션이 도구 호출을 실행하고(모델이 직접 실행하지 않음) 결과를 반환합니다.
4. **통합** — 모델이 도구 결과를 사용자 응답에 통합합니다.

### 도구 정의 예시

```json
{
  "name": "search_documentation",
  "description": "Search the product documentation for relevant articles",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "The search query"
      },
      "max_results": {
        "type": "integer",
        "description": "Maximum number of results to return",
        "default": 5
      }
    },
    "required": ["query"]
  }
}
```

### 일반적인 도구 카테고리

프로덕션 에이전트 시스템은 보통 여러 카테고리의 도구를 제공합니다:

- **정보 검색** — 웹 검색, 데이터베이스 쿼리, 파일 읽기, API 호출
- **코드 실행** — 샌드박스 환경에서 Python, JavaScript, 셸 명령 실행
- **커뮤니케이션** — 이메일 전송, 메시지 게시, 티켓 생성
- **파일 조작** — 파일 생성, 편집, 정리
- **시스템 운영** — 코드 배포, 인프라 관리, CI 파이프라인 실행

제공하는 도구가 에이전트가 할 수 있는 것의 경계를 정의합니다. 잘 설계된 도구 세트는 에이전트에게 유용할 만큼의 능력을 부여하면서 위험할 만큼의 권한은 주지 않습니다.

## 에이전트 루프

가장 강력한 패턴은 에이전트 루프입니다: 모델이 단계를 계획하고, 실행하고, 결과를 관찰하고, 다음 단계를 결정합니다. 이 루프는 작업이 완료되거나 진행할 수 없다고 판단할 때까지 계속됩니다.

### 루프의 에러 처리

견고한 에이전트는 실패를 우아하게 처리해야 합니다. 좋은 에이전트 설계에는 다음이 포함됩니다:

- **재시도 로직** — 일시적 실패를 백오프와 함께 재시도
- **대체 전략** — 한 접근이 실패하면 다른 것을 시도
- **우아한 성능 저하** — 작업을 완전히 완료할 수 없으면 가능한 만큼 완료하고 남은 것을 설명
- **루프 제한** — 에이전트가 막힐 때 무한 루프를 방지하기 위한 최대 반복 횟수 설정

## 효과적인 도구 설계

### 도구 설계 원칙

- **명확한 이름** — `query_db_1`보다 `search_users`가 좋습니다. 모델은 이름을 기반으로 도구를 호출할 시기를 결정합니다.
- **설명적 매개변수** — 모든 매개변수에 설명을 포함하세요.
- **집중된 범위** — 각 도구가 하나의 일을 잘 해야 합니다.
- **유용한 에러** — 무엇이 잘못되었고 대신 무엇을 시도할지 이해할 수 있는 명확한 에러 메시지를 반환하세요.
- **가능하면 멱등성** — 안전하게 재시도할 수 있는 도구가 에러 처리를 단순화합니다.

## 위험

행동을 취할 수 있는 에이전트는 잘못된 행동을 취할 수 있습니다. 샌드박싱, 확인 단계, 인간 참여 리뷰는 모든 프로덕션 에이전트 시스템의 필수 안전 조치입니다.

### 안전 패턴

프로덕션 에이전트 시스템은 여러 안전 패턴을 구현해야 합니다:

1. **최소 권한** — 에이전트에게 특정 작업에 필요한 도구만 제공
2. **샌드박싱** — 코드와 파일 작업을 격리된 환경에서 실행
3. **확인 게이트** — 파괴적이거나 돌이킬 수 없는 행동에 인간 승인 요구
4. **감사 로깅** — 모든 도구 호출과 결과를 기록
5. **킬 스위치** — 실행 중인 에이전트를 즉시 중단하는 메커니즘 제공
6. **예산 제한** — API 호출, 토큰 사용, 컴퓨트 시간에 하드 캡 설정

목표는 에이전트가 유용하지 못하게 하는 것이 아닌 — 잘 정의된 경계 내에서 유용하게 하는 것입니다.