Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
La prise en charge des outils peut varier considérablement entre différents types d’agents. Certains agents peuvent permettre aux développeurs de personnaliser l’agent au moment de la construction en fournissant des outils de fonction externes ou en choisissant d’activer des outils intégrés spécifiques pris en charge par l’agent. En revanche, certains agents personnalisés peuvent ne pas prendre en charge la personnalisation via la fourniture d’outils externes ou d’activation intégrés, s’ils fournissent déjà des fonctionnalités définies qui ne doivent pas être modifiées.
Par conséquent, l’abstraction de base ne fournit aucune prise en charge directe des outils, mais chaque agent peut choisir s’il accepte la personnalisation des outils au moment de la construction.
Prise en charge des outils avec ChatClientAgent
Il ChatClientAgent s’agit d’une classe d’agent qui peut être utilisée pour générer des fonctionnalités agentiques au-dessus de n’importe quel service d’inférence. Il est fourni avec prise en charge pour :
- Utilisation de vos propres outils de fonction avec l’agent
- Utilisation d’outils intégrés que le service sous-jacent peut prendre en charge.
Conseil / Astuce
Pour plus d’informations sur ChatClientAgent les services pris en charge, consultez Agents simples basés sur les services d’inférence
Fournir des instances pendant la construction de AIFunction l’agent
Il existe différentes façons de construire un ChatClientAgent, par exemple, directement ou via des méthodes d’assistance de fabrique sur différents clients de service, mais tous les outils de passage de support sont pris en charge.
// Sample function tool.
[Description("Get the weather for a given location.")]
static string GetWeather([Description("The location to get the weather for.")] string location)
=> $"The weather in {location} is cloudy with a high of 15°C.";
// When calling the ChatClientAgent constructor.
new ChatClientAgent(
chatClient,
instructions: "You are a helpful assistant",
tools: [AIFunctionFactory.Create(GetWeather)]);
// When using one of the helper factory methods.
openAIResponseClient.CreateAIAgent(
instructions: "You are a helpful assistant",
tools: [AIFunctionFactory.Create(GetWeather)]);
Fournir des AIFunction instances lors de l’exécution de l’agent
Bien que l’abstraction de base AIAgent accepte AgentRunOptions sur ses méthodes d’exécution, les sous-classes de AIAgent peuvent accepter des sous-classes de AgentRunOptions. Cela permet aux implémentations d’agents spécifiques d’accepter des options spécifiques à l’agent par exécution.
Le sous-jacent IChatClient du fichier ChatClientAgent peut être personnalisé via la ChatOptions classe pour tout appel.
Il ChatClientAgent peut accepter un ChatClientAgentRunOptions qui permet à l’appelant de fournir ChatOptions la méthode sous-jacente IChatClient.GetResponse . Lorsqu’une option se heurte à des options fournies à l’agent au moment de la construction, les options par exécution sont prioritaires.
À l’aide de ce mécanisme, nous pouvons fournir des outils par exécution.
// Create the chat options class with the per-run tools.
var chatOptions = new ChatOptions()
{
Tools = [AIFunctionFactory.Create(GetWeather)]
};
// Run the agent, with the per-run chat options.
await agent.RunAsync(
"What is the weather like in Amsterdam?",
options: new ChatClientAgentRunOptions(chatOptions));
Note
Tous les agents ne prennent pas en charge l’appel d’outils. Par conséquent, la fourniture d’outils par exécution nécessite de fournir une classe d’options spécifique à un agent.
Utilisation d’outils intégrés
Lorsque le service sous-jacent prend en charge les outils intégrés, ils peuvent être fournis à l’aide des mêmes mécanismes que ceux décrits ci-dessus.
L’implémentation IChatClient pour le service sous-jacent doit exposer une AITool classe dérivée qui peut être utilisée pour configurer l’outil intégré.
Par exemple, lors de la création d’un agent Azure AI Foundry, vous pouvez fournir un CodeInterpreterToolDefinition outil d’interpréteur de code intégré au service Azure AI Foundry.
var agent = await azureAgentClient.CreateAIAgentAsync(
deploymentName,
instructions: "You are a helpful assistant",
tools: [new CodeInterpreterToolDefinition()]);
Prise en charge des outils avec ChatAgent
Il ChatAgent s’agit d’une classe d’agent qui peut être utilisée pour générer des fonctionnalités agentiques au-dessus de n’importe quel service d’inférence. Il est fourni avec prise en charge pour :
- Utilisation de vos propres outils de fonction avec l’agent
- Utilisation d’outils intégrés que le service sous-jacent peut prendre en charge
- Utilisation d’outils hébergés tels que la recherche web et les serveurs MCP (Model Context Protocol)
Fournir des outils de fonction pendant la construction de l’agent
Il existe différentes façons de construire un ChatAgent, directement ou via des méthodes d’assistance d’usine sur différents clients de service. Toutes les approches prennent en charge le passage d’outils au moment de la construction.
from typing import Annotated
from pydantic import Field
from agent_framework import ChatAgent
from agent_framework.openai import OpenAIChatClient
# Sample function tool
def get_weather(
location: Annotated[str, Field(description="The location to get the weather for.")],
) -> str:
"""Get the weather for a given location."""
return f"The weather in {location} is cloudy with a high of 15°C."
# When creating a ChatAgent directly
agent = ChatAgent(
chat_client=OpenAIChatClient(),
instructions="You are a helpful assistant",
tools=[get_weather] # Tools provided at construction
)
# When using factory helper methods
agent = OpenAIChatClient().create_agent(
instructions="You are a helpful assistant",
tools=[get_weather]
)
L’agent utilise automatiquement ces outils chaque fois qu’il est nécessaire de répondre aux requêtes utilisateur :
result = await agent.run("What's the weather like in Amsterdam?")
print(result.text) # The agent will call get_weather() function
Fournir des outils de fonction lors de l’exécution de l’agent
Les agents Python prennent en charge la fourniture d’outils par exécution à l’aide du paramètre dans les tools deux run() méthodes.run_stream() Lorsque les outils au niveau de l’agent et au niveau de l’exécution sont fournis, ils sont combinés, avec des outils de niveau exécution prioritaires.
# Agent created without tools
agent = ChatAgent(
chat_client=OpenAIChatClient(),
instructions="You are a helpful assistant"
# No tools defined here
)
# Provide tools for specific runs
result1 = await agent.run(
"What's the weather in Seattle?",
tools=[get_weather] # Tool provided for this run only
)
# Use different tools for different runs
result2 = await agent.run(
"What's the current time?",
tools=[get_time] # Different tool for this query
)
# Provide multiple tools for a single run
result3 = await agent.run(
"What's the weather and time in Chicago?",
tools=[get_weather, get_time] # Multiple tools
)
Cela fonctionne également avec la diffusion en continu :
async for update in agent.run_stream(
"Tell me about the weather",
tools=[get_weather]
):
if update.text:
print(update.text, end="", flush=True)
Utilisation d’outils intégrés et hébergés
Python Agent Framework prend en charge différents outils intégrés et hébergés qui étendent les fonctionnalités de l’agent :
Outil de recherche web
from agent_framework import HostedWebSearchTool
agent = ChatAgent(
chat_client=OpenAIChatClient(),
instructions="You are a helpful assistant with web search capabilities",
tools=[
HostedWebSearchTool(
additional_properties={
"user_location": {
"city": "Seattle",
"country": "US"
}
}
)
]
)
result = await agent.run("What are the latest news about AI?")
Outils MCP (Protocole de contexte de modèle)
from agent_framework import HostedMCPTool
agent = ChatAgent(
chat_client=AzureAIAgentClient(async_credential=credential),
instructions="You are a documentation assistant",
tools=[
HostedMCPTool(
name="Microsoft Learn MCP",
url="https://learn.microsoft.com/api/mcp"
)
]
)
result = await agent.run("How do I create an Azure storage account?")
Outil de recherche de fichiers
from agent_framework import HostedFileSearchTool, HostedVectorStoreContent
agent = ChatAgent(
chat_client=AzureAIAgentClient(async_credential=credential),
instructions="You are a document search assistant",
tools=[
HostedFileSearchTool(
inputs=[
HostedVectorStoreContent(vector_store_id="vs_123")
],
max_results=10
)
]
)
result = await agent.run("Find information about quarterly reports")
Outil Interpréteur de code
from agent_framework import HostedCodeInterpreterTool
agent = ChatAgent(
chat_client=AzureAIAgentClient(async_credential=credential),
instructions="You are a data analysis assistant",
tools=[HostedCodeInterpreterTool()]
)
result = await agent.run("Analyze this dataset and create a visualization")
Mélange d’outils au niveau de l’agent et au niveau de l’exécution
Vous pouvez combiner des outils définis au niveau de l’agent avec des outils fournis au moment de l’exécution :
# Agent with base tools
agent = ChatAgent(
chat_client=OpenAIChatClient(),
instructions="You are a helpful assistant",
tools=[get_time] # Base tool available for all runs
)
# This run has access to both get_time (agent-level) and get_weather (run-level)
result = await agent.run(
"What's the weather and time in New York?",
tools=[get_weather] # Additional tool for this run
)
Note
La prise en charge des outils varie selon le fournisseur de services. Certains services comme Azure AI prennent en charge les outils hébergés en mode natif, tandis que d’autres peuvent nécessiter différentes approches. Vérifiez toujours la documentation de votre fournisseur de services pour obtenir des fonctionnalités d’outil spécifiques.