Pi Agent: Configuration Deep Dive

Q: P: O que deve ser configurado obrigatoriamente?

R: Apenas a chave API (providers. .api_key). Todo o resto tem padrões. Modelos locais nem precisam de chave. P: Conflito entre configuração de projeto e global? R: Configuração de projeto vence — "princípio de proximidade": projeto > usuário > padrões globais. P: Posso fazer commit da configuração no Git? R: Configuração de projeto (.pi-agent.yaml) sim, mas não inclua chaves API. Use variáveis de ambiente para segredos.

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

--- title: "Configuracao Avancada" description: "Guia completo do sistema de configuracao do Pi Agent, incluindo estrutura de arquivos, substituicao de camadas, variaveis de ambiente e configuracao dinamica." order: 12 lang: pt-br

Configuração é o "painel de controle" do Pi Agent — entenda-o para ajustar cada parâmetro.

1. Camadas de Configuração

Prioridade de configuração do Pi Agent, da menor para a maior:

TEXT 📖 Somente leitura

Defaults → Global Config → Project Config → Env Vars → Code Params → CLI Params
  (lowest)                                                    (highest)

Prioridade maior sobrepõe a menor.

2. Configuração Global

Localização: ~/.pi-agent/config.yaml

YAML

default_provider: deepseek
default_model: deepseek-chat

providers:
  deepseek:
    api_key: "sk-xxxxxxxx"
    base_url: "https://api.deepseek.com"
    model: "deepseek-chat"
    temperature: 0.7
    max_tokens: 4096

  openai:
    api_key: "sk-xxxxxxxx"
    model: "gpt-4o"

display:
  theme: dark
  code_highlight: true
  show_token_count: true

session:
  auto_save: true
  save_dir: "~/.pi-agent/sessions"

templates_dir: "~/.pi-agent/templates"
skills_dir: "~/.pi-agent/skills"

3. Configuração de Projeto

Localização: .pi-agent.yaml na raiz do projeto

YAML

project:
  name: "my_fastapi_app"
  description: "FastAPI project"

agent:
  system_prompt: "You are the dedicated assistant for this FastAPI project"
  tools:
    - file_reader
    - shell
    - search

context:
  inject:
    - "README.md"
    - "requirements.txt"

providers:
  deepseek:
    temperature: 0.3

4. Variáveis de Ambiente

Todos os itens de configuração têm variáveis de ambiente correspondentes com o prefixo PI_:

Item de Configuração	Variável de Ambiente
providers.deepseek.api_key	PI_DEEPSEEK_API_KEY
default_provider	PI_DEFAULT_PROVIDER
display.theme	PI_DISPLAY_THEME
session.auto_save	PI_SESSION_AUTO_SAVE
agent.temperature	PI_AGENT_TEMPERATURE

5. Configuração no Código

PYTHON

from pi_agent import Agent

agent = Agent(
    name="custom",
    provider="deepseek",
    model="deepseek-chat",
    temperature=0.5,
    max_tokens=2048,
    tools=["search", "calculator"],
    system_prompt="You are a math assistant",
    context_window=8192,
    truncation_strategy="summarize",
    auto_save=True
)

6. Configuração Dinâmica

Modifique a configuração em tempo de execução:

PYTHON

agent.configure(model="deepseek-reasoner", temperature=0.2)
agent.enable_tool("shell")
agent.disable_tool("search")
agent.set_system_prompt("You are now a strict security reviewer")

7. Referência de Configuração

Categoria	Item	Padrão	Descrição
Agent	name	"agent"	Nome do Agent
Agent	system_prompt	""	Prompt do sistema
Agent	temperature	0.7	Temperatura
Agent	max_tokens	4096	Máximo de tokens de saída
Agent	context_window	8192	Janela de contexto
Agent	truncation_strategy	"remove_oldest"	Estratégia de truncamento
Provider	api_key	""	Chave API
Provider	base_url	""	URL base da API
Provider	model	""	Nome do modelo
Display	theme	"dark"	Tema da UI
Session	auto_save	false	Salvamento automático de sessões

❓ Perguntas Frequentes

P: O que deve ser configurado obrigatoriamente? R: Apenas a chave API (providers.<name>.api_key). Todo o resto tem padrões. Modelos locais nem precisam de chave. P: Conflito entre configuração de projeto e global? R: Configuração de projeto vence — "princípio de proximidade": projeto > usuário > padrões globais. P: Posso fazer commit da configuração no Git? R: Configuração de projeto (.pi-agent.yaml) sim, mas não inclua chaves API. Use variáveis de ambiente para segredos.

❓ Resumo

Prioridade: padrões < global < projeto < variáveis de ambiente < código < CLI
Global: ~/.pi-agent/config.yaml; Projeto: .pi-agent.yaml
Variáveis de ambiente: PI_ + nome da chave em maiúsculo
Configuração dinâmica em tempo de execução suportada
Chaves API via variáveis de ambiente, nunca faça commit no Git

📝 Exercícios

Básico (Dificuldade: ⭐): Crie um arquivo de configuração global com pelo menos um provedor de LLM.
Intermediário (Dificuldade: ⭐⭐): Crie .pi-agent.yaml para seu projeto com system prompt e ferramentas personalizados.
Avançado (Dificuldade: ⭐⭐⭐): Escreva um script de validação de configuração que verifique completude e consistência.

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.

Sobre Nós