Azure AI Agent

This guide walks you through setting up an Azure AI Agent with RAG (Retrieval-Augmented Generation) in Microsoft Foundry, and connecting it to your Ravatar avatar. It is part of the AGENTIC AI configuration flow in the Genesis AI Avatar Studio wizard.

Prerequisites​

  • A Microsoft Azure account with an active subscription
  • Access to Microsoft Foundry
  • A Ravatar account with an active project

Part 1: Create a Project in Microsoft Foundry​

  1. Go to ai.azure.com and sign in with your Azure account.
  2. Click Create project and give it a name (e.g., foundry-file-search-test).
  3. Select or create a Resource Group and Region, then confirm.
  4. Once created, you'll see the Project Home page with your credentials.
Important:  

On the Project Home page you can already see your API Key and Project Endpoint — you'll need both of these later for Ravatar.

Microsoft Foundry project home page showing API key, project endpoint, and Azure OpenAI endpoint fields

Part 2: Create an AI Agent​

  1. In the left sidebar, click Build → Agents.
  2. Click the Create agent button.
Empty Microsoft Foundry Agents page with Create your first agent prompt
  1. Configure your agent:
    • Agent Name — enter a name (e.g., test-agent-file-search). This is the name you'll provide in Ravatar.
    • Model — select your model (e.g., gpt-4.1).
    • Instructions — write a system prompt that describes how your agent should behave (e.g., "You are a helpful assistant that answers questions based on the provided documents.").
Microsoft Foundry agent playground with agent name, model selection, instructions, tools and knowledge sections

The simplest way to add RAG (knowledge base) to your agent is through File Search. This lets you upload documents that the agent can reference when answering questions.

  1. In your agent's configuration, find the Tools section.
  2. Click Add → select File search.
  3. Click Upload files to attach your documents.
  4. In the Attach files dialog:
    • Drag and drop your files or click Browse for files.
    • Supported formats: PDF, DOCX, TXT, and more.
    • Wait for all files to show the Success status.
    • Click Attach.
Microsoft Foundry Attach files dialog showing uploaded files with green Success status
  1. After attaching, you'll see the File search tool listed under Tools with your vector index.
Microsoft Foundry agent configuration with File search tool attached and vector index name visible
  1. Click Save in the top bar. Each save creates a new Agent Version (starting from 1).

Part 4: Find Your Agent Name and Version​

  1. Go back to Build → Agents to see the agents list.
  2. Here you can see:
    • Agent Name (e.g., test-agent-file-search)
    • Version number (e.g., 1)
Microsoft Foundry agents list showing agent name, version, type and creation date columns
Note:  

Every time you save changes to your agent, the version number increments. Use the latest version number when connecting to Ravatar.

Part 5: Collect Your Configuration Values​

You need 4 values to connect your Azure AI Agent to Ravatar. Here is where to find each one:

ValueWhere to Find
API KeyProject Home page (Part 1) — click the copy icon next to API Key
Project EndpointProject Home page (Part 1) — click the copy icon next to Project endpoint
Agent NameAgents list (Part 4) — Name column
Agent VersionAgents list (Part 4) — Version column
Security:  

Keep your API Key confidential. Do not share it publicly or commit it to version control.

Part 6: Connect to Ravatar​

  1. Open your project in the Ravatar Dashboard.
  2. Go to the AI LOGIC section of the Configuration Wizard.
  3. Set Logic Source to AI Agents.
  4. Set Provider to Azure AI Agent.
  5. Fill in the four fields:
    • API Key — paste the API Key from your Foundry project.
    • Project Endpoint — paste the full endpoint URL (starts with https://).
    • Agent Name — enter the exact agent name (e.g., test-agent-file-search).
    • Agent Version — enter the version number (e.g., 1).
  6. Scroll down to Text to Speech and configure your preferred TTS provider and language(s). See the TTS guide for details.
  7. Click Save.
  8. Click Talk to Avatar to test your connection via the Preview Display panel.
Ravatar Dashboard AI Logic section with Azure AI Agent provider selected and all four required fields filled in

Quick Reference​

Ravatar FieldSourceExample Format
API KeyFoundry → Project HomeCR6ZV…OGVL6y
Project EndpointFoundry → Project Homehttps://<project>-resource.services.ai.azure.com/api/projects/<name>
Agent NameFoundry → Agents listtest-agent-file-search
Agent VersionFoundry → Agents list1

Troubleshooting​

Agent not responding?:  
  • Verify that all four fields are filled correctly with no extra whitespace.
  • Make sure the Project Endpoint is the full URL starting with https://.
  • Check that your Azure subscription is active.
RAG not working (agent does not use uploaded files)?:  
  • Confirm the File Search tool is attached and saved.
  • Make sure you saved the agent after adding files — the version should increment.
  • Use the correct Agent Version in Ravatar.
API Key rejected?:  
  • Ensure you are using the API Key from the Foundry project page, not the Azure Portal resource key.
  • Try regenerating the key in Foundry if it was recently rotated.

Need Help?​

Contact us at support@ravatar.com if you have any questions or run into issues while connecting your Azure AI Agent to Ravatar.