Megjegyzés
Az oldalhoz való hozzáféréshez engedély szükséges. Megpróbálhat bejelentkezni vagy módosítani a címtárat.
Az oldalhoz való hozzáféréshez engedély szükséges. Megpróbálhatja módosítani a címtárat.
Microsoft Agent Framework támogatja mind a közvetlen modellkövetkeztetést a Microsoft Foundry projektvégpontjaiból, mind a szolgáltatás által kezelt ügynököket a Foundry Agent Service-ben.
Első lépések
Adja hozzá a szükséges NuGet-csomagokat a projekthez.
dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.Foundry --prerelease
Két ügynöktípus
A Microsoft Foundry-integráció két különböző használati mintát tesz elérhetővé:
| Típus | Előállított típus | Leírás | Használat: |
|---|---|---|---|
| Válaszügynök | ChatClientAgent |
Az alkalmazás programozott módon biztosít egy modellt, utasításokat és eszközöket futásidőben.AIProjectClient.AsAIAgent(...) Nincs kiszolgálóoldali ügynöki erőforrás létrehozva. |
Ön az ügynökdefiníció tulajdonosa, és egyszerű, rugalmas beállításra van szüksége. Ez a minta, amit a legtöbb példában használnak. |
| Foundry Agent (verziókezelés alatt) | FoundryAgent |
Kiszolgáló által felügyelt – az ügynökdefiníciók az Foundry portálon vagy programozott módon AIProjectClient.AgentAdministrationClientjönnek létre és verziószámozhatók. Adjon meg egy ProjectsAgentVersion vagy ProjectsAgentRecord vagy AgentReference a AIProjectClient.AsAIAgent(...) számára. |
Szigorú, verziószámozott ügynökdefiníciókra van szüksége az Foundry portálon, szolgáltatás API-k használatával |
Válaszügynök (közvetlen következtetés)
Használja a AsAIAgent közvetlenül a AIProjectClient modellel és útmutatásokkal. Ez a legtöbb forgatókönyv esetében ez a javasolt kiindulópont.
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
AIAgent agent = new AIProjectClient(
new Uri("<your-foundry-project-endpoint>"),
new DefaultAzureCredential())
.AsAIAgent(
model: "gpt-4o-mini",
name: "Joker",
instructions: "You are good at telling jokes.");
Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));
Figyelmeztetés
DefaultAzureCredential a fejlesztéshez kényelmes, de a termelési környezetben gondos megfontolást igényel. Éles környezetben fontolja meg egy adott hitelesítő adat (pl. ManagedIdentityCredential) használatát a késési problémák elkerülése, a hitelesítő adatok nem szándékos próbálgatásának és a tartalék mechanizmusokból eredő esetleges biztonsági kockázatok elkerülése érdekében.
Ez az útvonal kódalapú, és nem hoz létre szerver által menedzselt ügynökerőforrást.
Öntödei ügynök (verziószámozott)
Az AI Projects SDK natív AIProjectClient.AgentAdministrationClient API-ival lekérheti a verziószámozott ügynökerőforrásokat, majd becsomagolhatja őket AsAIAgent. Az ügynökök közvetlenül az Foundry portálon vagy programozott módon hozhatók létre és konfigurálhatók.AIProjectClient.AgentAdministrationClient
using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry;
var aiProjectClient = new AIProjectClient(
new Uri("<your-foundry-project-endpoint>"),
new DefaultAzureCredential());
// Retrieve an existing agent by name (uses the latest version automatically)
ProjectsAgentRecord jokerRecord = await aiProjectClient.AgentAdministrationClient.GetAgentAsync("Joker");
FoundryAgent agent = aiProjectClient.AsAIAgent(jokerRecord);
Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));
Fontos
Az Öntödei Kiszolgálók eszközei és utasításai szigorúan igazodnak az eredeti tervekhez, és a futásidőben történő szerszám- vagy utasításmódosítás nem támogatott.
Az ügynök használata
A ChatClientAgent (válaszok) és a FoundryAgent (verziószámozott) standard AIAgent példányok, és támogatják az összes szabványos műveletet, beleértve a munkameneteket, az eszközöket, a köztes szoftvereket és a streamelést.
AgentSession session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("Tell me a joke.", session));
Console.WriteLine(await agent.RunAsync("Now make it funnier.", session));
Az ügynökök futtatásával és használatával kapcsolatos további információkért tekintse meg az ügynök első lépéseket ismertető oktatóanyagait.
Szerszámosládák
Note
Az Foundry Toolbox .NET-dokumentumok hamarosan elérhetők.
Öntöde a Python
A Pythonban mostantól minden Foundry-specifikus ügyfél a agent_framework.foundry alatt található.
-
agent-framework-foundrya következő felhőbeli Foundry-összekötőket biztosítja:FoundryChatClient,FoundryAgent,FoundryEmbeddingClientésFoundryMemoryProvider. -
agent-framework-foundry-localhelyi modell végrehajtására szolgálFoundryLocalClient.
Fontos
Ez a lap a Microsoft Foundry projekt végpontjai, a modellek végpontjai és a Foundry Agent szolgáltatás aktuális Python kliensprogramjait ismerteti. Ha van önálló Azure OpenAI-erőforrásvégpontja (https://<your-resource>.openai.azure.com), használja a Python útmutatót az OpenAI szolgáltatói oldalon. Ha helyileg szeretne támogatott modelleket futtatni, tekintse meg az Foundry Helyi szolgáltató oldalát.
Python alapú Foundry chat és agent minták
| Scenario | Python alakzat | Használat: |
|---|---|---|
| Egyszerű következtetés az Foundry-válaszok végpontjával | Agent(client=FoundryChatClient(...)) |
Az alkalmazás rendelkezik az ügynökdefinícióval, az eszközökkel és a beszélgetési ciklussal, és szeretne egy modellt telepíteni egy Foundry-projektben. |
| Szolgáltatás által felügyelt ügynökök a Foundry Agent Szolgáltatásban | FoundryAgent(...) |
Az Foundry portálon vagy a szolgáltatás API-ján keresztül létrehozott és konfigurált PromptAgenthez vagy HostedAgenthez szeretne csatlakozni. |
Installation
pip install agent-framework-foundry
pip install azure-identity
Ugyanez a agent-framework-foundry csomag tartalmaz FoundryEmbeddingClient a Foundry-modellek végpontjainak beágyazásaihoz.
Konfiguráció
FoundryChatClient
FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_MODEL="gpt-4o-mini"
FoundryAgent
FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_AGENT_NAME="my-agent"
FOUNDRY_AGENT_VERSION="1.0"
A parancssori ügynökökhöz használható FOUNDRY_AGENT_VERSION . A hosztolt ügynökök elhallgathatják.
FoundryEmbeddingClient
FOUNDRY_MODELS_ENDPOINT="https://<apim-instance>.azure-api.net/<foundry-instance>/models"
FOUNDRY_MODELS_API_KEY="<api-key>"
FOUNDRY_EMBEDDING_MODEL="text-embedding-3-small"
FOUNDRY_IMAGE_EMBEDDING_MODEL="Cohere-embed-v3-english" # optional
FoundryChatClient és FoundryAgent használja a projektvégpontot.
FoundryEmbeddingClient a különálló modellvégpontot használja.
Válassza ki a megfelelő Python ügyfelet
| Scenario | Előnyben részesített ügyfél | Jegyzetek |
|---|---|---|
| Azure OpenAI-erőforrás | OpenAIChatCompletionClient / OpenAIChatClient |
Használja az OpenAI szolgáltató oldalát. |
| Microsoft Foundry-projekt következtetése | Agent(client=FoundryChatClient(...)) |
Az Foundry Responses végpontot használja. |
| Microsoft Foundry szolgáltatás által felügyelt ügynök | FoundryAgent |
Ajánlott a Parancssori ügynökök és a Hosztolt ügynökök számára. |
| Microsoft Foundry modellek-végpont beágyazások | FoundryEmbeddingClient |
FOUNDRY_MODELS_ENDPOINT
FOUNDRY_EMBEDDING_MODEL
/ Pluszt használFOUNDRY_IMAGE_EMBEDDING_MODEL. |
| Foundry helyi futási környezet | Agent(client=FoundryLocalClient(...)) |
Lásd : Foundry Local. |
Hozzon létre egy ügynököt FoundryChatClient
FoundryChatClient Egy Foundry-projektben üzembe helyezett modellhez csatlakozik, és a Válaszok végpontot használja. Párosítsa egy szabványsal Agent , amikor az alkalmazásnak útmutatást, eszközöket és munkamenet-kezelést kell megadnia.
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential
agent = Agent(
client=FoundryChatClient(
project_endpoint="https://your-project.services.ai.azure.com",
model="gpt-4o-mini",
credential=AzureCliCredential(),
),
name="FoundryWeatherAgent",
instructions="You are a helpful assistant.",
)
FoundryChatClient az Foundry első Python elérési útja, amely közvetlen következtetést eredményez, és támogatja az eszközöket, a strukturált kimeneteket és a streamelést.
Beágyazások létrehozása a FoundryEmbeddingClient
Akkor használható FoundryEmbeddingClient , ha szöveg- vagy képbeágyazást szeretne egy Foundry-modellek végpontjáról.
from agent_framework.foundry import FoundryEmbeddingClient
async with FoundryEmbeddingClient() as client:
result = await client.get_embeddings(["hello from Agent Framework"])
print(result[0].dimensions)
Csatlakozás egy FoundryAgent által felügyelt szolgáltatás ügynökhöz
Akkor használható FoundryAgent , ha az ügynökdefiníció a Foundryben található. Ez az ajánlott Python API parancssori ügynökökhöz és HostedAgentekhez.
from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential
agent = FoundryAgent(
project_endpoint="https://your-project.services.ai.azure.com",
agent_name="my-prompt-agent",
agent_version="1.0",
credential=AzureCliCredential(),
)
HostedAgent esetén hagyja ki agent_version és használja helyette az üzemeltetett ügynök nevét.
Kapcsolódás telepített (hostolt) Foundry ügynökhöz
Szolgáltatásoldali munkameneteket (/agents/{name}/sessions) futtató HostedAgents esetén használja FoundryAgentallow_preview=True parancsot, hogy csatlakozzon az előnézeti Válaszok felülethez, és adja át a következőt: version="v2"
from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential
agent = FoundryAgent(
agent_name="my-hosted-agent",
credential=AzureCliCredential(),
allow_preview=True,
version="v2",
)
Ha a mögöttes szolgáltatási munkamenetet saját maga kell kezelnie – például egy munkamenet egy adott bérlőhöz vagy felhasználóhoz való kötéséhez –, hozza létre a munkamenetet az előzetes verziójú AIProjectClient API-val, és csomagolja be a következővel agent.get_session(...):
from azure.ai.projects.aio import AIProjectClient
from azure.ai.projects.models import VersionRefIndicator
service_session = await project_client.beta.agents.create_session(
agent_name="my-hosted-agent",
isolation_key="user-123",
version_indicator=VersionRefIndicator(agent_version="1.0"),
)
session = agent.get_session(service_session.agent_session_id)
response = await agent.run("Hello!", session=session)
Jótanács
using_deployed_agent.py A minta egy teljes példát mutat be, beleértve a legújabb verzió automatikus feloldását is.
Figyelmeztetés
A régebbi Python AzureAIClient, AzureAIProjectAgentProvider, AzureAIAgentClient, AzureAIAgentsProvider és Azure AI-beágyazási kompatibilitási felületek el lettek távolítva az aktuális agent_framework.azure névtérből. Az aktuális Python kódhoz használja a FoundryChatClient-t, amikor az alkalmazás utasításokat és eszközöket birtokol, a FoundryAgent-et, amikor az ügynök meghatározása a Foundry-ben van, és a FoundryEmbeddingClient-t a Foundry modellek végponti beágyazásaihoz.
Az ügynök használata
A FoundryChatClient és a FoundryAgent is integrálható a standard Python Agent felülettel, beleértve az eszközhívást, a munkameneteket és a streamelési válaszokat. Helyi futtatókörnyezetek esetén használja a külön Foundry Local szolgáltató oldalát.
Szerszámosládák
Fontos
A Toolbox API-k kísérleti jellegűek. A felület a jövőbeli kiadásokban változhat.
A Foundry toolbox egy elnevezett, verziókezelésű szerveroldali csomag, amely üzemeltetett eszközkészleteket (például kódértékelő, fájlkereső, képgeneráló, MCP, valamint webkereső) tartalmaz, és egy Microsoft Foundry-projekt keretén belül kerül konfigurálásra. Az eszközkészletekkel egyszer kezelheti az eszközkonfigurációt az Foundry portálon, és újra felhasználhatja az ügynökök között.
Az Agent Framework csak a felhasználást fedi le – az eszközkészlet-verziók létrehozása és frissítése az Foundry portálon vagy a nyers azure-ai-projects SDK-n (azure-ai-projects>=2.1.0) keresztül történik.
FoundryAgent és FoundryChatClient
| Ügynök típusa | Eszközkészlet viselkedése |
|---|---|
| FoundryAgent (üzemeltetve) | Az eszközkészlet csatolása a kiszolgálóoldalon történik. Nincs szükség ügyféloldali kábelezésre. |
| FoundryChatClient (közvetlen következtetés) | Hozza el az eszközkészletet get_toolbox() és adja át tools=. |
Két fogyasztási minta
| Pattern | Leírás |
|---|---|
| Natív (hosztolt eszközök) | Az eszközkonfigurációk az Foundry-futtatókörnyezetben futnak. Adja át az eszközkészletet közvetlenül a következőként tools=. |
| MCP | Használja MCPStreamableHTTPTool az eszközkészlet MCP-végpontján. Bármilyen csevegőügyféllel működik, nem csak FoundryChatClient. |
Eszközkészlet lehívása
Használja a FoundryChatClient.get_toolbox() eszköztár lekéréséhez.
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import AzureCliCredential
async with AzureCliCredential() as credential:
client = FoundryChatClient(credential=credential)
toolbox = await client.get_toolbox("research_toolbox")
async with Agent(client=client, name="ResearchAgent", tools=toolbox) as agent:
result = await agent.run("Summarize recent findings.")
print(result.text)
Ha version nincs megadva, get_toolbox két kérésben feloldja az alapértelmezett verziót. Rögzítsen egy adott verziót a további oda-visszaút elkerülése érdekében:
toolbox = await client.get_toolbox("research_toolbox", version="v3")
Note
Minden get_toolbox() hívás eléri a hálózatot – nincs keretrendszeroldali gyorsítótár, mert az alapértelmezett verziók módosíthatják a kiszolgálóoldalt. A gyorsítótárazás a hívó fél tulajdonában van.
Implicit simítás
Nem kell írnia toolbox.tools. A keretrendszer felismeri normalize_tools, és automatikusan simítja ToolboxVersionObject. Mindegyik működik.
# Single toolbox
agent = Agent(client=client, tools=toolbox)
# Toolbox in a list
agent = Agent(client=client, tools=[toolbox])
# Mix local function tools with a toolbox
agent = Agent(client=client, tools=[get_internal_metrics, toolbox])
# Combine multiple toolboxes
agent = Agent(client=client, tools=[toolbox_a, toolbox_b])
Szűrőeszközök a select_toolbox_tools
Ha az eszközkészlet több eszközt tartalmaz, de egy ügynöknek csak bizonyos eszközökre van szüksége, használja a select_toolbox_tools a készlet szűkítésére a beolvasás után. Így elkerülhető, hogy szükségtelen eszközdefiníciókat küldjön a modellnek, ami csökkenti a tokenhasználatot, és megakadályozza, hogy a modell olyan eszközöket invoktáljon, amelyeket nem kíván elérhetővé tenni:
from agent_framework.foundry import select_toolbox_tools, get_toolbox_tool_name
# Filter by tool name
tools = select_toolbox_tools(toolbox, include_names=["web_search", "code_interpreter"])
# Filter by tool type
tools = select_toolbox_tools(toolbox, include_types=["mcp", "web_search"])
# Filter with a custom predicate
tools = select_toolbox_tools(toolbox, predicate=lambda t: "search" in (get_toolbox_tool_name(t) or ""))
Segédfüggvények get_toolbox_tool_name(tool) és get_toolbox_tool_type(tool) adják vissza az eszközbejegyzés kijelölési nevét és nyers típusát.
FoundryHostedToolType egy TypeAlias (Literal["code_interpreter", "file_search", "image_generation", "mcp", "web_search"] | str), amely IDE által vezérelt kiegészítést biztosít include_types / exclude_types számára.
MCP-fogyasztási útvonal
Az eszközkészletet MCP-kiszolgálóként is felhasználhatja, ha MCPStreamableHTTPTool az eszközkészlet MCP-végpontjának URL-címére mutat.
Az MCP-végpont URL-címe megjelenik az Öntödei portálon, vagy a formátumot követi:
https://<account>.services.ai.azure.com/api/projects/<project>/toolsets/<name>/mcp?api-version=v1
Mivel az ügyfél közvetlenül csatlakozik a Foundry eszközkészlet-végponthoz, Entra ID szolgáltatástípusú jogkivonattal kell hitelesítenie a következőn keresztül header_provider:
from azure.identity.aio import DefaultAzureCredential
from azure.identity.aio import get_bearer_token_provider
from agent_framework import Agent, MCPStreamableHTTPTool
credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(credential, "https://ai.azure.com/.default")
mcp_tool = MCPStreamableHTTPTool(
name="research_mcp",
url="https://<your-toolbox-mcp-endpoint>",
header_provider=lambda: {"Authorization": f"Bearer {token_provider()}"},
)
async with Agent(client=client, name="MCPAgent", tools=[mcp_tool]) as agent:
result = await agent.run("Search for recent papers on LLM agents.")
print(result.text)
Limitations
- Az eszközkészleten belüli MCP-eszközök kiszolgálóoldali hitelesítést használnak. A felsőbb rétegbeli MCP-kiszolgáló hitelesítése a Foundry-projektben konfigurált OAuth-kapcsolaton keresztül
project_connection_idtörténik. Az ügyfél sosem tárol bearer tokeneket a forrás szerverhez. - Az eszközkészlet MCP-kiszolgálóként való használatához ügyféloldali hitelesítés szükséges. Amikor egy eszközkészlet MCP-végpontjára mutat
MCPStreamableHTTPTool, meg kell adnia egy Entra ID hozzáférési jogkivonatot (például aget_bearer_token_provider(credential, "https://ai.azure.com/.default")használatával) aheader_providersegítségével. - A hozzájárulási folyamat kezelése futásidejű probléma. Ha egy eszközkészlet MCP-eszköz eseményindítója
CONSENT_REQUIREDközbenagent.run()történik, akkor a rendszer futásidőben kezeli, nem pedig az eszközkészlet beolvasása során.
Samples
| Sample | Leírás |
|---|---|
| foundry_chat_client_with_toolbox.py | Alapszintű eszközkészlet-beolvasás, verzió-rögzítés, eszközkészletek kombinálása és szűrés |
| foundry_chat_client_with_toolbox_mcp.py | MCP-fogyasztási útvonal a MCPStreamableHTTPTool |
| foundry_toolbox_context_provider.py | Dinamikus fordulónkénti eszközkiválasztás egy kontextusszolgáltatón keresztül |