Portkey CrewAI Header Image

​
Introdução

Portkey aprimora o CrewAI com recursos prontos para produção, transformando seus crews de agentes experimentais em sistemas robustos ao fornecer:
  • Observabilidade completa de cada etapa do agente, uso de ferramentas e interações
  • Confiabilidade incorporada com fallbacks, tentativas automáticas e balanceamento de carga
  • Rastreamento e otimização de custos para gerenciar seus gastos com IA
  • Acesso a mais de 200 LLMs por meio de uma única integração
  • Guardrails para manter o comportamento dos agentes seguro e em conformidade
  • Prompts versionados para desempenho consistente dos agentes

​
Instalação & Configuração

1

Instale os pacotes necessários

pip install -U crewai portkey-ai

Gere a Chave de API

Crie uma chave de API Portkey com limites de orçamento/taxa opcionais no painel da Portkey. Você também pode adicionar configurações para confiabilidade, cache e outros recursos a essa chave. Mais sobre isso em breve.
3

Configure o CrewAI com Portkey

A integração é simples – basta atualizar a configuração do LLM no seu setup do CrewAI:
from crewai import LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

# Crie uma instância do LLM com integração Portkey
gpt_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",  # Estamos usando uma chave virtual, então isso é apenas um placeholder
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_LLM_VIRTUAL_KEY",
        trace_id="unique-trace-id",               # Opcional, para rastreamento da requisição
    )
)

#Use-os nos seus Crew Agents assim:

	@agent
	def lead_market_analyst(self) -> Agent:
		return Agent(
			config=self.agents_config['lead_market_analyst'],
			verbose=True,
			memory=False,
			llm=gpt_llm
		)
O que são Virtual Keys? Virtual keys no Portkey armazenam com segurança suas chaves de API dos provedores LLM (OpenAI, Anthropic, etc.) em um cofre criptografado. Elas facilitam a rotação de chaves e o gerenciamento de orçamento. Saiba mais sobre virtual keys aqui.

​
Recursos para Produção

​
1. Observabilidade Avançada

Portkey oferece observabilidade abrangente para seus agentes CrewAI, ajudando você a entender exatamente o que está acontecendo durante cada execução.
Os traces fornecem uma visão hierárquica da execução do seu crew, mostrando a sequência de chamadas LLM, ativações de ferramentas e transições de estado.
# Adicione trace_id para habilitar o tracing hierárquico no Portkey
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"  # Adicione um trace ID único
    )
)

​
2. Confiabilidade - Mantenha Seus Crews Funcionando Sem Interrupções

Ao executar crews em produção, problemas podem ocorrer – limites de taxa da API, problemas de rede ou indisponibilidade do provedor. Os recursos de confiabilidade do Portkey garantem que seus agentes continuem funcionando mesmo quando problemas surgem. É simples habilitar fallback na sua configuração CrewAI usando um Config do Portkey: 
from crewai import LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

# Crie LLM com configuração de fallback
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 essa configuração LLM com seus agentes
Essa configuração automaticamente tentará o Claude caso a requisição para o GPT-4o falhe, garantindo que seu crew continue funcionando.

Tentativas Automáticas

Lida automaticamente com falhas temporárias. Se uma chamada LLM falhar, o Portkey fará novas tentativas o número especificado de vezes – perfeito para limites de taxa ou instabilidades de rede.

Timeouts de Requisição

Evite que seus agentes fiquem travados. Defina timeouts para garantir respostas (ou falhas controladas) dentro do tempo necessário.

Roteamento Condicional

Envie diferentes solicitações para diferentes provedores. Direcione raciocínios complexos para o GPT-4, tarefas criativas para Claude e respostas rápidas para Gemini conforme sua necessidade.

Fallbacks

Mantenha-se em funcionamento mesmo se seu provedor principal falhar. Troque automaticamente para provedores de backup para manter a disponibilidade.

Balanceamento de Carga

