> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nudgen.net/llms.txt
> Use this file to discover all available pages before exploring further.

# AI 에이전트 사용법

> AI 에이전트를 위한 인터페이스로 Nudgen CLI를 사용하는 방법입니다.

## 개요

Nudgen CLI는 **AI 우선(AI-First)** 접근 방식으로 설계되었습니다. 사람을 위한 아름다운 TUI를 제공함과 동시에, 모든 명령은 기계 간 통신에 최적화되어 있습니다.

### 에이전트 패턴

AI 에이전트(Claude, GPT 또는 특수 자동화 에이전트 등)가 CLI를 사용할 때는 다음 패턴을 따라야 합니다:

1. **JSON 출력**: 기계가 파싱할 수 있는 데이터를 얻기 위해 모든 명령에 `--json`을 추가합니다.
2. **컨텍스트 인식**: 작업을 수행하기 전에 항상 팀 컨텍스트를 확인합니다.
3. **비대화형**: 대화형 TUI 프롬프트를 건너뛰려면 플래그를 사용합니다.

## JSON 자동화

모든 목록 및 상태 명령은 `--json` 플래그를 지원합니다. 이를 통해 서식 있는 테이블 대신 깔끔한 JSON 구조를 반환받을 수 있습니다.

```bash theme={null}
# 모든 캠페인을 JSON으로 가져오기
nudgen campaigns list --json

# 현재 팀의 연락처 가져오기
nudgen contacts list --json
```

## 에이전트를 위한 멀티 테넌트 워크플로우

Nudgen은 여러 팀을 지원하므로, 에이전트는 리소스를 생성하거나 업데이트하기 전에 올바른 팀에서 작업 중인지 확인해야 합니다.

**권장 워크플로우:**

1. **현재 팀 확인**:
   ```bash theme={null}
   nudgen teams current --json
   ```
2. **팀 전환 (필요한 경우)**:
   이전 단계의 `id`가 대상 팀과 일치하지 않으면 전환합니다:
   ```bash theme={null}
   nudgen teams switch <target-team-id>
   ```
3. **데이터 명령 실행**:
   `campaigns`, `contacts` 또는 `brand` 명령을 진행합니다.

## 에이전트 개발자를 위한 모범 사례

* **에러 처리**: CLI 명령의 종료 코드를 모니터링하세요. 0이 아닌 종료 코드는 에러(유효성 검사, 네트워크 또는 인증)를 나타냅니다.
* **요율 제한(Rate Limiting)**: CLI는 Nudgen API와 통신합니다. 에이전트 스크립트가 발생할 수 있는 요율 제한을 원활하게 처리하도록 하세요.
* **자동 모드**: 명령이 모든 프롬프트에 대해 특정 플래그를 지원하지 않는 경우, 에이전트가 TUI 루프에 빠지지 않고 stdout/stderr 스트림을 처리할 수 있는지 확인하세요.