docs: sync from cloudflare/agents PR #731 - refactor tools

[agents-git-bot]

Summary

This PR syncs documentation updates from cloudflare/agents PR #731 which introduces breaking changes to the Agents SDK's tool and chat APIs.

Changes

• Breaking: Replace useAgent + useAgentChat two-hook pattern with unified useChat hook
• Breaking: New declarative tool configuration using confirm and execute properties
• Breaking: Simplified approval API with approve(id) and deny(id) instead of addToolResult()
• Add documentation for TOOL_CONFIRMATION protocol constants
• Update human-in-the-loop guide with complete examples using new API
• Update Agents API reference with new useChat hook documentation

Source PR

• Repository: cloudflare/agents
• PR Number: Update package.json #731
• PR Title: refactor tools
• PR URL: refactor tools  agents#731

Breaking Changes

These changes affect how users implement human-in-the-loop workflows:

Old pattern (deprecated):

const agent = useAgent({ agent: "my-agent" });
const { messages, sendMessage, addToolResult } = useAgentChat({
  agent,
  tools: clientTools,
  toolsRequiringConfirmation: ["toolA", "toolB"]
});
// Manual approval handling
addToolResult({ tool: "toolA", output: "Yes, confirmed.", toolCallId });

New pattern:

const { messages, sendMessage, approve, deny, pendingToolCalls } = useChat({
  agent: "my-agent",
  tools: clientTools // confirm property defines approval behavior
});
// Simple approval handling
approve(toolCallId);

Impact

• All users implementing human-in-the-loop workflows will need to migrate to the new API
• Tool configuration is now declarative with confirm: true/false instead of manual tracking lists
• Significantly simpler API surface for common use cases

---

🤖 Generated with Claude Code

[github-actions]

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
/src/content/docs/agents/	@irvinebroque, @rita3ko, @elithrar, @thomasgauvin, @threepointone, @whoiskatrin, @cloudflare/pcx-technical-writing, @cloudflare/ai-agents

[github-actions]

Preview URL: https://2133fe07.preview.developers.cloudflare.com
Preview Branch URL: https://sync-docs-pr-731.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link	Updated Link
https://developers.cloudflare.com/agents/guides/human-in-the-loop/	https://sync-docs-pr-731.preview.developers.cloudflare.com/agents/guides/human-in-the-loop/
https://developers.cloudflare.com/agents/api-reference/agents-api/	https://sync-docs-pr-731.preview.developers.cloudflare.com/agents/api-reference/agents-api/

[mattzcarey]

underlying pr was closed