Segurança e Implantação

O DevUI foi projetado como um aplicativo de exemplo para desenvolvimento local. Esta página aborda considerações de segurança e práticas recomendadas se você precisar expor o DevUI além do localhost.

Aviso

O DevUI não se destina ao uso de produção. Para implantações de produção, crie sua própria interface personalizada usando o SDK do Agent Framework com as medidas de segurança apropriadas.

Em breve

A documentação do DevUI para C# estará disponível em breve. Verifique novamente mais tarde ou consulte a documentação do Python para obter diretrizes conceituais.

Modos de interface do usuário

O DevUI oferece dois modos que controlam o acesso aos recursos:

Modo de desenvolvedor (padrão)

Acesso completo a todos os recursos:

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

Modo de Usuário

Interface simplificada e restrita:

  • Gerenciamento de conversa e interface de chat
  • Listagem de entidades e informações básicas
  • APIs de desenvolvedor desabilitadas (recarregamento frequente, implantação)
  • Mensagens de erro genéricas (detalhes registrados no lado do servidor)
devui ./agents --mode user

Authentication

A autenticação por token Bearer está habilitada por padrão. Para uma vinculação de loopback, o DevUI gera um token e o exibe no console:

devui ./agents

Para um token repetível, defina DEVUI_AUTH_TOKEN ou use --auth-token. Uma associação sem loopback requer um token explícito e falha de modo restritivo caso não tenha 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

Todas as solicitações de API devem incluir o token no Authorization cabeçalho:

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

Use --no-auth somente para desenvolvimento de loopback isolado. O DevUI rejeita binds não autenticados que não sejam de loopback, e até mesmo o modo sem autenticação de loopback remove a proteção contra solicitações enviadas por sites hostis.

Se você precisar expor o DevUI aos usuários 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 voltadas para o desenvolvedor
  • Requer autenticação
  • Associa a todas as interfaces de rede

Recursos de segurança

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

Feature Description
Vinculação de localhost Associa a 127.0.0.1 por padrão
Modo de usuário Restringe APIs de desenvolvedor
Authentication A autenticação por Bearer token está habilitada por padrão
Modo sem autenticação Permitido somente em localhost ou 127.0.0.1
Associações de rede Requer DEVUI_AUTH_TOKEN ou --auth-token
Carregamento de entidade local Carrega entidades apenas de diretórios locais ou da memória
Nenhuma execução remota Sem recursos de execução de código remoto

Práticas recomendadas

Gerenciamento de credenciais

  • Armazenar chaves de API e segredos em .env arquivos
  • Nunca confirme os arquivos .env no controle de versão
  • Usar .env.example arquivos para documentar 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

  • Manter o DevUI associado ao localhost para desenvolvimento
  • Use um proxy reverso (nginx, Caddy) se o acesso externo for necessário
  • Habilitar HTTPS por meio do proxy reverso
  • Implementar a autenticação adequada no nível do proxy

Segurança de entidade

  • Examinar todo o código do agente/fluxo de trabalho antes de executar
  • Carregar apenas entidades de fontes confiáveis
  • Tenha cuidado com ferramentas que têm efeitos colaterais (acesso a arquivos, chamadas de rede)

Limpeza de Recursos

Registre ganchos de limpeza para fechar corretamente as credenciais e os recursos no desligamento:

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 ferramentas do 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])

Important

Não use async with gerentes de contexto ao criar agentes com ferramentas MCP para DevUI. As conexões serão fechadas antes da execução. As ferramentas MCP usam inicialização lenta e se conectam automaticamente no primeiro uso.

Note

O suporte para Go a este recurso estará disponível em breve. Consulte o repositório Agent Framework Go para obter o status mais recente.

Próximas etapas

  • Exemplos – Navegar por agentes de exemplo e fluxos de trabalho
  • Referência de API – Saiba mais sobre os pontos de extremidade da API
  • Última atualização em