> ## Documentation Index
> Fetch the complete documentation index at: https://crewai.burt.pe.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# Portkey를 활용한 에이전트 모니터링

> CrewAI와 함께 Portkey 사용 방법

<img src="https://raw.githubusercontent.com/siddharthsambharia-portkey/Portkey-Product-Images/main/Portkey-CrewAI.png" alt="Portkey CrewAI Header Image" width="70%" />

[Portkey](https://portkey.ai/?utm_source=crewai\&utm_medium=crewai\&utm_campaign=crewai)는 CrewAI 에이전트를 신뢰할 수 있고, 비용 효율적이며, 빠르게 만드는 2줄의 업그레이드다.

Portkey는 모든 CrewAI 에이전트에 4가지 핵심 프로덕션 기능을 추가한다:

1. **200개 이상의 LLM**으로 라우팅
2. 각 LLM 호출을 더 견고하게 만듦
3. 전체 스택 추적 및 비용, 성능 분석
4. 행동을 강제하는 실시간 가드레일

## 시작하기

<Steps>
  <Step title="CrewAI와 Portkey 설치">
    ```bash theme={null}
    pip install -qU crewai portkey-ai
    ```
  </Step>

  <Step title="LLM 클라이언트 설정">
    Portkey와 함께 CrewAI 에이전트를 구축하려면 두 가지 키가 필요하다:

    * **Portkey API 키**: [Portkey 앱](https://app.portkey.ai/?utm_source=crewai\&utm_medium=crewai\&utm_campaign=crewai)에 가입하고 API 키를 복사한다.
    * **가상 키**: 가상 키는 여러분의 LLM API 키를 한 곳에서 안전하게 관리한다. Portkey의 보관소에 LLM 프로바이더의 API 키를 안전하게 저장한다.

    ```python theme={null}
    from crewai import LLM
    from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

    gpt_llm = LLM(
        model="gpt-4",
        base_url=PORTKEY_GATEWAY_URL,
        api_key="dummy", # 가상 키를 사용한다.
        extra_headers=createHeaders(
            api_key="YOUR_PORTKEY_API_KEY",
            virtual_key="YOUR_VIRTUAL_KEY", # Portkey에서 가상 키를 입력한다.
        )
    )
    ```
  </Step>

  <Step title="첫 번째 에이전트 생성 및 실행">
    ```python theme={null}
    from crewai import Agent, Task, Crew

    # 역할과 목표를 가진 에이전트를 정의한다.
    coder = Agent(
        role='소프트웨어 개발자',
        goal='요청에 따라 명확하고 간결한 코드를 작성한다.',
        backstory='소프트웨어 트렌드에 대한 날카로운 통찰력을 가진 전문 코더.',
        llm=gpt_llm
    )

    # 에이전트를 위한 작업을 생성한다.
    task1 = Task(
        description="제목이 'Hello World! Portkey is working!'인 간단한 웹사이트를 만들기 위한 HTML을 정의한다.",
        expected_output="명확하고 간결한 HTML 코드",
        agent=coder
    )

    # 크루를 인스턴스화한다.
    crew = Crew(
        agents=[coder],
        tasks=[task1],
    )

    result = crew.kickoff()
    print(result)
    ```
  </Step>
</Steps>

## 주요 기능

| 기능           | 설명                                                              |
| :----------- | :-------------------------------------------------------------- |
| 🌐 다중 LLM 지원 | OpenAI, Anthropic, Gemini, Azure 및 250개 이상의 프로바이더를 통합 인터페이스로 접근 |
| 🛡️ 프로덕션 안정성 | 재시도, 타임아웃, 로드 밸런싱 및 폴백 기능 구현                                    |
| 📊 고급 관측 기능  | 비용, 토큰, 지연 시간 및 커스텀 메타데이터를 포함한 40개 이상의 지표 추적                    |
| 🔍 상세 로깅     | 실행 추적 및 함수 호출 로그를 통해 디버깅 가능                                     |
| 🚧 보안 제어     | 예산 제한 설정 및 역할 기반 접근 제어 구현                                       |
| 🔄 성능 분석     | 피드백을 수집 및 분석하여 지속적인 개선 가능                                       |
| 💾 지능형 캐싱    | 시맨틱 또는 단순 캐싱을 통해 비용과 지연 시간 감소                                   |

## Portkey 설정을 활용한 프로덕션 기능

아래에서 설명하는 모든 기능은 Portkey의 설정 시스템을 통해 구현한다. Portkey 설정 시스템을 사용하면 LLM API 호출 시 간단한 JSON 객체로 라우팅 전략을 정의할 수 있다. 코드 내에서 직접 설정을 생성하고 관리하거나 Portkey 대시보드를 통해 관리할 수 있다. 각 설정은 고유한 ID를 가지므로 쉽게 참조할 수 있다.

<Frame>
  <img src="https://raw.githubusercontent.com/Portkey-AI/docs-core/refs/heads/main/images/libraries/libraries-3.avif" />
</Frame>

### 1. 250개 이상의 LLM 활용

Anthropic, Gemini, Mistral, Azure OpenAI 등 다양한 LLM을 최소한의 코드 변경으로 활용할 수 있다. 여러 프로바이더 간 전환이나 동시 사용이 가능하다. [Universal API에 대해 더 알아보기](https://portkey.ai/docs/product/ai-gateway/universal-api)

다른 LLM 프로바이더 간 전환은 간단하다:

```python theme={null}
# Anthropic 설정
anthropic_llm = LLM(
    model="claude-3-5-sonnet-latest",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_ANTHROPIC_VIRTUAL_KEY", # 가상 키 사용 시 프로바이더 필요 없음
        trace_id="anthropic_agent"
    )
)

# Azure OpenAI 설정
azure_llm = LLM(
    model="gpt-4",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_AZURE_VIRTUAL_KEY", # 가상 키 사용 시 프로바이더 필요 없음
        trace_id="azure_agent"
    )
)
```

### 2. 캐싱(Caching)

두 가지 강력한 캐싱 모드를 활용해 응답 시간을 단축하고 비용을 절감할 수 있다:

* **단순 캐시(Simple Cache)**: 정확히 일치하는 요청에 적합
* **의미 기반 캐시(Semantic Cache)**: 의미상 유사한 요청에 대한 응답을 매칭

[캐싱에 대해 더 알아보기](https://portkey.ai/docs/product/ai-gateway/cache-simple-and-semantic)

```py theme={null}
config = {
    "cache": {
        "mode": "semantic",  # 정확한 매칭을 원하면 "simple"로 설정
    }
}
```

### 3. 프로덕션 신뢰성

Portkey는 포괄적인 신뢰성 기능을 제공한다:

* **자동 재시도**: 일시적인 실패를 유연하게 처리
* **요청 타임아웃**: 멈춤 현상 방지
* **조건부 라우팅**: 특정 조건에 따라 요청을 라우팅
* **대체 동작**: 자동 프로바이더 장애 조치 설정
* **로드 밸런싱**: 요청을 효율적으로 분배

[신뢰성 기능에 대해 더 알아보기](https://portkey.ai/docs/product/ai-gateway/)

### 4. 메트릭

에이전트 실행은 복잡하다. Portkey는 비용, 사용한 토큰, 지연 시간 등을 포함해 AI 에이전트에 대한 **40개 이상의 포괄적인 메트릭**을 자동으로 기록한다. 에이전트 실행에 대한 전체 개요가 필요하거나 세부적인 통찰이 필요할 때, Portkey의 커스텀 필터는 원하는 메트릭을 제공한다.

* 에이전트 상호작용당 비용
* 응답 시간과 지연 시간
* 토큰 사용량과 효율성
* 성공/실패율
* 캐시 적중률

<img src="https://github.com/siddharthsambharia-portkey/Portkey-Product-Images/blob/main/Portkey-Dashboard.png?raw=true" width="70%" alt="Portkey Dashboard" />

### 5. 상세 로깅

로그는 에이전트의 동작을 이해하고 문제를 진단하며 성능을 개선하는 데 필수적이다. 에이전트 활동과 도구 사용에 대한 상세 기록을 제공해 디버깅과 프로세스 최적화에 중요한 역할을 한다.

에이전트 실행 기록을 확인할 수 있는 전용 섹션에 접근해 매개변수, 결과, 함수 호출, 오류 등을 확인할 수 있다. trace ID, 모델, 사용된 토큰, 메타데이터 등 다양한 매개변수를 기반으로 로그를 필터링할 수 있다.

<details>
  <summary><b>트레이스</b></summary>

  <img src="https://raw.githubusercontent.com/siddharthsambharia-portkey/Portkey-Product-Images/main/Portkey-Traces.png" alt="Portkey Traces" width="70%" />
</details>

<details>
  <summary><b>로그</b></summary>

  <img src="https://raw.githubusercontent.com/siddharthsambharia-portkey/Portkey-Product-Images/main/Portkey-Logs.png" alt="Portkey Logs" width="70%" />
</details>

### 6. 기업 보안 기능

* 가상 키(일회용 API 키)별 예산 한도와 요청 제한 설정
* 역할 기반 접근 제어 구현
* 감사 로그를 통해 시스템 변경 사항 추적
* 데이터 보존 정책 구성

Configs 생성 및 관리에 대한 자세한 내용은 [Portkey 문서](https://docs.portkey.ai/product/ai-gateway/configs)를 참고한다.

## 리소스

* [📘 Portkey 문서](https://docs.portkey.ai)
* [📊 Portkey 대시보드](https://app.portkey.ai/?utm_source=crewai\&utm_medium=crewai\&utm_campaign=crewai)
* [🐦 트위터](https://twitter.com/portkeyai)
* [💬 Discord 커뮤니티](https://discord.gg/DD7vgKK299)