English 中文 العربية 日本語 Português

Pi Agent: Troubleshooting & AI Providers

Última atualização: 2026-08-31

--- title: "Solucao de Problemas e Provedores de IA" description: "Guia de solucao de problemas do Pi Agent e referencia completa de configuracao para todos os provedores de IA suportados." order: 20 lang: pt-br

Não entre em pânico quando as coisas quebram — 90% dos problemas podem ser resolvidos nesta página.

1. Solução de Problemas Comuns

(1) Problemas de Instalação

Problema Causa Solução
pip install falha Versão antiga do pip pip install --upgrade pip
Timeout de rede Problemas de rede Use mirror: -i https://pypi.tuna.tsinghua.edu.cn/simple
Erro de compilação Ferramentas de build ausentes Instale build-essential (Linux) ou VS Build Tools (Windows)
Erro de permissão Instalação global precisa de root Use --user ou virtualenv

(2) Problemas de Chamada de API

Código de Erro Significado Solução
401 Falha de autenticação Verifique a chave API
429 Limite de taxa atingido Reduza frequência de requisições ou atualize o plano
500 Erro do servidor Tente novamente mais tarde
503 Serviço indisponível Verifique a página de status do provedor

(3) Problemas de Chamada de Ferramentas

Problema Causa Solução
Ferramenta sem resposta Permissões insuficientes Verifique nível de confiança e permissões de ferramentas
Timeout da ferramenta Execução muito longa Aumente max_execution_time
Resultado vazio Parâmetros de entrada ruins Verifique tipos e formato dos parâmetros
Arquivo não encontrado Caminho errado Use caminhos absolutos

2. Dicas de Depuração

(1) Habilitar Modo Debug

BASH 
pi-agent chat --debug
PYTHON 
agent = Agent(name="debug", debug=True)

(2) Logging Detalhado

PYTHON 
import logging
logging.basicConfig(level=logging.DEBUG)

agent = Agent(name="debug")
agent.chat("Test message")

(3) Rastreamento de Eventos

PYTHON 
@agent.on("*")
def trace(event):
    print(f"[{event.timestamp}] {event.name}: {event.data}")

3. Referência de Provedores de IA

(1) DeepSeek

YAML 
providers:
  deepseek:
    api_key: "sk-xxxxxxxx"
    base_url: "https://api.deepseek.com"
    models:
      - name: deepseek-chat
        context: 64000
        input_price: 1.0
        output_price: 2.0
      - name: deepseek-reasoner
        context: 64000
        input_price: 4.0
        output_price: 16.0

(2) OpenAI

YAML 
providers:
  openai:
    api_key: "sk-xxxxxxxx"
    base_url: "https://api.openai.com/v1"
    models:
      - name: gpt-4o
        context: 128000
        input_price: 2.5
        output_price: 10.0
      - name: gpt-4o-mini
        context: 128000
        input_price: 0.15
        output_price: 0.6

(3) Anthropic

YAML 
providers:
  anthropic:
    api_key: "sk-ant-xxxxxxxx"
    base_url: "https://api.anthropic.com"
    models:
      - name: claude-sonnet-4-20250514
        context: 200000
        input_price: 3.0
        output_price: 15.0
      - name: claude-3-5-haiku-20241022
        context: 200000
        input_price: 0.8
        output_price: 4.0

(4) Google Gemini

YAML 
providers:
  gemini:
    api_key: "AIzaxxxxxxxx"
    base_url: "https://generativelanguage.googleapis.com/v1beta"
    models:
      - name: gemini-2.0-flash
        context: 1048576
        input_price: 0.1
        output_price: 0.4

(5) llama.cpp

YAML 
providers:
  local:
    type: llama_cpp
    model_path: "./models/qwen2.5-7b-instruct-q4_k_m.gguf"
    n_gpu_layers: -1
    n_ctx: 4096

(6) Ollama

YAML 
providers:
  ollama:
    type: ollama
    base_url: "http://localhost:11434"
    model: "qwen2.5:7b"

4. Otimização de Desempenho

PYTHON 
agent = Agent(
    max_tokens=2048,
    temperature=0.3,
    context_window=4096,
    provider="deepseek",
    auto_summarize=True
)

5. Verificação de Saúde

Exemplo 1: Script de Diagnóstico (Dificuldade: ⭐)

PYTHON 
from pi_agent import Config, Agent

print("=== Pi Agent Diagnostics ===")

config = Config.load()
print(f"Config: {'OK' if config else 'Not found'}")

for name, provider in config.providers.items():
    try:
        agent = Agent(provider=name)
        agent.chat("ping")
        print(f"Provider {name}: OK")
    except Exception as e:
        print(f"Provider {name}: FAIL ({e})")

print("=== Diagnostics Complete ===")

❓ Perguntas Frequentes

P: Agent nunca responde? R: Verifique rede, validade da chave API, status do serviço do provedor. Habilite modo debug para logs detalhados de requisição. P: Permissão de chamada de ferramenta negada? R: Verifique o nível de confiança do projeto. shell e file_write precisam de nível trusted ou restricted. P: Trocar para modelo mais barato? R: Interativo: /model gpt-4o-mini. Código: Agent(model="deepseek-chat"). Config: altere default_model.

❓ Resumo

📝 Exercícios

  1. Básico (Dificuldade: ⭐): Execute o script de verificação de saúde, confirme que seu ambiente está corretamente configurado.
  2. Intermediário (Dificuldade: ⭐⭐): Configure dois provedores, escreva código para failover automático para o provedor backup.
  3. Avançado (Dificuldade: ⭐⭐⭐): Implemente uma solução de monitoramento completa: verificações periódicas de provedores, rastreamento de latência de resposta, tendências de uso de tokens, alertas em anomalias.
Web-Tutorial.com

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

100%