Azure AI Agents: When to Use azure.ai.projects vs. agent_framework

By benperk · · , , , , , ,

As Azure AI Foundry adoption grows, developers are increasingly faced with an important architectural decision:

Should I use azure.ai.projects or agent_framework?

The answer depends on where your agent lives and how you want to manage it.  Although both SDKs are part of the Azure AI ecosystem, they solve different problems. Understanding the distinction can save significant development effort and help you build a more maintainable solution.  The content in Table 1 will provide some clarity.

If you want to… Use
Connect to an agent already created in Azure AI Foundry azure.ai.projects
Create and orchestrate agents in Python code agent_framework
Manage Foundry agents, threads, runs, and files azure.ai.projects
Build custom workflows and multi-agent systems agent_framework
Use instructions configured in Foundry azure.ai.projects
Version-control agent logic in Git agent_framework
Table 1, when to use which AI Agent library

Understanding the Difference

Think of the two SDKs as operating at different layers.

azure.ai.projects

This SDK interacts with resources that already exist in Azure AI Foundry.

Azure AI Foundry
│
├── Agent: agent-support
├── Instructions
├── Knowledge
├── Tools
└── Threads

Your application connects to these resources and uses them.

agent_framework

This SDK helps you build agents in code.

Python Application
│
├── Agent
├── Instructions
├── Tools
├── Memory
└── Workflows

Everything is defined programmatically.

Visual Architecture Comparison

azure.ai.projects

Python App
    │
    ▼
AIProjectClient
    │
    ▼
Azure AI Foundry Project
    │
    ▼
agent-support

The agent already exists in Foundry.

agent_framework

Python App
    │
    ▼
Agent Framework
    │
    ▼
Agent Defined in Code
    │
    ▼
Model Deployment

The agent is created locally in Python.

Using azure.ai.projects

This approach is ideal when a Foundry agent has already been configured.

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

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

agent = project_client.agents.get(
    agent_name="agent-support"
)

print(agent.name)

Using agent_framework

This approach is ideal when agents are defined entirely in code.

from agent_framework import Agent

agent = Agent(
    name="ExpenseAgent",
    instructions="You are an expense assistant."
)

Side-by-Side Comparison

Capability azure.ai.projects agent_framework
Works with existing Foundry agents ✅ ❌
Creates agents in code ❌ ✅
Uses instructions stored in Foundry ✅ ❌
Uses instructions in Python ❌ ✅
Agent discovery ✅ ❌
Thread management Built into framework
Run management ✅ Built into framework
Multi-agent orchestration Limited ✅
Limited ✅
Tool development in Python Limited ✅
Knowledge managed in Foundry ✅ Optional
Git-based configuration Partial
Best for enterprise-managed agents ✅ ⚠️
Best for custom agent applications ⚠️ ✅
Table 2, when to use

Can You Use Both Together?

Absolutely, this is becoming a common enterprise pattern.

Python Application
│
├── agent_framework
│       │
│       ├── Planner Agent
│       ├── Routing Agent
│       └── Workflow Agent
│
└── azure.ai.projects
        │
        └── Foundry Agent
                └── agent-support

In this architecture:

  • Agent Framework handles orchestration.
  • Azure AI Foundry provides managed agents.
  • azure.ai.projects connects the two.

This gives you the best of both worlds.  If your organization already has an agent such as agent-support configured in Azure AI Foundry, azure.ai.projects is typically the right choice. If you’re building a sophisticated, code-first, multi-agent solution, agent_framework becomes the more powerful option.  For many enterprise applications, the most effective architecture combines both: use agent_framework for orchestration and azure.ai.projects for interacting with Foundry-managed agents.