Portkey CrewAI 헤더 이미지

​
소개

Portkey는 CrewAI에 프로덕션 적합성을 위한 기능을 추가하여 실험적인 agent crew를 다음과 같이 견고한 시스템으로 전환합니다.
  • 모든 agent 단계, 도구 사용, 상호작용에 대한 완전한 관찰 가능성
  • 내장된 신뢰성: 폴백, 재시도, 로드 밸런싱 기능 제공
  • AI 비용 관리를 위한 비용 추적 및 최적화
  • 단일 통합을 통한 200개 이상의 LLM 접근
  • agent의 행동을 안전하고 규정 준수로 유지하는 가드레일
  • 일관된 agent 성능을 위한 버전 관리되는 prompt

​
설치 및 설정

1

필요한 패키지 설치하기

pip install -U crewai portkey-ai

API 키 생성

Portkey 대시보드에서 예산/속도 제한을 선택적으로 설정하여 Portkey API 키를 생성하세요. 이 키에는 신뢰성, 캐싱 등 여러 가지 구성을 추가로 적용할 수 있습니다. 자세한 내용은 추후 설명합니다.
3

Portkey로 CrewAI 구성하기

통합은 매우 간단합니다. CrewAI 설정의 LLM 구성을 다음과 같이 업데이트하기만 하면 됩니다:
from crewai import LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

# Portkey 통합으로 LLM 인스턴스 생성
gpt_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",  # Virtual key를 사용하므로 이 값은 단순한 placeholder입니다.
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_LLM_VIRTUAL_KEY",
        trace_id="unique-trace-id",               # 요청 추적을 위한 선택 사항
    )
)

#Crew Agents에서 다음처럼 사용하세요:

	@agent
	def lead_market_analyst(self) -> Agent:
		return Agent(
			config=self.agents_config['lead_market_analyst'],
			verbose=True,
			memory=False,
			llm=gpt_llm
		)
Virtual Key란? Portkey의 Virtual Key는 LLM 제공업체의 API 키(OpenAI, Anthropic 등)를 암호화된 금고에 안전하게 저장합니다. 이를 통해 키 교체 및 예산 관리를 더 쉽게 할 수 있습니다. Virtual Key에 대해 자세히 알아보기.

​
프로덕션 기능

​
1. 향상된 가시성

Portkey는 CrewAI agent에 대한 종합적인 가시성을 제공하여 각 실행 중에 어떤 일이 일어나고 있는지 정확히 이해할 수 있게 도와줍니다.
Traces는 crew의 실행을 계층적으로 보여주며, LLM 호출, 도구 호출, 상태 전환의 순서를 확인할 수 있습니다.
# Portkey에서 계층적 추적을 활성화하려면 trace_id를 추가하세요
portkey_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_OPENAI_VIRTUAL_KEY",
        trace_id="unique-session-id"  # 고유한 trace ID 추가
    )
)

​
2. 신뢰성 - Crew를 원활하게 운영하세요

프로덕션에서 crew를 운영할 때, API 속도 제한, 네트워크 이슈 또는 공급자 장애와 같이 문제가 발생할 수 있습니다. Portkey의 신뢰성 기능은 문제가 발생해도 에이전트가 원활하게 동작하도록 보장합니다. Portkey Config를 사용하여 CrewAI 설정에서 페일오버를 간단하게 활성화할 수 있습니다: 
from crewai import LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

# Create LLM with fallback configuration
portkey_llm = LLM(
    model="gpt-4o",
    max_tokens=1000,
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        config={
            "strategy": {
                "mode": "fallback"
            },
            "targets": [
                {
                    "provider": "openai",
                    "api_key": "YOUR_OPENAI_API_KEY",
                    "override_params": {"model": "gpt-4o"}
                },
                {
                    "provider": "anthropic",
                    "api_key": "YOUR_ANTHROPIC_API_KEY",
                    "override_params": {"model": "claude-3-opus-20240229"}
                }
            ]
        }
    )
)

