Testando com AG-UI Dojo

O aplicativoAG-UI Dojo fornece um ambiente interativo para testar e explorar agentes do Microsoft Agent Framework que implementam o protocolo AG-UI. O Dojo oferece uma interface visual para se conectar aos seus agentes e interagir com todos os 7 recursos AG-UI.

Pré-requisitos

Antes de começar, verifique se você tem:

• Python 3.10 ou superior
• uv para gerenciamento de dependência
• Uma chave de API OpenAI ou um ponto de extremidade do Azure OpenAI
• Node.js e pnpm (para executar o front-end do Dojo)

Installation

1. Clonar o repositório de AG-UI

Primeiro, clone o repositório AG-UI que contém o aplicativo Dojo e os exemplos de integração do Microsoft Agent Framework:

git clone https://github.com/ag-oss/ag-ui.git
cd ag-ui

2. Navegue até o Diretório de Exemplos

cd integrations/microsoft-agent-framework/python/examples

3. Instalar dependências do Python

Use uv para instalar as dependências necessárias:

uv sync

4. Configurar variáveis de ambiente

Crie um .env arquivo com base no modelo fornecido:

cp .env.example .env

Edite o .env arquivo e adicione suas credenciais de API:

# For OpenAI
OPENAI_API_KEY=your_api_key_here
OPENAI_CHAT_MODEL_ID="gpt-4.1"

# Or for Azure OpenAI
AZURE_OPENAI_ENDPOINT=your_endpoint_here
AZURE_OPENAI_API_KEY=your_api_key_here
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=your_deployment_here

Observação

Se estiver usando DefaultAzureCredential, no lugar de api_key para autenticação, certifique-se de estar autenticado no Azure (por exemplo, via az login). Para obter mais informações, consulte a documentação da Identidade do Azure.

Executando o aplicativo Dojo

1. Iniciar o servidor de back-end

No diretório de exemplos, inicie o servidor de back-end com os agentes de exemplo:

cd integrations/microsoft-agent-framework/python/examples
uv run dev

O servidor, por padrão, será iniciado em http://localhost:8888.

2. Iniciar o front-end do Dojo

Abra uma nova janela de terminal, navegue até a raiz do repositório AG-UI e, em seguida, para o diretório de aplicativos do Dojo:

cd apps/dojo
pnpm install
pnpm dev

O front-end do Dojo estará disponível em http://localhost:3000.

3. Conectar-se ao seu agente

1. Abrir http://localhost:3000 no navegador

2. Configurar a URL do servidor para http://localhost:8888

3. Selecione "Microsoft Agent Framework (Python)" na lista suspensa

4. Comece a explorar os agentes de exemplo

Agentes de exemplo disponíveis

Os exemplos de integração demonstram todos os 7 recursos AG-UI por meio de pontos de extremidade de agente diferentes:

Ponto final	Característica	Description
/agentic_chat	Recurso 1: Chat Agênico	Agente conversacional básico com chamada de ferramenta
/backend_tool_rendering	Recurso 2: Renderização da Ferramenta Backend	Agente com renderização da interface de usuário de ferramenta customizada
/human_in_the_loop	Recurso 3: Humano no Loop	Agente com fluxos de trabalho de aprovação
/agentic_generative_ui	Recurso 4: UI Generativa Agente	Agente que divide tarefas em etapas com atualizações em fluxo contínuo
/tool_based_generative_ui	Recurso 5: interface do usuário generativa baseada em ferramentas	Agente que gera componentes de interface do usuário personalizados
/shared_state	Recurso 6: Estado Compartilhado	Agente com sincronização de estado bidirecional
/predictive_state_updates	Recurso 7: Atualizações de Estado Preditivo	Agente com atualizações de estado preditivo durante a execução da ferramenta

Testando seus próprios agentes

Para testar seus próprios agentes com o Dojo:

1. Criar seu agente

Crie um novo agente seguindo o guia de Introdução :

from agent_framework import Agent
from agent_framework_azure_ai import AzureOpenAIChatClient

# Create your agent
chat_client = AzureOpenAIChatClient(
    endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    deployment_name=os.getenv("AZURE_OPENAI_CHAT_DEPLOYMENT_NAME"),
)

agent = Agent(
    name="my_test_agent",
    chat_client=chat_client,
    system_message="You are a helpful assistant.",
)

2. Adicionar o agente ao servidor

Na sua aplicação FastAPI, registre o endpoint do agente:

from fastapi import FastAPI
from agent_framework_ag_ui import add_agent_framework_fastapi_endpoint
import uvicorn

app = FastAPI()

# Register your agent
add_agent_framework_fastapi_endpoint(
    app=app,
    path="/my_agent",
    agent=agent,
)

if __name__ == "__main__":
    uvicorn.run(app, host="127.0.0.1", port=8888)

3. Testar no Dojo

1. Iniciar o servidor
2. Abrir o Dojo em http://localhost:3000
3. Definir a URL do servidor como http://localhost:8888
4. Seu agente aparecerá no menu suspenso do endpoint como "my_agent"
5. Selecione-o e inicie o teste

Estrutura do Projeto

Os exemplos de integração do repositório AG-UI seguem esta estrutura:

integrations/microsoft-agent-framework/python/examples/
├── agents/
│   ├── agentic_chat/                  # Feature 1: Basic chat agent
│   ├── backend_tool_rendering/        # Feature 2: Backend tool rendering
│   ├── human_in_the_loop/             # Feature 3: Human-in-the-loop
│   ├── agentic_generative_ui/         # Feature 4: Streaming state updates
│   ├── tool_based_generative_ui/      # Feature 5: Custom UI components
│   ├── shared_state/                  # Feature 6: Bidirectional state sync
│   ├── predictive_state_updates/      # Feature 7: Predictive state updates
│   └── dojo.py                        # FastAPI application setup
├── pyproject.toml                     # Dependencies and scripts
├── .env.example                       # Environment variable template
└── README.md                          # Integration examples documentation

Resolução de problemas

Problemas de conexão do servidor

Se o Dojo não puder se conectar ao servidor:

• Verifique se o servidor está em execução na porta correta (padrão: 8888)
• Verifique se a URL do servidor no Dojo corresponde ao endereço do servidor
• Verifique se nenhum firewall está bloqueando a conexão
• Procure erros de CORS no console do navegador

Agente não está aparecendo

Se o seu agente não aparecer na lista suspensa Dojo:

• Verifique se o endpoint do agente está registrado corretamente
• Verificar os logs do servidor quanto a erros de inicialização
• Verifique se a add_agent_framework_fastapi_endpoint chamada foi concluída com êxito

Problemas de variável de ambiente

Se você vir erros de autenticação:

• Verifique se o .env arquivo está no diretório correto
• Verifique se todas as variáveis de ambiente necessárias estão definidas
• Verifique se as chaves de API e os pontos de extremidade são válidos
• Reinicie o servidor depois de alterar variáveis de ambiente

Próximas etapas

• Explorar os agentes de exemplo para ver os padrões de implementação
• Saiba mais sobre a Renderização de Ferramentas de Back-end para personalizar UIs da ferramenta

Recursos adicionais

• Documentação doAG-UI

• AG-UI Repositório GitHub

• Aplicativo Dojo

• Exemplos de integração do Microsoft Agent Framework

Em breve.