Skip to content

Clarify validation before tool approval - #427

Open
Trym Håkansson (trymhaak) wants to merge 2 commits into
MicrosoftDocs:mainfrom
trymhaak:docs/clarify-tool-approval-validation
Open

Clarify validation before tool approval#427
Trym Håkansson (trymhaak) wants to merge 2 commits into
MicrosoftDocs:mainfrom
trymhaak:docs/clarify-tool-approval-validation

Conversation

@trymhaak

Copy link
Copy Markdown

Summary

Clarify that human approval is scoped to the exact tool call in the approval request.

The added note tells readers to:

  • validate the requested function name and arguments against the application's allowlist and current authorization policy;
  • require a new approval if the tool call changes.

This keeps the guidance next to the existing description of ToolApprovalRequestContent / function_approval_request without changing any language-specific API examples.

Validation

  • confirmed the target paragraph occurs exactly once on current upstream main
  • git diff --check passes
  • change is limited to one three-line Microsoft Learn callout

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit d7b337d:

✅ Validation status: passed

File Status Preview URL Details
agent-framework/workflows/human-in-the-loop.md ✅Succeeded

For more details, please refer to the build report.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit aee5703:

✅ Validation status: passed

File Status Preview URL Details
agent-framework/workflows/human-in-the-loop.md ✅Succeeded

For more details, please refer to the build report.

For interactive scenarios where an agent needs to gather more information from the user and iterate before proceeding; rather than only approving or rejecting a tool call; use the **[handoff orchestration](./orchestrations/handoff.md)**. Handoff is interactive by default: when an agent responds without handing off to another agent, control returns to the user for the next input, which enables multi-turn back-and-forth within the orchestration. Sequential, concurrent, and group chat orchestrations do not pause for free-form user input on their own; pair them with a `RequestPort` in a custom `WorkflowBuilder` workflow when you need that control between steps.

> [!IMPORTANT]
> Treat approval as scoped to the exact tool call in the request. Before sending an approval response, validate the requested function name and arguments against the application's allowlist and current authorization policy. If the call changes, require a new approval.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Before sending an approval response, validate the requested function name and arguments against the application's allowlist and current authorization policy

I'm not sure about this advice. After all, the application really shouldn't advertise functions that are against the application's allowlist in the first place. That seems like more sensible advice, since it wouldn't result in unnecessary of tools for approval, that cannot be executed anyway.

Doing additional validation against the arguments may make sense though, but mostly if validation couldn't happen in the funciton tool itself.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants