导航|地址|刷新
Actions

Skip to contentDocumentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/agents/llms.txt
Use this file to discover all available pages before exploring further.

Docs Directory API SDKs Changelog

Search

Log in

Agents

/

Overview

Getting started

Quick start

Add to existing project

Testing your Agents

Concepts

What are agents?

Conversation state and memory

Tools

Calling LLMs

Using Agents with Workflows

Agentic patterns

Overview

Human-in-the-loop patterns

Long-running agents

Communication channels

Chat

Chat agents

Autonomous responses

Client SDK

Voice

Email

Slack

Webhooks

Overview

Push notifications

Tools

Sandbox

MCP

Browser

AI Search

Agentic Payments

Overview

Charge for HTTP content

x402

Overview

Charge for HTTP content

Charge for MCP tools

Pay from Agents SDK

Pay from coding tools

MPP (Machine Payments Protocol)

Code Mode

Overview

Create a durable Code Mode runtime

AI SDK integration

Use Code Mode with TanStack AI

Browser-owned tools

MCP

OpenAPI

How Code Mode works

Code Mode API reference

Harnesses

Overview

Think

Overview

Getting started

Configuration

Tools

Actions

Lifecycle hooks

Client tools

Messengers

Channels

Scheduled tasks

Workflows

Sub-agent RPC and programmatic turns

Programmatic submissions

Durable recovery

Runtime

Agents API

Lifecycle

Agent class internals

Callable methods

Store and sync state

Sessions

getCurrentAgent()

Communication

Routing

WebSockets

HTTP and Server-Sent Events

Chat SDK

Protocol messages

Readonly connections

Execution

Sub-agents

Schedule tasks

Durable execution with fibers

Queue tasks

Retries

Run Workflows

Agents as tools

Agent Skills

Operations

Configuration

Cross-domain authentication

Using AI Models

Observability

Examples

Chat agent

Slack agent

Voice agent

Browser agent

Email agent

Model Context Protocol (MCP)

Overview

APIs

MCP handler APIs

McpAgent

McpClient

Protocol

Tools

Authorization

Transport

MCP governance

Guides

Build MCP client

Build a Remote MCP server

Test a Remote MCP Server

Securing MCP servers

Connect to an MCP server

Handle OAuth with MCP servers

Migrate to MCP SDK v2

Build a single-tool Code Mode MCP server

Build a search and execute MCP server

Cloudflare

MCP server portals ↗

Cloudflare's own MCP servers

Overview

Cloudflare Community MCP Server

Code Mode MCP server patterns

Platform

Limits

Agent resources

Agent setup ↗

Cloudflare Skills ↗

Code Mode MCP Server ↗

Domain-specific MCP Servers ↗MCP

Agents llms.txt ↗

Agents llms-full.txt ↗

Cloudflare Docs llms.txt ↗

Cloudflare Docs llms-full.txt ↗

Home

/Agents

/…
Harnesses

/Think

/Actions

Actions

Last updated Jun 26, 2026|Copy as Markdown|View as Markdown|Agent setup

OverviewDefine an action Actions versus plain toolsIdempotency and the action ledger Pending rows and the retry leaseApprovals Approval-gated (the turn waits) Durable-pause (the turn parks and resumes later)AuthorizationReply attachmentsReference action(config) Hooks and methods on the agentRelated

Experimental

The Actions API surface may evolve before Think graduates out of experimental.

Actions are server-side tools with batteries included. Where a plain AI SDK tool() is just a description, a schema, and an execute function, an action() adds the things that are tedious and dangerous to get right by hand for a tool that has real side effects:

Idempotency — a durable ledger replays a settled result by a stable key instead of re-running the side effect on a recovery retry.

Approvals — gate a call behind a human, either inline (the turn waits) or durably (the turn parks and resumes later, even from a dashboard with no live socket).

Authorization — declare the permissions a call requires and grant them per-turn.

Reply attachments — record advisory delivery metadata (a drafted email, a card, a voice note) without changing what the model sees.

Actions compile into Think tools, so the model calls them exactly like any other tool. Return them from getActions(); Think merges them into the tool set alongside getTools(), workspace tools, extensions, and MCP tools.

Define an action

Use the action() descriptor factory and return a map of actions from getActions(). The map key is the tool name the model sees (unless you set name). The execute input type is inferred from inputSchema:

import { Think, action } from "@cloudflare/think";import { z } from "zod";export class Support extends Think { getActions() { return { refundOrder: action({ description: "Refund a customer order.", inputSchema: z.object({ orderId: z.string(), amountCents: z.number().int().positive(), }), execute: async ({ orderId, amountCents }, ctx) => { const result = await refund(orderId, amountCents); return { refundId: result.id, status: result.status }; }, }), }; }}

import { Think, action } from "@cloudflare/think";import { z } from "zod";export class Support extends Think<Env> { getActions() { return { refundOrder: action({ description: "Refund a customer order.", inputSchema: z.object({ orderId: z.string(), amountCents: z.number().int().positive(), }), execute: async ({ orderId, amountCents }, ctx) => { const result = await refund(orderId, amountCents); return { refundId: result.id, status: result.status }; }, }), }; }}

The execute callback receives the validated input and an ActionContext:
type ActionContext = { agent: Think; env: Cloudflare.Env; requestId: string; toolCallId: string; messages: ReadonlyArray<ModelMessage>; signal: AbortSignal; // aborts on turn cancel or after `timeoutMs` attachReply(attachment: ReplyAttachment): void;};
The action output is normalized to JSON and truncated before it is shown to the model (long outputs are capped). Anything thrown from execute becomes a structured { error: { name, message } } tool result rather than crashing the turn. Each action has a default timeout of 30 seconds; override it per action with timeoutMs.

Actions versus plain tools

A plain tool() from getTools() still works and is the right choice for a read-only or trivial tool. Reach for action() when a tool has side effects you must not run twice, needs human approval, or needs declarative authorization — the ledger, approval descriptors, default timeout, and structured error mapping only apply to actions.

Idempotency and the action ledger

When an action declares an idempotencyKey, Think records the settled result in a durable ledger keyed by action:<name>:<key>. If the same key is seen again — on a recovery retry, a reconnect, or a duplicate inbound event — Think returns the stored result without re-running execute, so the side effect happens at most once on the happy path.

const chargeInvoice = action({ description: "Charge an invoice.", inputSchema: z.object({ invoiceId: z.string() }), // Use a stable domain identifier — never a timestamp, request id, or random value. idempotencyKey: ({ input }) => `invoice:${input.invoiceId}`, execute: async ({ invoiceId }) => charge(invoiceId),});

const chargeInvoice = action({ description: "Charge an invoice.", inputSchema: z.object({ invoiceId: z.string() }), // Use a stable domain identifier — never a timestamp, request id, or random value. idempotencyKey: ({ input }) => `invoice:${input.invoiceId}`, execute: async ({ invoiceId }) => charge(invoiceId),});

idempotencyKey is a string, or a function ({ input, ctx }) => string. Choose a key that survives recovery retries — an order id, an inbound event id — and not a value that changes per attempt. An action with no idempotencyKey falls back to a per-toolCallId key, which only deduplicates within the same tool call, not across retries.

Pending rows and the retry lease

A ledger row is written as pending before execute runs and flipped to settled on success (a thrown or timed-out execute deletes the row so the call can be retried cleanly). If the isolate dies mid-execute, the row is left pending. By default such a stale row is reclaimed and the action re-run once the row is older than actionLedgerPendingRetryLeaseMs (default 5 minutes) — but only for actions that declare an explicit idempotencyKey, since that key is your assertion that re-running the keyed side effect is safe. A fresh pending row (or one without an explicit key) instead returns an ActionPendingError result so the model does not blindly retry an unknown state. Set actionLedgerPendingRetryLeaseMs = false to disable reclaim entirely and always surface ActionPendingError for a stale row.

Approvals

Gate an action behind a human with approval. There are two mechanisms, selected by kind.

Approval-gated (the turn waits)

The default when you set approval without a kind. The action compiles to a tool with the AI SDK needsApproval flag: the stream pauses with an approval-requested part, the client approves or rejects, and the turn continues inline. execute runs only after approval.

const deleteAccount = action({ description: "Permanently delete a user account.", inputSchema: z.object({ userId: z.string() }), approval: true, // or ({ input }) => input.userId !== currentUser approvalSummary: "Delete an account", approvalRisk: "high", execute: async ({ userId }) => deleteAccount(userId),});

const deleteAccount = action({ description: "Permanently delete a user account.", inputSchema: z.object({ userId: z.string() }), approval: true, // or ({ input }) => input.userId !== currentUser approvalSummary: "Delete an account", approvalRisk: "high", execute: async ({ userId }) => deleteAccount(userId),});

approval is a boolean or a predicate ({ input, ctx }) => boolean, so you can require approval only for risky inputs. approvalSummary and approvalRisk ("low" | "medium" | "high") populate the approval descriptor your UI renders.

Durable-pause (the turn parks and resumes later)

Set kind: "durable-pause" when approval may take minutes or days and you do not want to hold a connection open. The action parks into a durable store and the turn ends; execute does not run yet. Resume later — from anywhere, including a dashboard with no live WebSocket — with approveExecution() or rejectExecution():

const deploy = action({ description: "Deploy to production.", inputSchema: z.object({ ref: z.string() }), kind: "durable-pause", approvalSummary: "Deploy to production", approvalRisk: "high", permissions: ["deploy:run"], execute: async ({ ref }) => deploy(ref),});

const deploy = action({ description: "Deploy to production.", inputSchema: z.object({ ref: z.string() }), kind: "durable-pause", approvalSummary: "Deploy to production", approvalRisk: "high", permissions: ["deploy:run"], execute: async ({ ref }) => deploy(ref),});

// List everything waiting on a human (cold-load reconciliation):const pending = await agent.pendingApprovals();// [{ executionId, source: "action" | "codemode", descriptor }]// Approve or reject by execution id (idempotent — a second call is a no-op):await agent.approveExecution(executionId);await agent.rejectExecution(executionId, "Not this release");

// List everything waiting on a human (cold-load reconciliation):const pending = await agent.pendingApprovals();// [{ executionId, source: "action" | "codemode", descriptor }]// Approve or reject by execution id (idempotent — a second call is a no-op):await agent.approveExecution(executionId);await agent.rejectExecution(executionId, "Not this release");

approveExecution() runs execute once and auto-continues the turn even if no client is connected; rejectExecution() resolves the action without running it. pendingApprovals() merges parked actions and paused Codemode executions, so a single approval UI can drive both. (durable-pause requires an approval policy — an action that would never park is rejected at definition time.)

Both approval-gated and durable-pause parts carry a stable ActionApprovalDescriptor ({ requestId, toolCallId, action, summary, input, permissions, risk, kind }) so your UI has everything it needs to render the prompt.

Authorization

Declare the permissions an action requires with permissions, then grant them per turn. By default every turn is fully authorized, so authorization is opt-in.

const refundOrder = action({ description: "Refund a customer order.", inputSchema: z.object({ orderId: z.string() }), permissions: ["billing:refund"], // or ({ input }) => [...] execute: async ({ orderId }) => refund(orderId),});

const refundOrder = action({ description: "Refund a customer order.", inputSchema: z.object({ orderId: z.string() }), permissions: ["billing:refund"], // or ({ input }) => [...] execute: async ({ orderId }) => refund(orderId),});

Override authorizeTurn() to decide, once per turn, which permissions are granted. Returning a list narrows the grant; any action requiring a permission outside the set is denied with a structured ActionAuthorizationError (the model never calls execute):

export class Support extends Think { authorizeTurn(ctx) { const role = ctx.body?.role; if (role === "admin") return true; // full grant (the default) return { allowed: true, grantedPermissions: ["billing:read"] }; }}

export class Support extends Think<Env> { override authorizeTurn(ctx: TurnContext): ActionAuthorizationDecision { const role = (ctx.body as { role?: string })?.role; if (role === "admin") return true; // full grant (the default) return { allowed: true, grantedPermissions: ["billing:read"] }; }}

authorizeTurn() returns true (full grant), false (deny all), or { allowed, reason?, grantedPermissions? }. For per-call logic, override authorizeAction(ctx) instead — it receives the action name, kind, input, and required and granted permissions.

Reply attachments

An action can record advisory delivery metadata for the turn — a drafted email, a card, a voice note — with ctx.attachReply(). Attachments never change the tool output the model sees; they ride alongside the response for your delivery layer to render.

const draftReply = action({ description: "Draft an email reply.", inputSchema: z.object({ to: z.string(), subject: z.string() }), execute: async ({ to, subject }, ctx) => { ctx.attachReply({ type: "email_draft", to: [to], subject }); return { drafted: true }; },});

const draftReply = action({ description: "Draft an email reply.", inputSchema: z.object({ to: z.string(), subject: z.string() }), execute: async ({ to, subject }, ctx) => { ctx.attachReply({ type: "email_draft", to: [to], subject }); return { drafted: true }; },});

Read the attachments after the turn from the onChatResponse() hook, or from the replyAttachments(requestId?) getter:

export class Support extends Think { async onChatResponse(result) { for (const attachment of result.attachments ?? []) { // attachment.type === "email_draft" | "card" | "voice_note" | custom } }}

…(内容过长已截断)

------
导航页打开网址