Partilhar via

Referência da API

O DevUI fornece uma API de Respostas compatível com OpenAI, permitindo-lhe usar o SDK OpenAI ou qualquer cliente HTTP para interagir com os seus agentes e fluxos de trabalho.

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.

Base URL

http://localhost:8080/v1

A porta pode ser configurada com a --port opção CLI.

Authentication

Por defeito, o DevUI não requer autenticação para desenvolvimento local. Ao correr com --auth, é necessária a autenticação por token portador.

Usando o OpenAI SDK

Pedido Básico

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)

Serviço de streaming

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)

Conversas com múltiplos turnos

Use o parâmetro padrão OpenAI conversation para conversas com múltiplos turnos:

# 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
)

O DevUI recupera automaticamente o histórico de mensagens da conversa e passa-o para o agente.

REST API Endpoints

API de Respostas (Padrão OpenAI)

Executar um agente ou fluxo de trabalho:

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 de Conversas (Padrão OpenAI)

Ponto final Método Description
/v1/conversations Publicação Criar uma conversa
/v1/conversations/{id} Obtém Obtenha detalhes da conversa
/v1/conversations/{id} Publicação Atualizar metadados da conversa
/v1/conversations/{id} DELETE Apagar uma conversa
/v1/conversations?agent_id={id} Obtém Conversas de lista (extensão DevUI)
/v1/conversations/{id}/items Publicação Adicionar itens à conversa
/v1/conversations/{id}/items Obtém Listar itens de conversa
/v1/conversations/{id}/items/{item_id} Obtém Arranja um tema de conversa

Gestão de Entidades (Extensão DevUI)

Ponto final Método Description
/v1/entities Obtém Lista agentes/fluxos de trabalho descobertos
/v1/entities/{entity_id}/info Obtém Obtenha informações detalhadas sobre a entidade
/v1/entities/{entity_id}/reload Publicação Entidade de recarga a quente (modo programador)

Verificação de Estado de Funcionamento

curl http://localhost:8080/health

Metadados do servidor

Obtenha a configuração e capacidades dos servidores:

curl http://localhost:8080/meta

Devoluções:

  • ui_mode - Modo de corrente (developer ou user)
  • version - Versão DevUI
  • framework - Nome do framework (agent_framework)
  • runtime - Tempo de execução do backend (python)
  • capabilities - Flags de funcionalidades (rastreamento, proxy OpenAI, deployment)
  • auth_required - Se a autenticação está ativada

Mapeamento de Eventos

O DevUI mapeia eventos do Agent Framework para eventos da API OpenAI Responses. A tabela abaixo mostra o mapeamento:

Eventos do Ciclo de Vida

Evento OpenAI Evento do Quadro de Agentes
response.created + response.in_progress AgentStartedEvent
response.completed AgentCompletedEvent
response.failed AgentFailedEvent
response.created + response.in_progress WorkflowStartedEvent
response.completed WorkflowCompletedEvent
response.failed WorkflowFailedEvent

Tipos de conteúdo

Evento OpenAI Conteúdo do Agent Framework
response.content_part.added + response.output_text.delta TextContent
response.reasoning_text.delta TextReasoningContent
response.output_item.added FunctionCallContent (inicial)
response.function_call_arguments.delta FunctionCallContent (args)
response.function_result.complete FunctionResultContent
response.output_item.added (imagem) DataContent (imagens)
response.output_item.added (ficheiro) DataContent (ficheiros)
error ErrorContent

Eventos de Fluxo de Trabalho

Evento OpenAI Evento do Quadro de Agentes
response.output_item.added (ExecutorAçãoItem) WorkflowEvent com type="executor_invoked"
response.output_item.done (ExecutorAçãoItem) WorkflowEvent com type="executor_completed"
response.output_item.added (MensagemRespostaSaída) WorkflowEvent com type="output"

Extensões Personalizadas DevUI

O DevUI adiciona tipos de eventos personalizados para funcionalidades específicas do Agent Framework:

  • response.function_approval.requested - Pedidos de aprovação de funções
  • response.function_approval.responded - Respostas de aprovação de funções
  • response.function_result.complete - Resultados de execução de funções do lado do servidor
  • response.workflow_event.complete - Eventos de fluxo de trabalho
  • response.trace.complete - Traços de execução

Estas extensões personalizadas têm namespaces e podem ser ignoradas em segurança pelos clientes OpenAI padrão.

Modo Proxy OpenAI

O DevUI fornece uma funcionalidade OpenAI Proxy para testar modelos OpenAI diretamente através da interface, sem criar agentes personalizados. Ativar através das Definições na interface.

curl -X POST http://localhost:8080/v1/responses \
  -H "X-Proxy-Backend: openai" \
  -d '{"model": "gpt-4.1-mini", "input": "Hello"}'

Observação

O modo proxy requer OPENAI_API_KEY variáveis de ambiente configuradas no backend.

Próximas Etapas

  • Last updated on