DevUI는 로컬 개발을 위한 샘플 애플리케이션으로 설계되었습니다. 이 페이지에서는 localhost 이외의 DevUI를 노출해야 하는 경우 보안 고려 사항 및 모범 사례를 설명합니다.
Warning
DevUI는 프로덕션용이 아닙니다. 프로덕션 배포의 경우 적절한 보안 조치와 함께 Agent Framework SDK를 사용하여 고유한 사용자 지정 인터페이스를 빌드합니다.
곧 출시
C#용 DevUI 설명서는 곧 제공될 예정입니다. 나중에 다시 확인하거나 개념 지침은 Python 설명서를 참조하세요.
사용자 인터페이스 모드
DevUI는 기능에 대한 액세스를 제어하는 두 가지 모드를 제공합니다.
개발자 모드(기본값)
모든 기능에 대한 모든 액세스 권한:
- 추적 정보가 있는 디버그 패널
- 빠른 개발을 위한 핫 리로드(
/v1/entities/{id}/reload) - 배포 도구(
/v1/deployments) - 디버깅을 위한 자세한 오류 메시지
devui ./agents # Developer mode is the default
사용자 모드
간소화되고 제한된 인터페이스:
- 채팅 인터페이스 및 대화 관리
- 엔터티 목록 및 기본 정보
- 개발자 API 사용 안 함(핫 재로드, 배포 작업)
- 일반 오류 메시지 (기록된 세부 정보는 서버 측에)
devui ./agents --mode user
Authentication
Bearer 토큰 인증은 기본적으로 사용하도록 설정됩니다. 루프백 바인드의 경우 DevUI는 토큰을 생성하고 콘솔에 표시합니다.
devui ./agents
반복 가능한 토큰의 경우 DEVUI_AUTH_TOKEN를 설정하거나 --auth-token를 사용하세요. 루프백이 아닌 바인딩에는 명시적 토큰이 필요하며, 토큰이 없으면 닫힌 상태로 실패합니다.
# 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
모든 API 요청에는 Authorization 헤더에 토큰이 포함되어야 합니다.
curl http://localhost:8080/v1/entities \
-H "Authorization: Bearer your-secure-token"
격리된 루프백 개발에만 사용합니다 --no-auth . DevUI는 인증되지 않은 비루프백 바인딩을 거부하며, 루프백 no-auth 모드조차도 적대적인 웹 사이트에서 보낸 요청으로부터의 보호를 제거합니다.
권장 배포 구성
최종 사용자에게 DevUI를 노출해야 하는 경우(프로덕션에는 권장되지 않음):
DEVUI_AUTH_TOKEN="<secure-dev-token>" devui ./agents --mode user --host 0.0.0.0
이 구성은 다음과 같습니다.
- 개발자용 API 제한
- 인증 필요
- 모든 네트워크 인터페이스에 바인딩
보안 기능
DevUI에는 다음과 같은 몇 가지 보안 조치가 포함되어 있습니다.
| 특징 | 설명 |
|---|---|
| Localhost 바인딩 | 기본적으로 127.0.0.1에 바인딩 |
| 사용자 모드 | 개발자 API 제한 |
| Authentication | Bearer 토큰 인증은 기본적으로 사용하도록 설정됩니다 |
| 인증 없음 모드 |
localhost 또는 127.0.0.1에서만 허용됩니다 |
| 네트워크 바인드 |
DEVUI_AUTH_TOKEN 또는 --auth-token 필요 |
| 로컬 엔터티 로딩 | 로컬 디렉터리 또는 메모리 내 엔터티만 로드합니다. |
| 원격 실행 없음 | 원격 코드 실행 기능 없음 |
모범 사례
자격 증명 관리
- API 키 및 비밀을
.env파일에 저장 - 소스 제어에
.env파일을 커밋하지 마세요. - 파일을 사용하여
.env.example필수 변수 문서화
# .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/
네트워크 보안
- 개발용 Localhost에 바인딩된 DevUI 유지
- 외부 액세스가 필요한 경우 역방향 프록시(nginx, Caddy)를 사용합니다.
- 역방향 프록시를 통해 HTTPS 사용
- 프록시 수준에서 적절한 인증 구현
엔터티 보안
- 실행하기 전에 모든 에이전트/워크플로 코드 검토
- 신뢰할 수 있는 원본에서만 엔터티를 로드하십시오
- 부작용이 있는 도구(파일 액세스, 네트워크 호출)에 주의하세요.
리소스 정리
종료할 때 자격 증명 및 리소스를 제대로 닫기 위해 정리 훅을 등록합니다.
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])
MCP 도구 고려 사항
DevUI에서 MCP(모델 컨텍스트 프로토콜) 도구를 사용하는 경우:
# Correct - DevUI handles cleanup automatically
mcp_tool = MCPStreamableHTTPTool(url="http://localhost:8011/mcp", client=chat_client)
agent = Agent(tools=mcp_tool)
serve(entities=[agent])
중요합니다
DevUI용 MCP 도구를 사용하여 에이전트를 만들 때 컨텍스트 관리자를 사용하지 async with 마세요. 실행하기 전에 연결이 닫힙니다. MCP 도구는 지연 초기화를 사용하고 처음 사용할 때 자동으로 연결합니다.
비고
이 기능에 대한 지원은 곧 제공될 예정입니다. 최신 상태는 에이전트 프레임워크 Go 리포지토리 를 참조하세요.