# Use this LLM configuration with your agents
이 설정은 GPT-4o 요청이 실패할 경우 자동으로 Claude를 시도하여 crew가 계속 운영될 수 있도록 보장합니다.

자동 재시도

일시적인 실패를 자동으로 처리합니다. LLM 호출에 실패하면 Portkey가 지정된 횟수만큼 동일한 요청을 재시도합니다. 속도 제한이나 네트워크 장애에서 완벽하게 사용할 수 있습니다.

요청 타임아웃

에이전트가 멈추는 것을 방지합니다. 타임아웃을 설정하여 요구되는 시간 내에 응답을 받거나(혹은 우아하게 실패할 수 있도록) 합니다.

조건부 라우팅

다양한 요청을 다양한 공급자에게 보낼 수 있습니다. 복잡한 reasoning은 GPT-4로, 창의적인 작업은 Claude로, 빠른 응답은 Gemini로 필요에 따라 라우팅하세요.

페일오버

기본 공급자가 실패해도 계속 운영됩니다. 백업 공급자로 자동으로 전환되어 가용성을 유지합니다.

로드 밸런싱

여러 API 키 또는 공급자에 요청을 분산시킵니다. 대량 crew 운영 및 속도 제한 내에서 작업할 때 유용합니다.

​
3. CrewAI에서의 프롬프트 사용

Portkey의 Prompt Engineering Studio는 CrewAI 에이전트에서 사용하는 프롬프트를 생성, 관리, 최적화하도록 도와줍니다. 프롬프트나 지시문을 하드코딩하는 대신 Portkey의 프롬프트 렌더링 API를 사용하여 버전 관리된 프롬프트를 동적으로 가져와 적용할 수 있습니다.
Prompt Playground Interface

Portkey의 프롬프트 라이브러리에서 프롬프트 관리하기

Prompt Playground는 여러분의 AI 애플리케이션을 위해 완벽한 프롬프트를 비교, 테스트, 배포할 수 있는 공간입니다. 이곳은 다양한 모델을 실험하고, 변수들을 테스트하며, 출력값을 비교하고, 배포 전에 프롬프트 엔지니어링 전략을 다듬을 수 있는 곳입니다. 이를 통해 다음과 같은 작업이 가능합니다:
  1. 에이전트에서 사용하기 전에 프롬프트를 반복적으로 개발
  2. 다양한 변수와 모델로 프롬프트 테스트
  3. 서로 다른 프롬프트 버전의 출력값 비교
  4. 팀원들과 프롬프트 개발 협업
이 시각적 환경을 통해 CrewAI 에이전트 워크플로우의 각 단계에 효과적인 프롬프트를 쉽게 작성할 수 있습니다.

Prompt Engineering Studio

Portkey의 프롬프트 관리 기능에 대해 더 알아보기

​
4. 안전한 Crew를 위한 가드레일

가드레일은 CrewAI agent가 모든 상황에서 안전하게 작동하고 적절하게 응답하도록 보장합니다. 가드레일을 사용하는 이유는 무엇인가요? CrewAI agent는 다양한 실패 모드를 경험할 수 있습니다:
  • 유해하거나 부적절한 콘텐츠 생성
  • PII와 같은 민감 정보 유출
  • 잘못된 정보의 환각
  • 잘못된 형식의 출력 생성
Portkey의 가드레일은 입력과 출력 모두에 대한 보호를 추가합니다. 가드레일 구현하기 
from crewai import Agent, LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

# Create LLM with guardrails
portkey_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_OPENAI_VIRTUAL_KEY",
        config={
            "input_guardrails": ["guardrails-id-xxx", "guardrails-id-yyy"],
            "output_guardrails": ["guardrails-id-zzz"]
        }
    )
)

# Create agent with guardrailed LLM
researcher = Agent(
    role="Senior Research Scientist",
    goal="Discover groundbreaking insights about the assigned topic",
    backstory="You are an expert researcher with deep domain knowledge.",
    verbose=True,
    llm=portkey_llm
)
Portkey의 가드레일은 다음을 수행할 수 있습니다:
  • 입력 및 출력의 PII 감지 및 마스킹
  • 유해하거나 부적절한 콘텐츠 필터링
  • 응답 형식을 스키마에 따라 검증
  • 근거 자료와 비교하여 환각 여부 확인
  • 맞춤형 비즈니스 로직 및 규칙 적용

