ToolApprovalAgent Class

Definition

Namespace:: Microsoft.Agents.AI

Assembly:: Microsoft.Agents.AI.dll

Package:: Microsoft.Agents.AI v1.13.0

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

A DelegatingAIAgent middleware that implements "don't ask again" tool approval behavior and queues multiple approval requests to present them to the caller one at a time.

public sealed class ToolApprovalAgent : Microsoft.Agents.AI.DelegatingAIAgent

type ToolApprovalAgent = class
    inherit DelegatingAIAgent

Public NotInheritable Class ToolApprovalAgent
Inherits DelegatingAIAgent

Inheritance: Object

AIAgent

DelegatingAIAgent
ToolApprovalAgent

Remarks

This middleware intercepts the approval flow between the caller and the inner agent:

Outbound (response to caller): When the inner agent surfaces ToolApprovalRequestContent items, the middleware checks whether matching Microsoft.Agents.AI.ToolApprovalRule entries have been recorded. Matched requests are auto-approved and stored as collected approval responses. If multiple unapproved requests remain, only the first is returned to the caller while the rest are queued. On subsequent calls, queued items are re-evaluated against rules (which may have been updated by the caller's "always approve" response) and presented one at a time. Once all queued requests are resolved, the collected responses are injected and the inner agent is called again.
Inbound (caller to agent): When the caller sends an AlwaysApproveToolApprovalResponseContent, the middleware extracts the standing approval settings, records them as Microsoft.Agents.AI.ToolApprovalRule entries in the session state, and forwards only the unwrapped ToolApprovalResponseContent to the inner agent. Content ordering within each message is preserved.

Approval rules are persisted in the AgentSessionStateBag and survive across agent runs within the same session. Two categories of rules are supported:

Tool-level: Approve all calls to a specific tool, regardless of arguments.
Tool+arguments: Approve all calls to a specific tool with exactly matching arguments.

Constructors

Name	Description
ToolApprovalAgent(AIAgent, ToolApprovalAgentOptions)	Initializes a new instance of the ToolApprovalAgent class.

Properties

Name	Description
AllToolsAutoApprovalRule	Gets an auto-approval rule that approves every tool call, regardless of tool name or arguments.
Description	Gets a description of the agent's purpose, capabilities, or behavior. (Inherited from DelegatingAIAgent)
Id	Gets the unique identifier for this agent instance. (Inherited from AIAgent)
IdCore	Gets a custom identifier for the agent, which can be overridden by derived classes. (Inherited from DelegatingAIAgent)
InnerAgent	Gets the inner agent instance that receives delegated operations. (Inherited from DelegatingAIAgent)
Name	Gets the human-readable name of the agent. (Inherited from DelegatingAIAgent)

Methods

Name	Description
CreateSessionAsync(CancellationToken)	Creates a new conversation session that is compatible with this agent. (Inherited from AIAgent)
CreateSessionCoreAsync(CancellationToken)	Core implementation of session creation logic. (Inherited from DelegatingAIAgent)
DeserializeSessionAsync(JsonElement, JsonSerializerOptions, CancellationToken)	Deserializes an agent session from its JSON serialized representation. (Inherited from AIAgent)
DeserializeSessionCoreAsync(JsonElement, JsonSerializerOptions, CancellationToken)	Core implementation of session deserialization logic. (Inherited from DelegatingAIAgent)
GetService(Type, Object)	Asks the AIAgent for an object of the specified type `serviceType`. (Inherited from DelegatingAIAgent)
GetService<TService>(Object)	Asks the AIAgent for an object of type `TService`. (Inherited from AIAgent)
RunAsync(AgentSession, AgentRunOptions, CancellationToken)	Run the agent with no message assuming that all required instructions are already provided to the agent or on the session. (Inherited from AIAgent)
RunAsync(ChatMessage, AgentSession, AgentRunOptions, CancellationToken)	Runs the agent with a single chat message. (Inherited from AIAgent)
RunAsync(IEnumerable<ChatMessage>, AgentSession, AgentRunOptions, CancellationToken)	Runs the agent with a collection of chat messages, providing the core invocation logic that all other overloads delegate to. (Inherited from AIAgent)
RunAsync(String, AgentSession, AgentRunOptions, CancellationToken)	Runs the agent with a text message from the user. (Inherited from AIAgent)
RunAsync<T>(AgentSession, JsonSerializerOptions, AgentRunOptions, CancellationToken)	Run the agent with no message assuming that all required instructions are already provided to the agent or on the session, and requesting a response of the specified type `T`. (Inherited from AIAgent)
RunAsync<T>(ChatMessage, AgentSession, JsonSerializerOptions, AgentRunOptions, CancellationToken)	Runs the agent with a single chat message, requesting a response of the specified type `T`. (Inherited from AIAgent)
RunAsync<T>(IEnumerable<ChatMessage>, AgentSession, JsonSerializerOptions, AgentRunOptions, CancellationToken)	Runs the agent with a collection of chat messages, requesting a response of the specified type `T`. (Inherited from AIAgent)
RunAsync<T>(String, AgentSession, JsonSerializerOptions, AgentRunOptions, CancellationToken)	Runs the agent with a text message from the user, requesting a response of the specified type `T`. (Inherited from AIAgent)
RunCoreAsync(IEnumerable<ChatMessage>, AgentSession, AgentRunOptions, CancellationToken)	Core implementation of the agent invocation logic with a collection of chat messages. (Inherited from DelegatingAIAgent)
RunCoreStreamingAsync(IEnumerable<ChatMessage>, AgentSession, AgentRunOptions, CancellationToken)	Core implementation of the agent streaming invocation logic with a collection of chat messages. (Inherited from DelegatingAIAgent)
RunStreamingAsync(AgentSession, AgentRunOptions, CancellationToken)	Runs the agent in streaming mode without providing new input messages, relying on existing context and instructions. (Inherited from AIAgent)
RunStreamingAsync(ChatMessage, AgentSession, AgentRunOptions, CancellationToken)	Runs the agent in streaming mode with a single chat message. (Inherited from AIAgent)
RunStreamingAsync(IEnumerable<ChatMessage>, AgentSession, AgentRunOptions, CancellationToken)	Runs the agent in streaming mode with a collection of chat messages, providing the core streaming invocation logic. (Inherited from AIAgent)
RunStreamingAsync(String, AgentSession, AgentRunOptions, CancellationToken)	Runs the agent in streaming mode with a text message from the user. (Inherited from AIAgent)
SerializeSessionAsync(AgentSession, JsonSerializerOptions, CancellationToken)	Serializes an agent session to its JSON representation. (Inherited from AIAgent)
SerializeSessionCoreAsync(AgentSession, JsonSerializerOptions, CancellationToken)	Core implementation of session serialization logic. (Inherited from DelegatingAIAgent)

Extension Methods

Name	Description
AsAIFunction(AIAgent, AIFunctionFactoryOptions, AgentSession)	Creates an AIFunction that runs the provided AIAgent.
AsBuilder(AIAgent)	Creates a new AIAgentBuilder using the specified agent as the foundation for the builder pipeline.
AsDurableAgentProxy(AIAgent, IServiceProvider)	Converts an AIAgent to a durable agent proxy.
BindAsExecutor(AIAgent, AIAgentHostOptions)	Configure an AIAgent as an executor for use in a workflow.
BindAsExecutor(AIAgent, Boolean)	Configure an AIAgent as an executor for use in a workflow.
EvaluateAsync(AIAgent, IEnumerable<AgentResponse>, IEnumerable<String>, IAgentEvaluator, String, IEnumerable<String>, IEnumerable<IEnumerable<ExpectedToolCall>>, CancellationToken)	Evaluates pre-existing agent responses without re-running the agent.
EvaluateAsync(AIAgent, IEnumerable<AgentResponse>, IEnumerable<String>, IEvaluator, ChatConfiguration, String, IEnumerable<String>, IEnumerable<IEnumerable<ExpectedToolCall>>, CancellationToken)	Evaluates pre-existing agent responses using an MEAI evaluator directly.
EvaluateAsync(AIAgent, IEnumerable<String>, IAgentEvaluator, String, IEnumerable<String>, IEnumerable<IEnumerable<ExpectedToolCall>>, IConversationSplitter, Int32, CancellationToken)	Evaluates an agent by running it against test queries and scoring the responses.
EvaluateAsync(AIAgent, IEnumerable<String>, IEnumerable<IAgentEvaluator>, String, IEnumerable<String>, IEnumerable<IEnumerable<ExpectedToolCall>>, IConversationSplitter, Int32, CancellationToken)	Evaluates an agent by running it against test queries with multiple evaluators.
EvaluateAsync(AIAgent, IEnumerable<String>, IEvaluator, ChatConfiguration, String, IEnumerable<String>, IEnumerable<IEnumerable<ExpectedToolCall>>, IConversationSplitter, Int32, CancellationToken)	Evaluates an agent using an MEAI evaluator directly.
RunAsync(AIAgent, IEnumerable<ChatMessage>, AgentSession, AgentRunOptions, CancellationToken)	Runs the AI agent with a collection of OpenAI chat messages and returns the response as a native OpenAI OpenAI.Chat.ChatCompletion.
RunAsync(AIAgent, IEnumerable<ResponseItem>, AgentSession, AgentRunOptions, CancellationToken)	Runs the AI agent with a collection of OpenAI response items and returns the response as a native OpenAI OpenAI.Responses.ResponseResult.
RunStreamingAsync(AIAgent, IEnumerable<ChatMessage>, AgentSession, AgentRunOptions, CancellationToken)	Runs the AI agent with a single OpenAI chat message and returns the response as collection of native OpenAI OpenAI.Chat.StreamingChatCompletionUpdate.
RunStreamingAsync(AIAgent, IEnumerable<ResponseItem>, AgentSession, AgentRunOptions, CancellationToken)	Runs the AI agent in streaming mode with a collection of OpenAI response items and returns the response as a collection of native OpenAI OpenAI.Responses.StreamingResponseUpdate.

Applies to

Feedback

Was this page helpful?