Distribua solicitações entre várias chaves de API ou provedores. Ótimo para operações de crew em grande escala e para permanecer dentro dos limites de taxa.

​
3. Prompting no CrewAI

O Prompt Engineering Studio do Portkey ajuda você a criar, gerenciar e otimizar os prompts usados em seus agentes CrewAI. Em vez de codificar prompts ou instruções manualmente, use a API de renderização de prompts do Portkey para buscar e aplicar dinâmicamente seus prompts versionados.
Prompt Playground Interface

Gerencie prompts na Prompt Library do Portkey

Prompt Playground é um local para comparar, testar e implantar prompts perfeitos para sua aplicação de IA. É onde você experimenta com diferentes modelos, testa variáveis, compara saídas e refina sua estratégia de engenharia de prompts antes de implantar em produção. Ele permite:
  1. Desenvolver prompts de forma iterativa antes de usá-los em seus agentes
  2. Testar prompts com diferentes variáveis e modelos
  3. Comparar saídas entre diferentes versões de prompts
  4. Colaborar com membros da equipe no desenvolvimento de prompts
Esse ambiente visual facilita a criação de prompts eficazes para cada etapa do fluxo de trabalho dos seus agentes CrewAI.

Prompt Engineering Studio

Saiba mais sobre os recursos de gerenciamento de prompts do Portkey

​
4. Guardrails para Crews Seguros

Guardrails garantem que seus agentes CrewAI operem com segurança e respondam adequadamente em todas as situações. Por que usar Guardrails? Os agentes CrewAI podem apresentar falhas de diversos tipos:
  • Gerar conteúdo nocivo ou inapropriado
  • Vazamento de informações sensíveis como PII
  • Alucinar informações incorretas
  • Gerar saídas em formatos incorretos
Os guardrails do Portkey fornecem proteções tanto para entradas quanto para saídas. Implementando Guardrails 
from crewai import Agent, LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

# Crie LLM com 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"]
        }
    )
)

# Crie agente com LLM guardrailed
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
)
Os guardrails do Portkey podem:
  • Detectar e redigir PII tanto em entradas quanto em saídas
  • Filtrar conteúdo prejudicial ou inapropriado
  • Validar formatos de resposta contra schemas
  • Verificar alucinações comparando com ground truth
  • Aplicar lógica e regras de negócio personalizadas

Saiba Mais Sobre Guardrails

Explore os recursos de guardrails do Portkey para aumentar a segurança dos agentes

​
5. Rastreamento de Usuário com Metadados

Rastreie usuários individuais através dos seus agentes CrewAI utilizando o sistema de metadados do Portkey. O que é Metadata no Portkey? Metadados permitem associar dados personalizados a cada requisição, possibilitando filtragem, segmentação e analytics. O campo especial _user é projetado especificamente para rastreamento de usuário. 
from crewai import Agent, LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

# Configure o LLM com rastreamento de usuário
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",  # Campo especial _user para analytics de usuários
            "user_tier": "premium",
            "user_company": "Acme Corp",
            "session_id": "abc-123"
        }
    )
)

# Crie agente com LLM rastreado
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
)
Filtre Analytics por Usuário Com os metadados configurados, você pode filtrar analytics por usuário e analisar métricas de desempenho individualmente:

Filtre analytics por usuário

Isso permite:
  • Rastreamento de custos e orçamento por usuário
  • Analytics personalizados por usuário
  • Métricas por equipe ou organização
  • Monitoramento específico por ambiente (homologação x produção)

Saiba Mais Sobre Metadata

Veja como usar metadados personalizados para aprimorar seus analytics

​
6. Cache para Crews Eficientes

Implemente caching para tornar seus agentes CrewAI mais eficientes e econômicos: 
from crewai import Agent, LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

# Configure o LLM com caching simples
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"
            }
        }
    )
)

# Crie agente com LLM cacheado
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
)
O caching simples realiza correspondências exatas de prompts de entrada, cacheando requisições idênticas para evitar execuções redundantes do modelo.