가드레일에 대해 더 알아보기

Portkey의 가드레일 기능을 탐색하여 agent의 안전성을 높여보세요

​
5. 메타데이터로 사용자 추적

Portkey의 메타데이터 시스템을 사용하여 CrewAI 에이전트를 통해 개별 사용자를 추적할 수 있습니다. Portkey에서의 메타데이터란? 메타데이터를 사용하면 각 요청에 사용자 지정 데이터를 연결할 수 있어 필터링, 세분화, 분석이 가능합니다. 특별한 _user 필드는 사용자 추적을 위해 특별히 설계되었습니다. 
from crewai import Agent, LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

# 사용자 추적이 설정된 LLM 구성
portkey_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_OPENAI_VIRTUAL_KEY",
        metadata={
            "_user": "user_123",  # 사용자 분석을 위한 특별 _user 필드
            "user_tier": "premium",
            "user_company": "Acme Corp",
            "session_id": "abc-123"
        }
    )
)

# 추적된 LLM으로 에이전트 생성
researcher = Agent(
    role="Senior Research Scientist",
    goal="Discover groundbreaking insights about the assigned topic",
    backstory="You are an expert researcher with deep domain knowledge.",
    verbose=True,
    llm=portkey_llm
)
사용자별로 분석 필터링 메타데이터가 설정되어 있으면, 사용자별로 분석을 필터링하고 사용자 단위의 성능 지표를 분석할 수 있습니다:

사용자별로 분석 필터링

이를 통해 다음이 가능합니다:
  • 사용자별 비용 추적 및 예산 관리
  • 개인화된 사용자 분석
  • 팀 또는 조직 단위의 지표
  • 환경별 모니터링(스테이징 vs. 프로덕션)

메타데이터에 대해 더 알아보기

맞춤형 메타데이터를 활용하여 분석 기능을 향상시키는 방법을 살펴보세요

​
6. 효율적인 Crews를 위한 캐싱

캐싱을 구현하여 CrewAI agent를 보다 효율적이고 비용 효율적으로 만드세요: 
from crewai import Agent, LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

# Configure LLM with simple caching
portkey_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_OPENAI_VIRTUAL_KEY",
        config={
            "cache": {
                "mode": "simple"
            }
        }
    )
)

# Create agent with cached LLM
researcher = Agent(
    role="Senior Research Scientist",
    goal="Discover groundbreaking insights about the assigned topic",
    backstory="You are an expert researcher with deep domain knowledge.",
    verbose=True,
    llm=portkey_llm
)
Simple 캐싱은 입력 프롬프트에 대한 정확한 일치 항목을 수행하며, 동일한 요청을 캐시에 저장하여 중복된 모델 실행을 방지합니다.

​
7. 모델 상호 운용성

CrewAI는 여러 LLM 제공업체를 지원하며, Portkey는 통합 인터페이스를 통해 200개 이상의 LLM에 대한 액세스를 제공함으로써 이 기능을 확장합니다. 코어 에이전트 로직을 변경하지 않고도 다양한 모델 간에 쉽게 전환할 수 있습니다: 
from crewai import Agent, LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

# Set up LLMs with different providers
openai_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_OPENAI_VIRTUAL_KEY"
    )
)

anthropic_llm = LLM(
    model="claude-3-5-sonnet-latest",
    max_tokens=1000,
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_ANTHROPIC_VIRTUAL_KEY"
    )
)

