NodesCore
AI Agent
Run an LLM-backed workflow step with ordered messages, a chat model, optional tools, and guardrails.
AI Agent
Description
AIAgent runs a model against each workflow item. It is the main built-in node for classification, extraction, summarization, routing, and tool-enabled agent flows.
Construct it with an options object: required name, messages, and chatModel; optional tools, outputSchema, guardrails, id, and retryPolicy. See the AI Agent workflow guide for message shapes, node-backed tools, and turn limits.
workflow().agent(...) uses the same messages model. In fluent workflow definitions, use itemExpr(...) when messages depend on the current item.
Examples
Basic usage: classify inbound mail into RFQ or other
const classifyMailOutputSchema = z.object({
outcome: z.enum(["rfq", "other"]),
summary: z.string(),
});
new AIAgent<{ subject: string; body: string }, z.output<typeof classifyMailOutputSchema>>({
name: "Classify RFQ vs other",
messages: [
{
role: "system",
content: "Classify the current mail.",
},
{
role: "user",
content: ({ item }) => JSON.stringify(item.json),
},
],
chatModel: new OpenAIChatModelConfig("OpenAI", "gpt-4o-mini"),
outputSchema: classifyMailOutputSchema,
});Example input:
{
"subject": "RFQ for 1000 widgets",
"body": "Please send pricing and lead times."
}Example output:
{
"outcome": "rfq",
"summary": "The sender is explicitly requesting a quote."
}Advanced usage: use tools before returning a structured answer
new AIAgent({
name: "Answer with product context",
messages: [
{
role: "system",
content: "Use the available tools when needed, then answer with a final structured result.",
},
{ role: "user", content: ({ item }) => JSON.stringify(item.json) },
],
chatModel: new OpenAIChatModelConfig("OpenAI", "gpt-4o-mini"),
tools: [new SearchDocsToolConfig(), new PricingLookupToolConfig()],
outputSchema: z.object({
answer: z.string(),
recommendedPlan: z.string(),
monthlyPrice: z.number(),
}),
});Example input:
{
"question": "Can the Pro plan process Gmail attachments, and what does it cost?"
}Example output:
{
"answer": "Yes. The Pro plan supports Gmail attachment processing.",
"recommendedPlan": "pro",
"monthlyPrice": 99
}Output behavior
- Without
outputSchema, the node keeps the legacy behavior: valid JSON is parsed when possible, otherwise plain text becomes{ output: "..." }. - With
outputSchema, the node must emit validated structured JSON or fail. - Tool-enabled agents still plan and execute tools normally, then finalize the last answer against the schema.
See also
- AI Agent workflow guide — full configuration, guardrails, and tools