Test con AG-UI Dojo

L'applicazione DojoAG-UI fornisce un ambiente interattivo per testare ed esplorare gli agenti di Microsoft Agent Framework che implementano il protocollo AG-UI. Dojo offre un'interfaccia visiva per connettersi agli agenti e interagire con tutte le 7 AG-UI funzionalità.

Prerequisiti

Prima di iniziare, assicurarsi di disporre di:

• Python 3.10 o versione successiva
• uv per la gestione delle dipendenze
• Una chiave API OpenAI o un endpoint OpenAI di Azure
• Node.js e pnpm (per l'esecuzione del front-end Dojo)

Installazione

1. Clonare il repository AG-UI

Prima di tutto, clonare il repository AG-UI che contiene l'applicazione Dojo e gli esempi di integrazione di Microsoft Agent Framework:

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

2. Vai alla directory 'Examples'

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

3. Installare le dipendenze python

Usare uv per installare le dipendenze necessarie:

uv sync

4. Configurare le variabili di ambiente

Creare un .env file dal modello fornito:

cp .env.example .env

Modificare il .env file e aggiungere le credenziali 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

Annotazioni

Se si utilizza DefaultAzureCredential al posto di un api_key per l'autenticazione, assicurarsi di essere autenticati con Azure (ad esempio, tramite az login). Per altre informazioni, vedere la documentazione sull'identità di Azure.

Esecuzione dell'applicazione Dojo

1. Avviare il server back-end

Nella directory degli esempi avviare il server back-end con gli agenti di esempio:

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

Il server verrà avviato su http://localhost:8888 per impostazione predefinita.

2. Avviare il front-end Dojo

Aprire una nuova finestra del terminale, passare alla radice del repository AG-UI e quindi alla directory dell'applicazione Dojo:

cd apps/dojo
pnpm install
pnpm dev

Il front-end Dojo sarà disponibile all'indirizzo http://localhost:3000.

3. Connetti all'agente

1. Aprire http://localhost:3000 nel browser

2. Configurare l'URL del server in http://localhost:8888

3. Selezionare "Microsoft Agent Framework (Python)" nell'elenco a discesa

4. Iniziare a esplorare gli agenti di esempio

Agenti di esempio disponibili

Gli esempi di integrazione illustrano tutte le 7 funzionalità AG-UI tramite endpoint agente diversi:

Punto finale	Caratteristica / Funzionalità	Description
/agentic_chat	Funzionalità 1: Chat agentica	Agente conversazionale di base con richiamo di strumenti
/backend_tool_rendering	Funzionalità 2: Rendering degli strumenti back-end	Rendering dell'interfaccia utente dell'agente con strumenti personalizzati
/human_in_the_loop	Caratteristica 3: Umano nel ciclo	Agente con flussi di lavoro di approvazione
/agentic_generative_ui	Funzionalità 4: Interfaccia utente generativa orientata agli agenti	Agente che suddivide le attività in passaggi con gli aggiornamenti in streaming
/tool_based_generative_ui	Funzionalità 5: Interfaccia utente generativa basata su strumenti	Agente che genera componenti dell'interfaccia utente personalizzati
/shared_state	Funzionalità 6: Stato condiviso	Agente con sincronizzazione dello stato bidirezionale
/predictive_state_updates	Funzionalità 7: Aggiornamenti dello stato predittivo	Agente con aggiornamenti dello stato predittivo durante l'esecuzione degli strumenti

Test dei propri agenti

Per testare i propri agenti con Dojo:

1. Crea il tuo agente

Creare un nuovo agente seguendo la guida introduttiva :

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. Aggiungere l'agente al proprio server

Nell'applicazione FastAPI registrare l'endpoint dell'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. Test nel Dojo

1. Avviare il server
2. Aprire Dojo all'indirizzo http://localhost:3000
3. Impostare l'URL del server su http://localhost:8888
4. L'agente verrà visualizzato nell'elenco a discesa dell'endpoint come "my_agent"
5. Selezionarlo e avviare il test

Struttura del progetto

Gli esempi di integrazione del repository AG-UI seguono questa struttura:

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

Risoluzione dei problemi

Problemi di connessione al server

Se Dojo non riesce a connettersi al server:

• Verificare che il server sia in esecuzione sulla porta corretta (impostazione predefinita: 8888)
• Verificare che l'URL del server in Dojo corrisponda all'indirizzo del server
• Assicurarsi che nessun firewall blocchi la connessione
• Cercare errori CORS nella console del browser

Agente non visualizzato nel sistema

Se l'agente non appare nel menu a tendina Dojo:

• Verificare che l'endpoint dell'agente sia registrato correttamente
• Controllare i log del server per eventuali errori di avvio
• Assicurarsi che la add_agent_framework_fastapi_endpoint chiamata sia stata completata correttamente

Problemi relativi alle variabili di ambiente

Se vengono visualizzati errori di autenticazione:

• Verificare che il .env file si trova nella directory corretta
• Verificare che siano impostate tutte le variabili di ambiente necessarie
• Verificare che le chiavi API e gli endpoint siano validi
• Riavviare il server dopo la modifica delle variabili di ambiente

Passaggi successivi

• Esplorare gli agenti di esempio per visualizzare i modelli di implementazione
• Scopri il rendering degli strumenti nel backend per personalizzare le interfacce utente degli strumenti.

Risorse aggiuntive

• Documentazione diAG-UI

• GitHub Repository AG-UI

• Applicazione Dojo

• Esempi di integrazione di Microsoft Agent Framework

Prossimamente.