DevUI는 OpenAI 호환 응답 API를 제공하므로 OpenAI SDK 또는 HTTP 클라이언트를 사용하여 에이전트 및 워크플로와 상호 작용할 수 있습니다.
준비 중
C#용 DevUI 설명서는 곧 제공될 예정입니다. 나중에 다시 확인하거나 개념 지침은 Python 설명서를 참조하세요.
기본 URL
http://localhost:8080/v1
포트는 CLI 옵션을 사용하여 --port 구성할 수 있습니다.
Authentication
기본적으로 DevUI는 로컬 개발에 인증이 필요하지 않습니다. 실행 --auth중인 경우 전달자 토큰 인증이 필요합니다.
OpenAI SDK 사용
기본 요청
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8080/v1",
api_key="not-needed" # API key not required for local DevUI
)
response = client.responses.create(
metadata={"entity_id": "weather_agent"}, # Your agent/workflow name
input="What's the weather in Seattle?"
)
# Extract text from response
print(response.output[0].content[0].text)
스트리밍
response = client.responses.create(
metadata={"entity_id": "weather_agent"},
input="What's the weather in Seattle?",
stream=True
)
for event in response:
# Process streaming events
print(event)
다중 턴 대화
다중 턴 대화에 표준 OpenAI conversation 매개 변수를 사용합니다.
# Create a conversation
conversation = client.conversations.create(
metadata={"agent_id": "weather_agent"}
)
# First turn
response1 = client.responses.create(
metadata={"entity_id": "weather_agent"},
input="What's the weather in Seattle?",
conversation=conversation.id
)
# Follow-up turn (continues the conversation)
response2 = client.responses.create(
metadata={"entity_id": "weather_agent"},
input="How about tomorrow?",
conversation=conversation.id
)
DevUI는 대화의 메시지 기록을 자동으로 검색하여 에이전트에 전달합니다.
REST API 엔드포인트
응답 API(OpenAI Standard)
에이전트 또는 워크플로 실행:
curl -X POST http://localhost:8080/v1/responses \
-H "Content-Type: application/json" \
-d '{
"metadata": {"entity_id": "weather_agent"},
"input": "What is the weather in Seattle?"
}'
대화 API(OpenAI Standard)
| 엔드포인트 | 메서드 | Description |
|---|---|---|
/v1/conversations |
POST | 대화 만들기 |
/v1/conversations/{id} |
가져오기 | 대화 세부 정보 가져오기 |
/v1/conversations/{id} |
POST | 대화 메타데이터 업데이트 |
/v1/conversations/{id} |
삭제 | 대화 삭제 |
/v1/conversations?agent_id={id} |
가져오기 | 대화 나열(DevUI 확장) |
/v1/conversations/{id}/items |
POST | 대화에 항목 추가 |
/v1/conversations/{id}/items |
가져오기 | 대화 항목 나열 |
/v1/conversations/{id}/items/{item_id} |
가져오기 | 대화 항목 가져오기 |
엔터티 관리(DevUI 확장)
| 엔드포인트 | 메서드 | Description |
|---|---|---|
/v1/entities |
가져오기 | 검색된 에이전트/워크플로 나열 |
/v1/entities/{entity_id}/info |
가져오기 | 자세한 엔터티 정보 가져오기 |
/v1/entities/{entity_id}/reload |
POST | 핫 다시 로드 엔터티(개발자 모드) |
상태 확인
curl http://localhost:8080/health
서버 메타데이터
서버 구성 및 기능 가져오기:
curl http://localhost:8080/meta
반환 값:
-
ui_mode- 현재 모드(developer또는user) -
version- DevUI 버전 -
framework- 프레임워크 이름(agent_framework) -
runtime- 백 엔드 런타임(python) -
capabilities- 기능 플래그(추적, OpenAI 프록시, 배포) -
auth_required- 인증 사용 여부
이벤트 매핑
DevUI는 에이전트 프레임워크 이벤트를 OpenAI 응답 API 이벤트에 매핑합니다. 아래 표에서는 매핑을 보여줍니다.
수명 주기 이벤트
| OpenAI 이벤트 | Agent Framework 이벤트 |
|---|---|
response.created + response.in_progress |
AgentStartedEvent |
response.completed |
AgentCompletedEvent |
response.failed |
AgentFailedEvent |
response.created + response.in_progress |
WorkflowStartedEvent |
response.completed |
WorkflowCompletedEvent |
response.failed |
WorkflowFailedEvent |
콘텐츠 형식
| OpenAI 이벤트 | 에이전트 프레임워크 콘텐츠 |
|---|---|
response.content_part.added + response.output_text.delta |
TextContent |
response.reasoning_text.delta |
TextReasoningContent |
response.output_item.added |
FunctionCallContent (초기) |
response.function_call_arguments.delta |
FunctionCallContent (인수) |
response.function_result.complete |
FunctionResultContent |
response.output_item.added (이미지) |
DataContent (이미지) |
response.output_item.added (파일) |
DataContent (파일) |
error |
ErrorContent |
워크플로 이벤트
| OpenAI 이벤트 | Agent Framework 이벤트 |
|---|---|
response.output_item.added (ExecutorActionItem) |
WorkflowEvent와 type="executor_invoked" |
response.output_item.done (ExecutorActionItem) |
WorkflowEvent와 type="executor_completed" |
response.output_item.added (ResponseOutputMessage) |
WorkflowEvent와 type="output" |
DevUI 사용자 지정 확장
DevUI는 에이전트 프레임워크 관련 기능에 대한 사용자 지정 이벤트 유형을 추가합니다.
-
response.function_approval.requested- 함수 승인 요청 -
response.function_approval.responded- 함수 승인 응답 -
response.function_result.complete- 서버 쪽 함수 실행 결과 -
response.workflow_event.complete- 워크플로 이벤트 -
response.trace.complete- 실행 추적
이러한 사용자 지정 확장은 이름 간격으로 지정되며 표준 OpenAI 클라이언트에서 안전하게 무시할 수 있습니다.
OpenAI 프록시 모드
DevUI는 사용자 지정 에이전트를 만들지 않고 인터페이스를 통해 직접 OpenAI 모델을 테스트하기 위한 OpenAI 프록시 기능을 제공합니다. UI의 설정을 통해 사용하도록 설정합니다.
curl -X POST http://localhost:8080/v1/responses \
-H "X-Proxy-Backend: openai" \
-d '{"model": "gpt-4.1-mini", "input": "Hello"}'
비고
프록시 모드에는 OPENAI_API_KEY 백 엔드에 구성된 환경 변수가 필요합니다.
다음 단계
- 추적 및 관찰 가능성 - 디버깅을 위한 추적 보기
- 보안 및 배포 - DevUI 배포 보안