agents 0.20.1 → 0.21.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +50 -12
- package/dist/{agent-tool-types-BC-WFlsz.d.ts → agent-tool-types-CzGGB-20.d.ts} +375 -72
- package/dist/agent-tool-types.d.ts +1 -1
- package/dist/{agent-tools-DeHe9Xov.d.ts → agent-tools-zR2d5uij.d.ts} +2 -2
- package/dist/agent-tools.d.ts +24 -8
- package/dist/agent-tools.js +14 -6
- package/dist/agent-tools.js.map +1 -1
- package/dist/browser/ai.d.ts +5 -3
- package/dist/browser/ai.js +86 -7
- package/dist/browser/ai.js.map +1 -1
- package/dist/browser/index.d.ts +1 -1
- package/dist/browser/index.js +1 -1
- package/dist/browser/tanstack-ai.js +13 -1
- package/dist/browser/tanstack-ai.js.map +1 -1
- package/dist/chat/index.d.ts +31 -2
- package/dist/chat/index.js +57 -2
- package/dist/chat/index.js.map +1 -1
- package/dist/chat/react.d.ts +5 -179
- package/dist/chat/react.js +18 -555
- package/dist/chat/react.js.map +1 -1
- package/dist/chat/transport.d.ts +10 -0
- package/dist/chat/transport.js +2 -0
- package/dist/chat-sdk/index.d.ts +1 -1
- package/dist/client.d.ts +1 -1
- package/dist/{connector-v2M1zlZp.d.ts → connector-CkQD4MK3.d.ts} +20 -3
- package/dist/{connector-KEJnl6e5.js → connector-CptFKzRh.js} +158 -40
- package/dist/connector-CptFKzRh.js.map +1 -0
- package/dist/index.d.ts +20 -12
- package/dist/index.js +5 -4
- package/dist/index.js.map +1 -1
- package/dist/mcp/client.d.ts +20 -20
- package/dist/mcp/index.d.ts +35 -35
- package/dist/observability/ai/index.d.ts +1 -130
- package/dist/observability/ai/index.js +39 -399
- package/dist/observability/ai/index.js.map +1 -1
- package/dist/{wire-types-CU9rLoeS.js → protocol-Dqc2MQxo.js} +2 -46
- package/dist/protocol-Dqc2MQxo.js.map +1 -0
- package/dist/react.d.ts +1 -1
- package/dist/react.js +5 -8
- package/dist/react.js.map +1 -1
- package/dist/serializable.d.ts +1 -1
- package/dist/sub-routing.d.ts +18 -6
- package/dist/sub-routing.js +92 -2
- package/dist/sub-routing.js.map +1 -1
- package/dist/wire-types-CnMt6_HR.js +47 -0
- package/dist/wire-types-CnMt6_HR.js.map +1 -0
- package/dist/workflow-types.d.ts +25 -25
- package/dist/workflow-types.js.map +1 -1
- package/dist/workflows.d.ts +22 -22
- package/dist/ws-chat-transport-CIoOBbO7.js +561 -0
- package/dist/ws-chat-transport-CIoOBbO7.js.map +1 -0
- package/dist/ws-chat-transport-UNRIS2xl.d.ts +184 -0
- package/docs/adding-to-existing-project.md +4 -2
- package/docs/agent-class.md +1 -1
- package/docs/agent-tools.md +29 -0
- package/docs/browse-the-web.md +16 -1
- package/docs/chat-agents.md +3 -1
- package/docs/client-sdk.md +12 -8
- package/docs/configuration.md +7 -1
- package/docs/cross-domain-authentication.md +7 -35
- package/docs/email.md +2 -13
- package/docs/human-in-the-loop.md +15 -12
- package/docs/long-running-agents.md +11 -11
- package/docs/mcp-servers.md +6 -0
- package/docs/mcp-transports.md +18 -12
- package/docs/migration-to-ai-sdk-v5.md +2 -2
- package/docs/migration-to-ai-sdk-v6.md +5 -1
- package/docs/observability.md +22 -66
- package/docs/routing.md +27 -0
- package/docs/sub-agents.md +47 -2
- package/docs/webhooks.md +109 -136
- package/docs/workflows.md +9 -1
- package/package.json +13 -4
- package/dist/connector-KEJnl6e5.js.map +0 -1
- package/dist/wire-types-CU9rLoeS.js.map +0 -1
- package/dist/workflow-types-Baz_PO5v.d.ts +0 -280
package/README.md
CHANGED
|
@@ -16,6 +16,11 @@ Or add to an existing project:
|
|
|
16
16
|
npm install agents
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
+
The examples below use `@callable()` decorators. Vite projects must extend
|
|
20
|
+
`agents/tsconfig` and add the `agents/vite` plugin; other bundlers must support
|
|
21
|
+
TC39 decorators (`2023-11`). See
|
|
22
|
+
[Adding Agents to an Existing Project](../../docs/agents/adding-to-existing-project.md#4-configure-typescript-and-vite).
|
|
23
|
+
|
|
19
24
|
---
|
|
20
25
|
|
|
21
26
|
## Why Agents, Why Now
|
|
@@ -44,7 +49,7 @@ A counter agent with real-time state sync and callable methods:
|
|
|
44
49
|
// server.ts
|
|
45
50
|
import { Agent, callable } from "agents";
|
|
46
51
|
|
|
47
|
-
type State = { count: number };
|
|
52
|
+
export type State = { count: number };
|
|
48
53
|
|
|
49
54
|
export class CounterAgent extends Agent<Env, State> {
|
|
50
55
|
initialState: State = { count: 0 };
|
|
@@ -67,11 +72,12 @@ export class CounterAgent extends Agent<Env, State> {
|
|
|
67
72
|
// client.tsx
|
|
68
73
|
import { useAgent } from "agents/react";
|
|
69
74
|
import { useState } from "react";
|
|
75
|
+
import type { CounterAgent, State } from "./server";
|
|
70
76
|
|
|
71
77
|
function Counter() {
|
|
72
78
|
const [count, setCount] = useState(0);
|
|
73
79
|
|
|
74
|
-
const agent = useAgent<State>({
|
|
80
|
+
const agent = useAgent<CounterAgent, State>({
|
|
75
81
|
agent: "counter-agent",
|
|
76
82
|
name: "my-counter",
|
|
77
83
|
onStateUpdate: (state) => setCount(state.count)
|
|
@@ -120,8 +126,12 @@ Platform Observability · Cross-domain auth · Resumable streams
|
|
|
120
126
|
State persists across requests and syncs to all connected clients:
|
|
121
127
|
|
|
122
128
|
```typescript
|
|
123
|
-
|
|
124
|
-
|
|
129
|
+
import { Agent, callable, type Connection } from "agents";
|
|
130
|
+
|
|
131
|
+
type State = { items: string[] };
|
|
132
|
+
|
|
133
|
+
export class MyAgent extends Agent<Env, State> {
|
|
134
|
+
initialState: State = { items: [] };
|
|
125
135
|
|
|
126
136
|
@callable()
|
|
127
137
|
addItem(item: string) {
|
|
@@ -262,6 +272,29 @@ export class Assistant extends Think<Env> {
|
|
|
262
272
|
}
|
|
263
273
|
```
|
|
264
274
|
|
|
275
|
+
`inputSchema` accepts schemas supported by the AI SDK, including Zod, Standard
|
|
276
|
+
JSON Schema-compatible schemas, raw JSON Schema through `jsonSchema()`, and
|
|
277
|
+
schemas exposed through AI SDK adapters. For example, use `@ai-sdk/valibot` v2
|
|
278
|
+
with AI SDK 6 or v3 with AI SDK 7:
|
|
279
|
+
|
|
280
|
+
```typescript
|
|
281
|
+
import { valibotSchema } from "@ai-sdk/valibot";
|
|
282
|
+
import * as v from "valibot";
|
|
283
|
+
|
|
284
|
+
const researchInput = valibotSchema(
|
|
285
|
+
v.object({ query: v.pipe(v.string(), v.minLength(3)) })
|
|
286
|
+
);
|
|
287
|
+
|
|
288
|
+
agentTool(Researcher, {
|
|
289
|
+
description: "Research one topic in depth.",
|
|
290
|
+
inputSchema: researchInput
|
|
291
|
+
});
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
Tool inputs need model-facing JSON Schema in addition to runtime validation. A
|
|
295
|
+
validation-only Standard Schema is therefore insufficient; use its Standard
|
|
296
|
+
JSON Schema extension or an AI SDK adapter.
|
|
297
|
+
|
|
265
298
|
For deterministic fan-out, call `this.runAgentTool(Researcher, { input })`
|
|
266
299
|
directly. Parent recovery reconciles stale child rows after restarts and marks
|
|
267
300
|
unrecoverable runs `interrupted` instead of hanging. In React, use
|
|
@@ -294,7 +327,9 @@ async onClose(connection: Connection) {
|
|
|
294
327
|
Agents can receive and respond to emails:
|
|
295
328
|
|
|
296
329
|
```typescript
|
|
297
|
-
|
|
330
|
+
import type { AgentEmail } from "agents/email";
|
|
331
|
+
|
|
332
|
+
async onEmail(email: AgentEmail) {
|
|
298
333
|
const from = email.from;
|
|
299
334
|
const subject = email.headers.get("subject");
|
|
300
335
|
// Process incoming email
|
|
@@ -392,15 +427,18 @@ For AI-powered chat experiences with persistent conversations, streaming respons
|
|
|
392
427
|
|
|
393
428
|
```typescript
|
|
394
429
|
import { AIChatAgent } from "@cloudflare/ai-chat";
|
|
430
|
+
import { createWorkersAI } from "workers-ai-provider";
|
|
431
|
+
import { convertToModelMessages, streamText } from "ai";
|
|
395
432
|
|
|
396
433
|
export class ChatAgent extends AIChatAgent<Env> {
|
|
397
|
-
async onChatMessage(
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
onFinish
|
|
434
|
+
async onChatMessage() {
|
|
435
|
+
const workersai = createWorkersAI({ binding: this.env.AI });
|
|
436
|
+
const result = streamText({
|
|
437
|
+
model: workersai("@cf/moonshotai/kimi-k2.7-code"),
|
|
438
|
+
messages: await convertToModelMessages(this.messages)
|
|
403
439
|
});
|
|
440
|
+
|
|
441
|
+
return result.toUIMessageStreamResponse();
|
|
404
442
|
}
|
|
405
443
|
}
|
|
406
444
|
```
|
|
@@ -409,7 +447,7 @@ export class ChatAgent extends AIChatAgent<Env> {
|
|
|
409
447
|
// Client
|
|
410
448
|
import { useAgentChat } from "@cloudflare/ai-chat/react";
|
|
411
449
|
|
|
412
|
-
const { messages,
|
|
450
|
+
const { messages, sendMessage } = useAgentChat({
|
|
413
451
|
agent: useAgent({ agent: "chat-agent" })
|
|
414
452
|
});
|
|
415
453
|
```
|
|
@@ -18,17 +18,14 @@ import {
|
|
|
18
18
|
u as McpClientOptions
|
|
19
19
|
} from "./handler-stateless-C_bo-Ytq.js";
|
|
20
20
|
import { n as LegacyCallToolResultSchema } from "./client-invoker-BNSZxAkv.js";
|
|
21
|
-
import {
|
|
22
|
-
_ as WorkflowEventPayload,
|
|
23
|
-
d as WorkflowCallback,
|
|
24
|
-
l as RunWorkflowOptions,
|
|
25
|
-
v as WorkflowInfo,
|
|
26
|
-
x as WorkflowQueryCriteria,
|
|
27
|
-
y as WorkflowPage
|
|
28
|
-
} from "./workflow-types-Baz_PO5v.js";
|
|
29
21
|
import { t as MessageType } from "./types-6Zo2zfoO.js";
|
|
30
22
|
import { r as EmailResolver } from "./email-CL27preh.js";
|
|
31
|
-
import {
|
|
23
|
+
import {
|
|
24
|
+
RpcTarget,
|
|
25
|
+
WorkflowEvent,
|
|
26
|
+
WorkflowSleepDuration,
|
|
27
|
+
WorkflowStep
|
|
28
|
+
} from "cloudflare:workers";
|
|
32
29
|
import {
|
|
33
30
|
Connection,
|
|
34
31
|
Connection as Connection$1,
|
|
@@ -136,6 +133,47 @@ declare function withInvocationScope<T>(
|
|
|
136
133
|
* token everywhere (parent fetch, client, helpers).
|
|
137
134
|
*/
|
|
138
135
|
declare const SUB_PREFIX = "sub";
|
|
136
|
+
/** One agent identity in a root-first address chain. */
|
|
137
|
+
interface AgentPathStep {
|
|
138
|
+
/** Agent class name as exported by the Worker. */
|
|
139
|
+
className: string;
|
|
140
|
+
/** Logical Agent instance name. */
|
|
141
|
+
name: string;
|
|
142
|
+
}
|
|
143
|
+
interface BuildAgentPathOptions {
|
|
144
|
+
/** Top-level route prefix. Must match `routeAgentRequest`; defaults to `agents`. */
|
|
145
|
+
prefix?: string;
|
|
146
|
+
/** Pathname suffix appended after the destination Agent identity. */
|
|
147
|
+
leafPath?: string;
|
|
148
|
+
/** Root Durable Object binding name, when it differs from the root class name. */
|
|
149
|
+
rootBinding?: string;
|
|
150
|
+
}
|
|
151
|
+
/** @internal Build the strictly validated path tail for sub-agent routing. */
|
|
152
|
+
declare function buildSubAgentPath(
|
|
153
|
+
path: ReadonlyArray<AgentPathStep>,
|
|
154
|
+
leafPath?: string
|
|
155
|
+
): string;
|
|
156
|
+
/** @internal Preserve React's tolerant path composition for disabled placeholders. */
|
|
157
|
+
declare function buildSubAgentPathUnchecked(
|
|
158
|
+
path: ReadonlyArray<AgentPathStep>,
|
|
159
|
+
leafPath?: string
|
|
160
|
+
): string;
|
|
161
|
+
/**
|
|
162
|
+
* Build the canonical pathname for a root Agent or nested sub-agent.
|
|
163
|
+
*
|
|
164
|
+
* The address is root-first and accepts `Agent#selfPath`. Pass
|
|
165
|
+
* `rootBinding` when the root Durable Object binding and class names differ.
|
|
166
|
+
*/
|
|
167
|
+
declare function buildAgentPath(
|
|
168
|
+
path: ReadonlyArray<AgentPathStep>,
|
|
169
|
+
options?: BuildAgentPathOptions
|
|
170
|
+
): string;
|
|
171
|
+
/** Build an absolute URL for a root Agent or nested sub-agent. */
|
|
172
|
+
declare function buildAgentUrl(
|
|
173
|
+
origin: string | URL,
|
|
174
|
+
path: ReadonlyArray<AgentPathStep>,
|
|
175
|
+
options?: BuildAgentPathOptions
|
|
176
|
+
): URL;
|
|
139
177
|
interface SubAgentPathMatch {
|
|
140
178
|
/** CamelCase class name of the child, as it appears in `ctx.exports`. */
|
|
141
179
|
childClass: string;
|
|
@@ -2572,6 +2610,251 @@ declare function getNamespacedData<T extends keyof NamespacedData>(
|
|
|
2572
2610
|
type: T
|
|
2573
2611
|
): NamespacedData[T];
|
|
2574
2612
|
//#endregion
|
|
2613
|
+
//#region src/workflow-types.d.ts
|
|
2614
|
+
type AgentWorkflowPathStep = AgentPathStep;
|
|
2615
|
+
type AgentWorkflowOrigin =
|
|
2616
|
+
| {
|
|
2617
|
+
kind: "agent";
|
|
2618
|
+
version: 1 /** Environment binding name for the top-level Agent namespace */;
|
|
2619
|
+
binding: string /** Name/ID of the top-level Agent */;
|
|
2620
|
+
name: string;
|
|
2621
|
+
}
|
|
2622
|
+
| {
|
|
2623
|
+
kind: "facet";
|
|
2624
|
+
version: 1 /** Environment binding name for the root Agent namespace */;
|
|
2625
|
+
rootBinding: string /** Root-first path to the originating facet, including itself */;
|
|
2626
|
+
path: AgentWorkflowPathStep[];
|
|
2627
|
+
};
|
|
2628
|
+
/**
|
|
2629
|
+
* Type alias for WorkflowEvent in AgentWorkflow context.
|
|
2630
|
+
* Identical to WorkflowEvent - provided for naming consistency with AgentWorkflowStep.
|
|
2631
|
+
*/
|
|
2632
|
+
type AgentWorkflowEvent<Params = unknown> = WorkflowEvent<Params>;
|
|
2633
|
+
/**
|
|
2634
|
+
* Extended WorkflowStep with durable Agent communication methods.
|
|
2635
|
+
* All added methods on this interface are durable - they're idempotent and won't
|
|
2636
|
+
* repeat on workflow retry.
|
|
2637
|
+
*/
|
|
2638
|
+
interface AgentWorkflowStep extends WorkflowStep {
|
|
2639
|
+
/**
|
|
2640
|
+
* Report successful completion to the Agent (durable).
|
|
2641
|
+
* Triggers onWorkflowComplete() on the Agent.
|
|
2642
|
+
* @param result - Optional result data
|
|
2643
|
+
*/
|
|
2644
|
+
reportComplete<T = unknown>(result?: T): Promise<void>;
|
|
2645
|
+
/**
|
|
2646
|
+
* Report an error to the Agent (durable).
|
|
2647
|
+
* Triggers onWorkflowError() on the Agent.
|
|
2648
|
+
* @param error - Error or error message
|
|
2649
|
+
*/
|
|
2650
|
+
reportError(error: Error | string): Promise<void>;
|
|
2651
|
+
/**
|
|
2652
|
+
* Send a custom event to the Agent (durable).
|
|
2653
|
+
* Triggers onWorkflowEvent() on the Agent.
|
|
2654
|
+
* @param event - Custom event payload
|
|
2655
|
+
*/
|
|
2656
|
+
sendEvent<T = unknown>(event: T): Promise<void>;
|
|
2657
|
+
/**
|
|
2658
|
+
* Update the Agent's state entirely (durable).
|
|
2659
|
+
* This will replace the Agent's state and broadcast to all connected clients.
|
|
2660
|
+
* @param state - New state to set
|
|
2661
|
+
*/
|
|
2662
|
+
updateAgentState(state: unknown): Promise<void>;
|
|
2663
|
+
/**
|
|
2664
|
+
* Merge partial state into the Agent's existing state (durable).
|
|
2665
|
+
* Performs a shallow merge and broadcasts to all connected clients.
|
|
2666
|
+
* @param partialState - Partial state to merge
|
|
2667
|
+
*/
|
|
2668
|
+
mergeAgentState(partialState: Record<string, unknown>): Promise<void>;
|
|
2669
|
+
/**
|
|
2670
|
+
* Reset the Agent's state to its initialState (durable).
|
|
2671
|
+
* Broadcasts the reset state to all connected clients.
|
|
2672
|
+
*/
|
|
2673
|
+
resetAgentState(): Promise<void>;
|
|
2674
|
+
}
|
|
2675
|
+
/**
|
|
2676
|
+
* Internal parameters injected by runWorkflow() to identify the originating Agent
|
|
2677
|
+
*/
|
|
2678
|
+
type AgentWorkflowInternalParams = {
|
|
2679
|
+
/** Name/ID of the Agent that started this workflow */ __agentName: string /** Environment binding name for the Agent's namespace */;
|
|
2680
|
+
__agentBinding: string /** Workflow binding name (for callbacks) */;
|
|
2681
|
+
__workflowName: string /** Versioned origin identity for top-level Agents and sub-agent facets */;
|
|
2682
|
+
__agentOrigin?: AgentWorkflowOrigin;
|
|
2683
|
+
};
|
|
2684
|
+
/**
|
|
2685
|
+
* Combined workflow params: user params + internal agent params
|
|
2686
|
+
*/
|
|
2687
|
+
type AgentWorkflowParams<T = unknown> = T & AgentWorkflowInternalParams;
|
|
2688
|
+
/**
|
|
2689
|
+
* Workflow callback types for Agent-Workflow communication
|
|
2690
|
+
*/
|
|
2691
|
+
type WorkflowCallbackType = "progress" | "complete" | "error" | "event";
|
|
2692
|
+
/**
|
|
2693
|
+
* Base callback structure sent from Workflow to Agent
|
|
2694
|
+
*/
|
|
2695
|
+
type WorkflowCallbackBase = {
|
|
2696
|
+
/** Workflow binding name */ workflowName: string /** ID of the workflow instance */;
|
|
2697
|
+
workflowId: string /** Type of callback */;
|
|
2698
|
+
type: WorkflowCallbackType /** Timestamp when callback was sent */;
|
|
2699
|
+
timestamp: number;
|
|
2700
|
+
};
|
|
2701
|
+
/**
|
|
2702
|
+
* Default progress type - covers common use cases.
|
|
2703
|
+
* Developers can define their own progress type for domain-specific needs.
|
|
2704
|
+
*/
|
|
2705
|
+
type DefaultProgress = {
|
|
2706
|
+
/** Current step name */ step?: string /** Step/overall status */;
|
|
2707
|
+
status?:
|
|
2708
|
+
| "pending"
|
|
2709
|
+
| "running"
|
|
2710
|
+
| "complete"
|
|
2711
|
+
| "error" /** Human-readable message */;
|
|
2712
|
+
message?: string /** Progress percentage (0-1) */;
|
|
2713
|
+
percent?: number /** Allow additional custom fields */;
|
|
2714
|
+
[key: string]: unknown;
|
|
2715
|
+
};
|
|
2716
|
+
/**
|
|
2717
|
+
* Progress callback - reports workflow progress with typed payload
|
|
2718
|
+
*/
|
|
2719
|
+
type WorkflowProgressCallback<P = DefaultProgress> = WorkflowCallbackBase & {
|
|
2720
|
+
type: "progress" /** Typed progress data */;
|
|
2721
|
+
progress: P;
|
|
2722
|
+
};
|
|
2723
|
+
/**
|
|
2724
|
+
* Complete callback - workflow finished successfully
|
|
2725
|
+
*/
|
|
2726
|
+
type WorkflowCompleteCallback = WorkflowCallbackBase & {
|
|
2727
|
+
type: "complete" /** Result of the workflow */;
|
|
2728
|
+
result?: unknown;
|
|
2729
|
+
};
|
|
2730
|
+
/**
|
|
2731
|
+
* Error callback - workflow encountered an error
|
|
2732
|
+
*/
|
|
2733
|
+
type WorkflowErrorCallback = WorkflowCallbackBase & {
|
|
2734
|
+
type: "error" /** Error message */;
|
|
2735
|
+
error: string;
|
|
2736
|
+
};
|
|
2737
|
+
/**
|
|
2738
|
+
* Event callback - custom event from workflow
|
|
2739
|
+
*/
|
|
2740
|
+
type WorkflowEventCallback = WorkflowCallbackBase & {
|
|
2741
|
+
type: "event" /** Custom event payload */;
|
|
2742
|
+
event: unknown;
|
|
2743
|
+
};
|
|
2744
|
+
/**
|
|
2745
|
+
* Union of all callback types
|
|
2746
|
+
*/
|
|
2747
|
+
type WorkflowCallback<P = DefaultProgress> =
|
|
2748
|
+
| WorkflowProgressCallback<P>
|
|
2749
|
+
| WorkflowCompleteCallback
|
|
2750
|
+
| WorkflowErrorCallback
|
|
2751
|
+
| WorkflowEventCallback;
|
|
2752
|
+
/**
|
|
2753
|
+
* Workflow status values - derived from Cloudflare's InstanceStatus
|
|
2754
|
+
*/
|
|
2755
|
+
type WorkflowStatus = InstanceStatus["status"];
|
|
2756
|
+
/**
|
|
2757
|
+
* Row structure for cf_agents_workflows tracking table
|
|
2758
|
+
*/
|
|
2759
|
+
type WorkflowTrackingRow = {
|
|
2760
|
+
/** Internal row ID (UUID) */ id: string /** Cloudflare Workflow instance ID */;
|
|
2761
|
+
workflow_id: string /** Workflow binding name */;
|
|
2762
|
+
workflow_name: string /** Current workflow status */;
|
|
2763
|
+
status: WorkflowStatus /** JSON-serialized metadata for querying */;
|
|
2764
|
+
metadata: string | null /** Error name if workflow failed */;
|
|
2765
|
+
error_name: string | null /** Error message if workflow failed */;
|
|
2766
|
+
error_message: string | null /** Unix timestamp when workflow was created */;
|
|
2767
|
+
created_at: number /** Unix timestamp when workflow was last updated */;
|
|
2768
|
+
updated_at: number /** Unix timestamp when workflow completed (null if not complete) */;
|
|
2769
|
+
completed_at: number | null;
|
|
2770
|
+
};
|
|
2771
|
+
/**
|
|
2772
|
+
* Options for runWorkflow()
|
|
2773
|
+
*/
|
|
2774
|
+
type RunWorkflowOptions = {
|
|
2775
|
+
/** Custom workflow instance ID (auto-generated if not provided) */ id?: string /** Optional metadata for querying (stored as JSON) */;
|
|
2776
|
+
metadata?: Record<
|
|
2777
|
+
string,
|
|
2778
|
+
unknown
|
|
2779
|
+
> /** Agent binding name (auto-detected from class name if not provided) */;
|
|
2780
|
+
agentBinding?: string /** Retention policy for the underlying Workflow instance */;
|
|
2781
|
+
retention?: WorkflowInstanceCreateOptions["retention"];
|
|
2782
|
+
};
|
|
2783
|
+
/**
|
|
2784
|
+
* Event payload for sendWorkflowEvent()
|
|
2785
|
+
*/
|
|
2786
|
+
type WorkflowEventPayload = {
|
|
2787
|
+
/** Event type name */ type: string /** Event payload data */;
|
|
2788
|
+
payload: unknown;
|
|
2789
|
+
};
|
|
2790
|
+
/**
|
|
2791
|
+
* Parsed workflow tracking info returned by getWorkflow()
|
|
2792
|
+
*/
|
|
2793
|
+
type WorkflowInfo = {
|
|
2794
|
+
/** Internal row ID */ id: string /** Cloudflare Workflow instance ID */;
|
|
2795
|
+
workflowId: string /** Workflow binding name */;
|
|
2796
|
+
workflowName: string /** Current workflow status */;
|
|
2797
|
+
status: WorkflowStatus /** Metadata (parsed from JSON) */;
|
|
2798
|
+
metadata: Record<string, unknown> | null /** Error info if workflow failed */;
|
|
2799
|
+
error: {
|
|
2800
|
+
name: string;
|
|
2801
|
+
message: string;
|
|
2802
|
+
} | null /** When workflow was created */;
|
|
2803
|
+
createdAt: Date /** When workflow was last updated */;
|
|
2804
|
+
updatedAt: Date /** When workflow completed (null if not complete) */;
|
|
2805
|
+
completedAt: Date | null;
|
|
2806
|
+
};
|
|
2807
|
+
/**
|
|
2808
|
+
* Criteria for querying tracked workflows
|
|
2809
|
+
*/
|
|
2810
|
+
type WorkflowQueryCriteria = {
|
|
2811
|
+
/** Filter by status */ status?:
|
|
2812
|
+
| WorkflowStatus
|
|
2813
|
+
| WorkflowStatus[] /** Filter by workflow binding name */;
|
|
2814
|
+
workflowName?: string /** Filter by metadata key-value pairs (exact match) */;
|
|
2815
|
+
metadata?: Record<
|
|
2816
|
+
string,
|
|
2817
|
+
string | number | boolean
|
|
2818
|
+
> /** Limit number of results (default 50, max 100) */;
|
|
2819
|
+
limit?: number /** Order by created_at */;
|
|
2820
|
+
orderBy?:
|
|
2821
|
+
| "asc"
|
|
2822
|
+
| "desc" /** Cursor for pagination (from previous WorkflowPage.nextCursor) */;
|
|
2823
|
+
cursor?: string;
|
|
2824
|
+
};
|
|
2825
|
+
/**
|
|
2826
|
+
* Paginated result from getWorkflows()
|
|
2827
|
+
*/
|
|
2828
|
+
type WorkflowPage = {
|
|
2829
|
+
/** Workflows for this page */ workflows: WorkflowInfo[] /** Total count of workflows matching the criteria (ignoring pagination) */;
|
|
2830
|
+
total: number /** Cursor for next page, or null if no more pages */;
|
|
2831
|
+
nextCursor: string | null;
|
|
2832
|
+
};
|
|
2833
|
+
/**
|
|
2834
|
+
* Standard approval event payload used by approveWorkflow/rejectWorkflow
|
|
2835
|
+
*/
|
|
2836
|
+
type ApprovalEventPayload = {
|
|
2837
|
+
/** Whether the workflow was approved */ approved: boolean /** Optional reason for approval/rejection */;
|
|
2838
|
+
reason?: string /** Optional additional metadata */;
|
|
2839
|
+
metadata?: Record<string, unknown>;
|
|
2840
|
+
};
|
|
2841
|
+
/**
|
|
2842
|
+
* Options for waitForApproval()
|
|
2843
|
+
*/
|
|
2844
|
+
type WaitForApprovalOptions = {
|
|
2845
|
+
/** Step name for waitForEvent (default: "wait-for-approval") */ stepName?: string /** Timeout duration (e.g., "7 days") */;
|
|
2846
|
+
timeout?: WorkflowSleepDuration /** Event type to wait for (default: "approval") */;
|
|
2847
|
+
eventType?: string;
|
|
2848
|
+
};
|
|
2849
|
+
/**
|
|
2850
|
+
* Error thrown when a workflow is rejected via rejectWorkflow()
|
|
2851
|
+
*/
|
|
2852
|
+
declare class WorkflowRejectedError extends Error {
|
|
2853
|
+
readonly reason?: string | undefined;
|
|
2854
|
+
readonly workflowId?: string | undefined;
|
|
2855
|
+
constructor(reason?: string | undefined, workflowId?: string | undefined);
|
|
2856
|
+
}
|
|
2857
|
+
//#endregion
|
|
2575
2858
|
//#region src/index.d.ts
|
|
2576
2859
|
/**
|
|
2577
2860
|
* Structural type for Cloudflare's `send_email` binding.
|
|
@@ -2822,10 +3105,6 @@ type Schedule<T = string> = {
|
|
|
2822
3105
|
intervalSeconds: number;
|
|
2823
3106
|
}
|
|
2824
3107
|
);
|
|
2825
|
-
type AgentPathStep = {
|
|
2826
|
-
className: string;
|
|
2827
|
-
name: string;
|
|
2828
|
-
};
|
|
2829
3108
|
type ScheduleStorageRow = {
|
|
2830
3109
|
id: string;
|
|
2831
3110
|
callback: string;
|
|
@@ -4476,19 +4755,13 @@ declare class Agent<
|
|
|
4476
4755
|
*
|
|
4477
4756
|
* @experimental The API surface may change before stabilizing.
|
|
4478
4757
|
*/
|
|
4479
|
-
get parentPath(): ReadonlyArray<
|
|
4480
|
-
className: string;
|
|
4481
|
-
name: string;
|
|
4482
|
-
}>;
|
|
4758
|
+
get parentPath(): ReadonlyArray<AgentPathStep>;
|
|
4483
4759
|
/**
|
|
4484
4760
|
* Ancestor chain + self, root-first. Convenient for logging.
|
|
4485
4761
|
*
|
|
4486
4762
|
* @experimental The API surface may change before stabilizing.
|
|
4487
4763
|
*/
|
|
4488
|
-
get selfPath(): ReadonlyArray<
|
|
4489
|
-
className: string;
|
|
4490
|
-
name: string;
|
|
4491
|
-
}>;
|
|
4764
|
+
get selfPath(): ReadonlyArray<AgentPathStep>;
|
|
4492
4765
|
/**
|
|
4493
4766
|
* Resolve a typed parent stub for this facet's **immediate** parent
|
|
4494
4767
|
* agent.
|
|
@@ -6024,124 +6297,154 @@ type AgentToolEventState<Part extends AgentToolRunPart = AgentToolRunPart> = {
|
|
|
6024
6297
|
//#endregion
|
|
6025
6298
|
export {
|
|
6026
6299
|
RoutingRetryOptions as $,
|
|
6027
|
-
|
|
6300
|
+
MCPOAuthCallbackResult as $t,
|
|
6028
6301
|
AgentGetOptions as A,
|
|
6029
|
-
|
|
6302
|
+
StreamableHTTPEdgeClientTransport as An,
|
|
6303
|
+
WorkflowCompleteCallback as At,
|
|
6030
6304
|
EmailSendBinding as B,
|
|
6031
|
-
|
|
6305
|
+
parseSubAgentPath as Bn,
|
|
6306
|
+
WorkflowTrackingRow as Bt,
|
|
6032
6307
|
DetachedRunAgentToolResult as C,
|
|
6033
|
-
|
|
6308
|
+
LegacyMcpHandler as Cn,
|
|
6309
|
+
ApprovalEventPayload as Ct,
|
|
6034
6310
|
AddRpcMcpServerOptions as D,
|
|
6035
|
-
|
|
6311
|
+
WorkerTransport as Dn,
|
|
6312
|
+
WorkflowCallback as Dt,
|
|
6036
6313
|
AddMcpServerOptions as E,
|
|
6037
|
-
|
|
6314
|
+
TransportState as En,
|
|
6315
|
+
WaitForApprovalOptions as Et,
|
|
6038
6316
|
Connection$1 as F,
|
|
6039
|
-
|
|
6317
|
+
buildAgentPath as Fn,
|
|
6318
|
+
WorkflowPage as Ft,
|
|
6040
6319
|
FiberStatus as G,
|
|
6041
|
-
|
|
6320
|
+
MCPClientElicitationHandler as Gt,
|
|
6042
6321
|
FiberInspection as H,
|
|
6043
|
-
|
|
6322
|
+
withInvocationScope as Hn,
|
|
6323
|
+
ElicitResult$2 as Ht,
|
|
6044
6324
|
ConnectionContext$1 as I,
|
|
6045
|
-
|
|
6325
|
+
buildAgentUrl as In,
|
|
6326
|
+
WorkflowProgressCallback as It,
|
|
6046
6327
|
MCPServerMessage as J,
|
|
6047
|
-
|
|
6328
|
+
MCPClientManagerOptions as Jt,
|
|
6048
6329
|
ListFibersOptions as K,
|
|
6049
|
-
|
|
6330
|
+
MCPClientElicitationHandlers as Kt,
|
|
6050
6331
|
DEFAULT_AGENT_STATIC_OPTIONS as L,
|
|
6051
|
-
|
|
6332
|
+
buildSubAgentPath as Ln,
|
|
6333
|
+
WorkflowQueryCriteria as Lt,
|
|
6052
6334
|
AgentOptions as M,
|
|
6053
|
-
|
|
6335
|
+
BuildAgentPathOptions as Mn,
|
|
6336
|
+
WorkflowEventCallback as Mt,
|
|
6054
6337
|
AgentStaticOptions as N,
|
|
6055
|
-
|
|
6338
|
+
SUB_PREFIX as Nn,
|
|
6339
|
+
WorkflowEventPayload as Nt,
|
|
6056
6340
|
Agent as O,
|
|
6057
|
-
|
|
6341
|
+
WorkerTransportOptions as On,
|
|
6342
|
+
WorkflowCallbackBase as Ot,
|
|
6058
6343
|
CallableMetadata as P,
|
|
6059
|
-
|
|
6344
|
+
SubAgentPathMatch as Pn,
|
|
6345
|
+
WorkflowInfo as Pt,
|
|
6060
6346
|
RPCResponse as Q,
|
|
6061
|
-
|
|
6347
|
+
MCPDiscoverResult as Qt,
|
|
6062
6348
|
DeleteFibersOptions as R,
|
|
6063
|
-
|
|
6349
|
+
buildSubAgentPathUnchecked as Rn,
|
|
6350
|
+
WorkflowRejectedError as Rt,
|
|
6064
6351
|
DetachedAgentToolConfig as S,
|
|
6065
|
-
|
|
6352
|
+
CreateMcpHandlerOptions$1 as Sn,
|
|
6353
|
+
AgentWorkflowStep as St,
|
|
6066
6354
|
RunAgentToolResult as T,
|
|
6067
|
-
|
|
6355
|
+
MCPStorageApi as Tn,
|
|
6356
|
+
RunWorkflowOptions as Tt,
|
|
6068
6357
|
FiberRecoveryContext as U,
|
|
6069
|
-
|
|
6358
|
+
MCPAITool as Ut,
|
|
6070
6359
|
FiberContext as V,
|
|
6071
|
-
|
|
6360
|
+
routeSubAgentRequest as Vn,
|
|
6361
|
+
ElicitRequest$1 as Vt,
|
|
6072
6362
|
FiberRecoveryResult as W,
|
|
6073
|
-
|
|
6363
|
+
MCPAIToolSet as Wt,
|
|
6074
6364
|
QueueItem as X,
|
|
6075
|
-
|
|
6365
|
+
MCPClientOAuthResult as Xt,
|
|
6076
6366
|
MCPServersState as Y,
|
|
6077
|
-
|
|
6367
|
+
MCPClientOAuthCallbackConfig as Yt,
|
|
6078
6368
|
RPCRequest as Z,
|
|
6079
|
-
|
|
6369
|
+
MCPConnectionResult as Zt,
|
|
6080
6370
|
AgentToolRunState as _,
|
|
6081
|
-
|
|
6371
|
+
ClearableEventStore as _n,
|
|
6372
|
+
AgentWorkflowEvent as _t,
|
|
6082
6373
|
AgentToolEvent as a,
|
|
6083
|
-
|
|
6374
|
+
normalizeServerId as an,
|
|
6084
6375
|
StartFiberResult as at,
|
|
6085
6376
|
AgentToolTerminalStatus as b,
|
|
6086
|
-
|
|
6377
|
+
experimental_createMcpHandler as bn,
|
|
6378
|
+
AgentWorkflowParams as bt,
|
|
6087
6379
|
AgentToolFailure as c,
|
|
6088
|
-
|
|
6380
|
+
RPCClientTransport as cn,
|
|
6089
6381
|
SubAgentClass as ct,
|
|
6090
6382
|
AgentToolMilestone as d,
|
|
6091
|
-
|
|
6383
|
+
RPCServerTransportOptions as dn,
|
|
6092
6384
|
callable as dt,
|
|
6093
|
-
|
|
6385
|
+
MCPServerFilter as en,
|
|
6094
6386
|
Schedule as et,
|
|
6095
6387
|
AgentToolProgress as f,
|
|
6096
|
-
|
|
6388
|
+
RPC_DO_PREFIX as fn,
|
|
6097
6389
|
getAgentByName as ft,
|
|
6098
6390
|
AgentToolRunPart as g,
|
|
6391
|
+
McpAgent as gn,
|
|
6099
6392
|
unstable_callable as gt,
|
|
6100
6393
|
AgentToolRunInspection as h,
|
|
6394
|
+
ElicitResult$3 as hn,
|
|
6101
6395
|
routeAgentRequest as ht,
|
|
6102
6396
|
AgentToolDisplayMetadata as i,
|
|
6103
|
-
|
|
6397
|
+
getNamespacedData as in,
|
|
6104
6398
|
StartFiberOptions as it,
|
|
6105
6399
|
AgentNamespace as j,
|
|
6106
|
-
|
|
6400
|
+
AgentPathStep as jn,
|
|
6401
|
+
WorkflowErrorCallback as jt,
|
|
6107
6402
|
AgentContext as k,
|
|
6108
|
-
|
|
6403
|
+
SSEEdgeClientTransport as kn,
|
|
6404
|
+
WorkflowCallbackType as kt,
|
|
6109
6405
|
AgentToolInterruptedReason as l,
|
|
6110
|
-
|
|
6406
|
+
RPCClientTransportOptions as ln,
|
|
6111
6407
|
SubAgentStub as lt,
|
|
6112
6408
|
AgentToolRunInfo as m,
|
|
6409
|
+
ElicitRequestSchema as mn,
|
|
6113
6410
|
routeAgentEmail as mt,
|
|
6114
6411
|
AGENT_TOOL_PROGRESS_PART as n,
|
|
6115
|
-
|
|
6412
|
+
MCP_SERVER_ID_MAX_LENGTH as nn,
|
|
6116
6413
|
SendEmailOptions as nt,
|
|
6117
6414
|
AgentToolEventMessage as o,
|
|
6118
|
-
|
|
6415
|
+
MCPElicitationHandler as on,
|
|
6119
6416
|
StateUpdateMessage as ot,
|
|
6120
6417
|
AgentToolProgressSnapshot as p,
|
|
6418
|
+
ElicitRequest$2 as pn,
|
|
6121
6419
|
getCurrentAgent as pt,
|
|
6122
6420
|
MCPServer as q,
|
|
6123
|
-
|
|
6421
|
+
MCPClientManager as qt,
|
|
6124
6422
|
AgentToolChildAdapter as r,
|
|
6125
|
-
|
|
6423
|
+
RegisterServerOptions as rn,
|
|
6126
6424
|
SqlError as rt,
|
|
6127
6425
|
AgentToolEventState as s,
|
|
6128
|
-
|
|
6426
|
+
MCPElicitationHandlers as sn,
|
|
6129
6427
|
StreamingResponse as st,
|
|
6130
6428
|
AGENT_TOOL_MILESTONE_PART as t,
|
|
6131
|
-
|
|
6429
|
+
MCPServerOptions as tn,
|
|
6132
6430
|
ScheduleCriteria as tt,
|
|
6133
6431
|
AgentToolLifecycleResult as u,
|
|
6134
|
-
|
|
6432
|
+
RPCServerTransport as un,
|
|
6135
6433
|
WSMessage$1 as ut,
|
|
6136
6434
|
AgentToolRunStatus as v,
|
|
6137
|
-
|
|
6435
|
+
DurableObjectEventStore as vn,
|
|
6436
|
+
AgentWorkflowInternalParams as vt,
|
|
6138
6437
|
RunAgentToolOptions as w,
|
|
6139
|
-
|
|
6438
|
+
createLegacyMcpHandler as wn,
|
|
6439
|
+
DefaultProgress as wt,
|
|
6140
6440
|
ChatCapableAgentClass as x,
|
|
6141
|
-
|
|
6441
|
+
CreateLegacyMcpHandlerOptions as xn,
|
|
6442
|
+
AgentWorkflowPathStep as xt,
|
|
6142
6443
|
AgentToolStoredChunk as y,
|
|
6143
|
-
|
|
6444
|
+
createMcpHandler$1 as yn,
|
|
6445
|
+
AgentWorkflowOrigin as yt,
|
|
6144
6446
|
EmailRoutingOptions as z,
|
|
6145
|
-
|
|
6447
|
+
getSubAgentByName as zn,
|
|
6448
|
+
WorkflowStatus as zt
|
|
6146
6449
|
};
|
|
6147
|
-
//# sourceMappingURL=agent-tool-types-
|
|
6450
|
+
//# sourceMappingURL=agent-tool-types-CzGGB-20.d.ts.map
|