Multi-Agent Orchestration: Hosted Workflows in Azure AI Foundry

This repo provides a practical implementation of Hosted Workflows using the Azure AI SDK for Python. It utilises the Microsoft Agent Framework's declarative schema to define multi-agent orchestration (workflow).

Unlike local workflows, hosted workflows are deployed directly to Azure AI Foundry, allowing them to be managed, versioned and executed within the Azure ecosystem.

Warning

To successfully run this code, you must have access to an Azure AI Foundry project and AI model deployment. Please ensure you have the following environment variables set up in your system:

Environment Variable	Description
AZURE_FOUNDRY_PROJECT_ENDPOINT	The endpoint URL for your Azure AI Foundry project.
AZURE_FOUNDRY_GPT_MODEL	The name of the model deployment to be used by the Azure AI SDK, e.g., gpt-4.1-mini.

📑 Table of Contents

• Use-Case Scenario: Code Review
• Code Sample: YAML Definition
• Code Sample: Python Script
• Deployment of Hosted Workflow
• Execution in Azure AI Foundry

Use-Case Scenario: Code Review

This sample demonstrates a Code Review workflow involving two specialised agents:

• Developer Agent: writes code to solve problems and may occasionally introduce bugs,
• Reviewer Agent: checks the code for style and correctness.

The workflow continues in a loop until the Reviewer provides the approved keyword, at which point the final solution is delivered then to the user.

Code Sample: YAML Definition

The workflow logic is defined in CodeReview.yaml file, that describes the triggers, variables and the sequence of agent invocations.

1.1 Workflow Trigger

The workflow is initialised using the OnConversationStart trigger, that captures the user's input into a local variable (Local.LatestMessage) as the starting context for the agents.

kind: workflow
trigger:
  kind: OnConversationStart
  id: trigger_wf
  actions:
    - kind: SetVariable
      id: init_latest
      variable: Local.LatestMessage
      value: =UserMessage(System.LastMessageText)

1.2 Agent Invocation

The logic utilises the InvokeAzureAgent action to call specific agents registered in Azure AI Foundry.

• DeveloperAgent: receives the initial problem or previous feedback to generate code,
• ReviewerAgent: analyses the developer's output to provide feedback or approval,

Both agents map their outputs back to Local.LatestMessage, for the conversation state to persist across turns.

- kind: InvokeAzureAgent
  id: invoke_developer
  agent:
    name: DeveloperAgent
  conversationId: =System.ConversationId
  input:
    messages: =Local.LatestMessage
  output:
    messages: Local.LatestMessage
    autoSend: true

1.3 Conditions and Looping

To manage the code review interactions, the workflow utilises a ConditionGroup logic.

• Approval Check: A condition searches for the string "approved" within the reviewer's last message.
• Termination: If approved, the workflow sends the final activity and ends the conversation.
• Looping: If not approved, a GotoAction redirects the flow back to the invoke_developer step.

- kind: ConditionGroup
  id: check_approved
  conditions:
    - id: if_approved
      condition: =!IsBlank(Find("approved", Lower(Last(Local.LatestMessage).Text)))
      actions:
        - kind: EndConversation
  elseActions:
    - kind: GotoAction
      id: loop_back
      actionId: invoke_developer

Code Sample: Python Script

The hosted_workflow.py script is your deployment engine. It utilises the AIProjectClient to register both the individual agents and the orchestration workflow in your Azure AI Foundry project.

2.1 Registering Agents

Agents are created as versions in the new Azure AI Foundry UI. This allows you to define their persona once and reuse then specific versions in the target agentic workflows.

agent = project_client.agents.create_version(
    agent_name="<YOUR_AGENT_NAME>",
    definition=PromptAgentDefinition(
        model=model,
        instructions="<YOUR_AGENT_INSTRUCTIONS>"
    ),
)

2.2 Registering the Workflow

The YAML definition is uploaded to Azure AI Foundry as a WorkflowAgentDefinition. By registering the workflow this way, you make it "hosted" and enable it being triggered within AI Foundry UI or via API calls to the project endpoint.

workflow_agent = project_client.agents.create_version(
    agent_name=workflow_definition["name"],
    definition=WorkflowAgentDefinition(workflow=workflow_yaml),
    description=workflow_definition["description"],
)

2.3 Client Initialisation

To interact with Azure AI Foundry, the Python script initialises an AIProjectClient using your Azure AI Foundry project endpoint and AzureCliCredential. This client serves as the primary interface for managing agentic resources in AI Foundry.

project_client = AIProjectClient(
    endpoint=project_endpoint,
    credential=AzureCliCredential()
)

Deployment of Hosted Workflow

To deploy your orchestration logic to Azure, you must execute the provided Python script.

Important

Ensure you have authenticated via the Azure CLI (az login) before starting.

3.1 Prerequisites

Before running the deployment, install the necessary Azure AI SDK and Azure Identity libraries:

pip install azure-ai-projects --pre
pip install azure-identity pyyaml

3.2 Running the Deployment

The script requires the path to your YAML definition file as a command-line argument. If not provided, it defaults to CodeReview.yaml.

python hosted_workflow.py CodeReview.yaml

3.3 Deployment Process

The deployment process consists of the following few steps:

• Connection: The AIProjectClient establishes the connection to your Azure AI Foundry project endpoint, using your Azure CLI credentials.
• Agent Creation: The script utilises the define_developer_agent and define_reviewer_agent functions to create / update agent versions in the project.
• Workflow Registration: The script then reads the CodeReview.yaml file and registers it as a WorkflowAgentDefinition within the AI Foundry's Workflow section.

3.4 CLI Output

If successful, you should see a command-line output similar to this:

============================================================
Creating Hosted Workflow in Azure AI Foundry
============================================================
Project Endpoint: https://<YOUR_AI_FOUNDRY_ACCOUNT>.services.ai.azure.com/api/projects/<YOUR_AI_FOUNDRY_PROJECT>
Model: gpt-4.1-mini

Creating agents in Azure AI Foundry...
Created DeveloperAgent: DeveloperAgent:1
Created ReviewerAgent: ReviewerAgent:1

Creating workflow in Azure AI Foundry...
Loaded workflow definition from: CodeReview.yaml
Created workflow: CodeReviewWorkflow:1

============================================================
Hosted Workflow Created Successfully!
============================================================
Workflow ID: CodeReviewWorkflow:1
Agents: ['DeveloperAgent', 'ReviewerAgent']

Execution in Azure AI Foundry

Once the deployment is complete, you can manage and visualise your agents and workflows directly within the new Azure AI Foundry portal's UI.

4.1 Agents Section

Navigate to the Agents tab to view your newly registered DeveloperAgent and ReviewerAgent.

• Validation: inspect the specific system instructions, created versions and assigned model deployments.
• Individual Testing: use the new AI Foundry UI to test agent responses independently before running the full orchestration.

4.2 Workflows Section

Under the Workflows tab, you will find the CodeReviewWorkflow.

• Visualizer View: view the logic flow, incl. the loop between agents and the final conditional exit.
• YAML View: review or update the uploaded declarative schema directly in the Azure AI Foundry UI.
• Code View: access the code representation of your workflow in Python, JavaScript and C#.

4.3 Traceability and Debugging

Every workflow execution generates a unique trace, allowing granular audit of the multi-agent interaction.

• Transcript Analysis: view the messages exchanged, e.g. the ReviewerAgent providing code feedback and the DeveloperAgent submitting revisions.
• Loop Monitoring: check how many iterations occurred before the approved keyword was detected by the condition group.