​
7. Interoperabilidade de Modelos

O CrewAI oferece suporte a múltiplos provedores de LLM, e o Portkey amplia essa capacidade fornecendo acesso a mais de 200 LLMs por meio de uma interface unificada. Você pode facilmente alternar entre diferentes modelos sem alterar a lógica central do seu agente: 
from crewai import Agent, LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

# Configure LLMs com diferentes provedores
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"
    )
)

# Escolha qual LLM usar para cada agente conforme necessário
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 para Anthropic
)
Portkey oferece acesso a LLMs de provedores como:
  • OpenAI (GPT-4o, GPT-4 Turbo, etc.)
  • Anthropic (Claude 3.5 Sonnet, Claude 3 Opus, etc.)
  • Mistral AI (Mistral Large, Mistral Medium, etc.)
  • Google Vertex AI (Gemini 1.5 Pro, etc.)
  • Cohere (Command, Command-R, etc.)
  • AWS Bedrock (Claude, Titan, etc.)
  • Modelos locais/privados

Provedores Suportados

Veja a lista completa de provedores LLM suportados pelo Portkey

​
Configure Governança Corporativa para o CrewAI

Por que Governança Corporativa? Se você utiliza CrewAI dentro de sua organização, é importante considerar diversos aspectos de governança:
  • Gestão de Custos: Controlar e rastrear os gastos com IA entre equipes
  • Controle de Acesso: Gerenciar quais equipes podem usar modelos específicos
  • Analytics de Uso: Compreender como a IA está sendo utilizada na organização
  • Segurança & Compliance: Manutenção de padrões corporativos de segurança
  • Confiabilidade: Garantir serviço consistente para todos os usuários
O Portkey adiciona uma camada abrangente de governança para atender a essas necessidades corporativas. Vamos implementar esses controles passo a passo.
1

Crie uma Virtual Key

Virtual Keys são a maneira segura do Portkey para gerenciar as chaves de API dos provedores de LLM. Elas fornecem controles essenciais como:
  • Limites de orçamento para uso da API
  • Capacidade de rate limiting
  • Armazenamento seguro das chaves de API
Para criar uma virtual key: Vá até Virtual Keys no app Portkey. Salve e copie o ID da virtual key
Salve o ID da sua virtual key – você precisará dele no próximo passo.
2

Crie um Config Padrão

Os Configs no Portkey definem como suas requisições são roteadas, com recursos como roteamento avançado, fallbacks e tentativas automáticas.Para criar seu config:
  1. Vá até Configs no painel Portkey
  2. Crie um novo config com: 
    {
    "virtual_key": "YOUR_VIRTUAL_KEY_FROM_STEP1",
   	"override_params": {
      "model": "gpt-4o" // Nome do seu modelo preferido
    }
}
  3. Salve e anote o nome do Config para o próximo passo
3

Configure a Chave de API Portkey

Agora crie uma chave de API Portkey e anexe a config criada no Passo 2:
  1. Vá até API Keys na Portkey e crie uma nova chave de API
  2. Selecione sua config do Passo 2
  3. Gere e salve sua chave de API
4

Conecte ao CrewAI

Após configurar sua chave de API Portkey com a config anexada, conecte-a aos seus agentes CrewAI:
from crewai import Agent, LLM
from portkey_ai import PORTKEY_GATEWAY_URL

# Configure o LLM com sua chave de API
portkey_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="YOUR_PORTKEY_API_KEY"
)

# Crie agente com LLM habilitado para Portkey
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
)

​
Recursos Corporativos Agora Disponíveis

Sua integração CrewAI agora conta com:
  • Controles de orçamento departamental
  • Governança de acesso a modelos
  • Rastreamento de uso & atribuição
  • Guardrails de segurança
  • Recursos de confiabilidade

​
Perguntas Frequentes

​
Recursos

CrewAI Docs

Documentação oficial do CrewAI

Agende uma Demonstração

Receba orientação personalizada sobre como implementar essa integração