Patterns for Defining Tools
Common patterns for defining tools in durable AI agents using Workflow SDK.
This page covers the details for some common patterns when defining tools for AI agents using Workflow SDK.
Using WorkflowAgent, we model most tools as steps. These can range from a single function call to an entire multi-day workflow.
Accessing message context in tools
As with regular AI SDK tool definitions, tools in WorkflowAgent receive the tool's input parameters as the first argument and the tool call context as the second.
When you tool needs access to the full message history, you can access it via the messages property of the tool call context:
import { Experimental_Agent as Agent } from "ai";
import type { ModelMessage } from "ai";
async function getWeather(
{ city }: { city: string },
{ messages, toolCallId }: { messages: ModelMessage[], toolCallId: string }) {
"use step";
return `Weather in ${city} is sunny`;
}Writing to streams
As discussed in Streaming Updates from Tools, it's common to use a step only to call getWritable() for writing custom data parts to the stream.
This can be made generic, by creating a helper step function to write arbitrary data to the stream:
import { getWritable } from "workflow";
async function writeToStream(data: any) {
"use step";
const writable = getWritable();
const writer = writable.getWriter();
await writer.write(data);
writer.releaseLock();
}Step-level vs workflow-level tools
Tools can be implemented either at the step level or the workflow level, with different capabilities and constraints.
| Capability | Step-Level ("use step") | Workflow-Level ("use workflow") |
|---|---|---|
getWritable() | ✅ | ❌ |
| Automatic retries | ✅ | ❌ |
| Side-effects (e.g. API calls) allowed | ✅ | ❌ |
sleep() | ❌ | ✅ |
createWebhook() | ❌ | ✅ |
Tools can also combine both by starting out on the workflow level, and calling into steps for I/O operations, like so:
import { sleep } from "workflow";
import type { LanguageModel, ModelMessage } from "ai";
// Step: handles I/O with retries
async function performFetch(url: string) {
"use step";
const response = await fetch(url);
return response.json();
}
// Workflow-level: orchestrates steps and can use sleep()
async function executeFetchWithDelay({ url }: { url: string }) {
const result = await performFetch(url);
await sleep("5s"); // Only available at workflow level
return result;
}