Segurança e Implantação

O DevUI foi concebido como uma aplicação de exemplo para desenvolvimento local. Esta página aborda considerações de segurança e melhores práticas caso precise de expor o DevUI para além do localhost.

Warning

O DevUI não é destinado a uso em produção. Para implementações em produção, construa a sua própria interface personalizada usando o Agent Framework SDK com as medidas de segurança adequadas.

Brevemente

A documentação DevUI para C# está a chegar em breve. Por favor, volte a consultar mais tarde ou consulte a documentação em Python para orientações conceptuais.

Modos UI

O DevUI oferece dois modos que controlam o acesso às funcionalidades:

Modo Desenvolvedor (Predefinido)

Acesso total a todas as funcionalidades:

  • Painel de depuração com informação de rastreio
  • Recarregamento a quente para desenvolvimento rápido (/v1/entities/{id}/reload)
  • Ferramentas de implantação (/v1/deployments)
  • Mensagens de erro verbosas para depuração
devui ./agents  # Developer mode is the default

Modo Utilizador

Interface simplificada e restrita:

  • Interface de chat e gestão de conversas
  • Listagem da entidade e informações básicas
  • APIs de desenvolvedor desativadas (recarregamento a quente, implementação)
  • Mensagens de erro genéricas (detalhes registados do lado do servidor)
devui ./agents --mode user

Authentication

A autenticação por token Bearer está ativada por defeito. Para um bind de loopback, o DevUI gera um token e exibe-o na consola:

devui ./agents

Para um token repetível, defina DEVUI_AUTH_TOKEN ou use --auth-token. Uma ligação sem loopback requer um token explícito e falha de forma segura sem um:

# Custom token via CLI
devui ./agents --auth-token "your-secure-token"

# Custom token via environment variable
export DEVUI_AUTH_TOKEN="your-secure-token"
devui ./agents --host 0.0.0.0

Todos os pedidos de API devem incluir o token no Authorization cabeçalho:

curl http://localhost:8080/v1/entities \
  -H "Authorization: Bearer your-secure-token"

Utilize --no-auth apenas para desenvolvimento de loopback isolado. O DevUI rejeita binds não autenticados que não sejam de loopback, e até o modo loopback sem autenticação remove a proteção contra pedidos enviados por sites hostis.

Se precisares de expor o DevUI aos utilizadores finais (não recomendado para produção):

DEVUI_AUTH_TOKEN="<secure-dev-token>" devui ./agents --mode user --host 0.0.0.0

Esta configuração:

  • Restringe APIs direcionadas para programadores
  • Necessita de autenticação
  • Liga-se a todas as interfaces de rede

Elementos de Segurança

O DevUI inclui várias medidas de segurança:

Feature Descrição
Ligação localhost Vincula a 127.0.0.1 por padrão
Modo de utilizador Restringe APIs para programadores
Authentication A autenticação por token Bearer é ativada por defeito
Modo sem autenticação Permitido apenas em localhost ou 127.0.0.1
Associações de rede Requer DEVUI_AUTH_TOKEN ou --auth-token
Carregamento de entidades locais Só carrega entidades a partir de diretórios locais ou em memória
Sem execução remota Sem capacidades remotas de execução de código

Melhores práticas

Gestão de Credenciais

  • Armazenar chaves API e segredos em .env ficheiros
  • Nunca submeta .env ficheiros para o controlo de versões
  • Usar .env.example ficheiros para documentar as variáveis necessárias
# .env.example (safe to commit)
OPENAI_API_KEY=your-api-key-here
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/

# .env (never commit)
OPENAI_API_KEY=sk-actual-key
AZURE_OPENAI_ENDPOINT=https://my-resource.openai.azure.com/

Segurança de Rede

  • Mantenha o DevUI ligado ao localhost para desenvolvimento
  • Use um reverse proxy (nginx, Caddy) se for necessário acesso externo
  • Ativar o HTTPS através do reverse proxy
  • Implementar autenticação adequada ao nível do proxy

Segurança de Entidades

  • Revê todo o código dos agentes/workflows antes de correr
  • Só carregue entidades de fontes confiáveis
  • Tem cuidado com ferramentas que tenham efeitos secundários (acesso a ficheiros, chamadas de rede)

Limpeza de Recursos

Registo ganchos de limpeza para fechar corretamente credenciais e recursos durante o encerramento:

import os
from azure.identity.aio import DefaultAzureCredential
from agent_framework import Agent
from agent_framework.openai import OpenAIChatCompletionClient
from agent_framework_devui import register_cleanup, serve

credential = DefaultAzureCredential()
client = OpenAIChatCompletionClient(
    model=os.environ["AZURE_OPENAI_CHAT_COMPLETION_MODEL"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
    credential=credential,
)
agent = Agent(name="MyAgent", client=client)

# Register cleanup hook - credential will be closed on shutdown
register_cleanup(agent, credential.close)
serve(entities=[agent])

Considerações sobre as Ferramentas MCP

Ao usar ferramentas MCP (Model Context Protocol) com DevUI:

# Correct - DevUI handles cleanup automatically
mcp_tool = MCPStreamableHTTPTool(url="http://localhost:8011/mcp", client=chat_client)
agent = Agent(tools=mcp_tool)
serve(entities=[agent])

Importante

Não uses async with gestores de contexto ao criar agentes com ferramentas MCP para DevUI. As ligações serão encerradas antes da execução. As ferramentas MCP usam inicialização preguiçosa e ligam-se automaticamente à primeira utilização.

Observação

O suporte para esta funcionalidade do go está a chegar em breve. Consulte o repositório Agent Framework Go para o estado mais recente.

Próximas Etapas

  • Exemplos - Navegue por agentes e fluxos de trabalho de exemplo
  • Referência API - Saiba mais sobre os endpoints da API
  • Última atualização a