# Choose which LLM to use for each agent based on your needs
researcher = Agent(
    role="Senior Research Scientist",
    goal="Discover groundbreaking insights about the assigned topic",
    backstory="You are an expert researcher with deep domain knowledge.",
    verbose=True,
    llm=openai_llm  # Use anthropic_llm for Anthropic
)
Portkey는 다음을 포함한 제공업체의 LLM에 액세스를 제공합니다:
  • OpenAI (GPT-4o, GPT-4 Turbo 등)
  • Anthropic (Claude 3.5 Sonnet, Claude 3 Opus 등)
  • Mistral AI (Mistral Large, Mistral Medium 등)
  • Google Vertex AI (Gemini 1.5 Pro 등)
  • Cohere (Command, Command-R 등)
  • AWS Bedrock (Claude, Titan 등)
  • 로컬/프라이빗 모델

지원되는 제공업체

Portkey에서 지원하는 전체 LLM 제공업체 목록 보기

​
CrewAI를 위한 엔터프라이즈 거버넌스 설정

엔터프라이즈 거버넌스가 필요한 이유 조직 내에서 CrewAI를 사용하는 경우, 여러 거버넌스 측면을 고려해야 합니다:
  • 비용 관리: 팀별 AI 사용 비용 통제 및 추적
  • 접근 제어: 특정 팀이 특정 모델을 사용할 수 있도록 관리
  • 사용 분석: 조직 전반에서 AI 사용 현황 파악
  • 보안 및 컴플라이언스: 엔터프라이즈 수준의 보안 기준 유지
  • 신뢰성: 모든 사용자에게 일관된 서비스 제공 보장
Portkey는 이러한 엔터프라이즈 요구를 해결하는 종합적인 거버넌스 계층을 추가합니다. 이제 이러한 컨트롤을 단계별로 구현해보겠습니다.
1

Virtual Key 생성

Virtual Key는 Portkey의 안전한 LLM 공급자 API 키 관리 방식입니다. 주요 제어 기능을 제공합니다:
  • API 사용에 대한 예산 제한
  • 속도 제한(Rate limiting) 기능
  • 안전한 API 키 저장
Virtual Key를 생성하려면: Portkey 앱에서 Virtual Keys로 이동하세요. Virtual Key ID를 저장하고 복사하세요.
Virtual Key ID를 저장하세요. 다음 단계에서 필요합니다.
2

기본 Config 생성

Portkey에서 Config는 요청 라우팅 방식을 정의하며, 고급 라우팅·폴백·재시도 등 기능을 제공합니다.Config를 생성하려면:
  1. Portkey 대시보드의 Configs로 이동
  2. 아래와 같은 새 config 생성: 
    {
    "virtual_key": "YOUR_VIRTUAL_KEY_FROM_STEP1",
   	"override_params": {
      "model": "gpt-4o" // 선호하는 모델명
    }
}
  3. Config 이름을 저장하고 다음 단계에 사용하세요.
3

Portkey API Key 설정

이제 Portkey API 키를 생성하고, 2단계에서 만든 config에 연결하세요:
  1. Portkey의 API Keys로 이동해 새 API 키 생성
  2. 2단계에서 만든 config 선택
  3. API 키를 생성 및 저장
4

CrewAI에 연결

Portkey API 키와 config를 설정한 후, 이를 CrewAI agent에 연결하세요:
from crewai import Agent, LLM
from portkey_ai import PORTKEY_GATEWAY_URL

# API 키로 LLM 구성
portkey_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="YOUR_PORTKEY_API_KEY"
)

# Portkey가 적용된 LLM으로 agent 생성
researcher = Agent(
    role="Senior Research Scientist",
    goal="Discover groundbreaking insights about the assigned topic",
    backstory="You are an expert researcher with deep domain knowledge.",
    verbose=True,
    llm=portkey_llm
)

​
엔터프라이즈 기능이 이제 사용 가능합니다

귀하의 CrewAI 통합에는 이제 다음과 같은 기능이 포함됩니다:
  • 부서별 예산 관리
  • 모델 접근 거버넌스
  • 사용량 추적 및 귀속
  • 보안 가드레일
  • 신뢰성 기능

​
자주 묻는 질문

​
자료

CrewAI Docs

공식 CrewAI 문서

Book a Demo

이 통합 구현에 대한 맞춤형 안내를 받아보세요