agents/ai-agent

Enumerations#AIAgentToolChoice#Tool choice options for AI agents
Controls how the agent decides to use tools during execution
Enumeration Members#Enumeration Member
Value
Description
auto
"auto"
Let the model decide when to use tools
none
"none"
Disable tool usage
required
"required"
Force tool usage
router
"router"
Choose exactly one tool and route directly to it
Classes#AIAgent<I, O>#AI-powered agent that leverages language models
AIAgent connects to language models to process inputs and generate responses, with support for streaming, function calling, and tool usage.
Key features:
Connect to any language model
Use customizable instructions and prompts
Execute tools/function calls
Support streaming responses
Router mode for specialized agents
Example#Basic AIAgent creation:
const model = new OpenAIChatModel();

const agent = AIAgent.from({
  model,
  name: "assistant",
  description: "A helpful assistant",
  inputKey: "message",
});

const result = await agent.invoke({ message: "What is the weather today?" });

console.log(result); // Expected output: { message: "Hello, How can I help you?" }

Extends#`Agent`<I, O>
Type Parameters#Type Parameter
Default type
Description
I extends `Message`
any
The input message type the agent accepts
O extends `Message`
any
The output message type the agent returns
Indexable#[key: symbol]: () => string | () => Promise<void>
Constructors#Constructor#new AIAgent<I, O>(options): AIAgent<I, O>
Create an AIAgent instance
Parameters#Parameter
Type
Description
options
AIAgentOptions<I, O>
Configuration options for the AI agent
Returns#AIAgent<I, O>
Overrides#`Agent`.`constructor`
Properties#tag#tag: string = "AIAgent"
Overrides#`Agent`.`tag`
model?#optional model: ChatModel
The language model used by this agent
If not set on the agent, the model from the context will be used
instructions#instructions: PromptBuilder
Instructions for the language model
Contains system messages, user templates, and other prompt elements that guide the model's behavior
Example#Custom prompt builder:
const model = new OpenAIChatModel();

// Create a custom prompt template
const systemMessage = SystemMessageTemplate.from(
  "You are a technical support specialist.",
);
const userMessage = UserMessageTemplate.from(
  "Please help me troubleshoot this issue: {{issue}}",
);
const promptTemplate = ChatMessagesTemplate.from([systemMessage, userMessage]);

// Create a PromptBuilder with the template
const promptBuilder = new PromptBuilder({
  instructions: promptTemplate,
});

// Create an AIAgent with the custom PromptBuilder
const agent = AIAgent.from({
  model,
  name: "support",
  description: "Technical support specialist",
  instructions: promptBuilder,
});

const result = await agent.invoke({ issue: "My computer won't start." });

console.log(result); // Expected output: { message: "Is there any message on the screen?" }

inputKey?#optional inputKey: string
Pick a message from input to use as the user's message
outputKey#outputKey: string
Custom key to use for text output in the response
Example#Setting a custom output key:
const model = new OpenAIChatModel();

// Create an AIAgent with a custom output key
const agent = AIAgent.from({
  model,
  outputKey: "greeting",
  inputKey: "message",
});

const result = await agent.invoke({ message: "What is the weather today?" });

console.log(result); // Expected output: { greeting: "Hello, How can I help you?" }

toolChoice?#optional toolChoice: `Agent`<any, any> | AIAgentToolChoice
Controls how the agent uses tools during execution
Examples#Automatic tool choice:
const model = new OpenAIChatModel();

// Create function agents to serve as tools
const calculator = FunctionAgent.from({
  name: "calculator",
  inputSchema: z.object({
    a: z.number(),
    b: z.number(),
    operation: z.enum(["add", "subtract", "multiply", "divide"]),
  }),
  outputSchema: z.object({
    result: z.union([z.number(), z.string()]),
  }),
  process: ({
    a,
    b,
    operation,
  }: {
    a: number;
    b: number;
    operation: string;
  }) => {
    let result: number | string;
    switch (operation) {
      case "add":
        result = a + b;
        break;
      case "subtract":
        result = a - b;
        break;
      case "multiply":
        result = a * b;
        break;
      case "divide":
        result = a / b;
        break;
      default:
        result = "Unknown operation";
    }
    return { result };
  },
});

const weatherService = FunctionAgent.from({
  name: "weather",
  inputSchema: z.object({
    location: z.string(),
  }),
  outputSchema: z.object({
    forecast: z.string(),
  }),
  process: ({ location }: { location: string }) => {
    return {
      forecast: `Weather forecast for ${location}: Sunny, 75°F`,
    };
  },
});

// Create an AIAgent that can use tools automatically
const agent = AIAgent.from({
  model,
  name: "assistant",
  description: "A helpful assistant with tool access",
  toolChoice: AIAgentToolChoice.auto, // Let the model decide when to use tools
  skills: [calculator, weatherService],
  inputKey: "message",
});

const result1 = await agent.invoke({
  message: "What is the weather in San Francisco?",
});

console.log(result1); // Expected output: { message: "Weather forecast for San Francisco: Sunny, 75°F" }

const result2 = await agent.invoke({ message: "Calculate 5 + 3" });

console.log(result2); // Expected output: { message: "The result of 5 + 3 is 8" }

Router tool choice:
const model = new OpenAIChatModel();

// Create specialized function agents
const weatherAgent = FunctionAgent.from({
  name: "weather",
  inputSchema: z.object({
    location: z.string(),
  }),
  outputSchema: z.object({
    forecast: z.string(),
  }),
  process: ({ location }: { location: string }) => ({
    forecast: `Weather in ${location}: Sunny, 75°F`,
  }),
});

const translator = FunctionAgent.from({
  name: "translator",
  inputSchema: z.object({
    text: z.string(),
    language: z.string(),
  }),
  outputSchema: z.object({
    translation: z.string(),
  }),
  process: ({ text, language }: { text: string; language: string }) => ({
    translation: `Translated ${text} to ${language}`,
  }),
});

// Create an AIAgent with router tool choice
const agent = AIAgent.from({
  model,
  name: "router-assistant",
  description: "Assistant that routes to specialized agents",
  toolChoice: AIAgentToolChoice.router, // Use the router mode
  skills: [weatherAgent, translator],
  inputKey: "message",
});

const result = await agent.invoke({
  message: "What's the weather in San Francisco?",
});

console.log(result); // Expected output: { forecast: "Weather in San Francisco: Sunny, 75°F" }

memoryAgentsAsTools?#optional memoryAgentsAsTools: boolean
Whether to include memory agents as tools for the AI model
When set to true, memory agents will be made available as tools that the model can call directly to retrieve or store information. This enables the agent to explicitly interact with its memories.
memoryPromptTemplate?#optional memoryPromptTemplate: string
Custom prompt template for formatting memory content
Allows customization of how memories are presented to the AI model. If not provided, the default template from MEMORY_MESSAGE_TEMPLATE will be used.
The template receives a {{memories}} variable containing serialized memory content.
catchToolsError#catchToolsError: boolean = true
Whether to catch error from tool execution and continue processing. If set to false, the agent will throw an error if a tool fails
Default#true;

structuredStreamMode?#optional structuredStreamMode: boolean
Whether to enable structured stream mode
When enabled, the AI model's streaming response will be processed to extract structured metadata. The model needs to include specific format metadata tags (like) in its response, which will be parsed as JSON objects and passed through the stream.
This is useful for scenarios that need to extract structured information (like classifications, scores, tags, etc.) from AI responses.
Default#false;

customStructuredStreamInstructions?#optional customStructuredStreamInstructions: { instructions: PromptBuilder; metadataStart: string; metadataEnd: string; parse: (raw) => object; }
Custom structured stream instructions configuration
Allows customization of structured stream mode behavior, including:
instructions: Prompt instructions to guide the AI model on how to output structured data
metadataStart: Metadata start marker (e.g., "")
metadataEnd: Metadata end marker (e.g., "")
parse: Function to parse metadata content, converting raw string to object
If not provided, the default STRUCTURED_STREAM_INSTRUCTIONS configuration will be used, which outputs structured data in YAML format withintags.
Name
Type
instructions
PromptBuilder
metadataStart
string
metadataEnd
string
parse()
(raw) => object
Methods#from()#static from<I, O>(options): AIAgent<I, O>
Create an AIAgent with the specified options
Factory method that provides a convenient way to create new AI agents
Type Parameters#Type Parameter
I extends `Message`
O extends `Message`
Parameters#Parameter
Type
Description
options
AIAgentOptions<I, O>
Configuration options for the AI agent
Returns#AIAgent<I, O>
A new AIAgent instance
Example#AI agent with custom instructions:
const model = new OpenAIChatModel();

// Create an AIAgent with custom instructions
const agent = AIAgent.from({
  model,
  name: "tutor",
  description: "A math tutor",
  instructions:
    "You are a math tutor who helps students understand concepts clearly.",
  inputKey: "message",
});

const result = await agent.invoke({ message: "What is 10 factorial?" });

console.log(result); // Expected output: { message: "10 factorial is 3628800." }

process()#protected process(input, options): `AgentProcessAsyncGenerator`<O>
Process an input message and generate a response
Parameters#Parameter
Type
input
I
options
`AgentInvokeOptions`
Returns#`AgentProcessAsyncGenerator`<O>
Overrides#`Agent`.`process`
onGuideRailError()#protected onGuideRailError(error): Promise<`GuideRailAgentOutput` | O>
Handle errors detected by GuideRail agents
This method is called when a GuideRail agent aborts the process, providing a way for agents to customize error handling behavior. By default, it simply returns the original error, but subclasses can override this method to:
Transform the error into a more specific response
Apply recovery strategies
Log or report the error in a custom format
Return a fallback output instead of an error
Parameters#Parameter
Type
Description
error
`GuideRailAgentOutput`
The GuideRail agent output containing abort=true and a reason
Returns#Promise<`GuideRailAgentOutput` | O>
Either the original/modified error or a substitute output object which will be tagged with $status: "GuideRailError"
Overrides#`Agent`.`onGuideRailError`
_processRouter()#protected _processRouter(input, model, modelInput, options, toolsMap): `AgentProcessAsyncGenerator`<O>
Process router mode requests
In router mode, the agent sends a single request to the model to determine which tool to use, then routes the request directly to that tool
Parameters#Parameter
Type
input
I
model
ChatModel
modelInput
ChatModelInput
options
`AgentInvokeOptions`
toolsMap
Map<string, `Agent`<any, any>>
Returns#`AgentProcessAsyncGenerator`<O>
Interfaces#AIAgentOptions<I, O>#Configuration options for an AI Agent
These options extend the base agent options with AI-specific parameters like model configuration, prompt instructions, and tool choice.
Extends#`AgentOptions`<I, O>
Type Parameters#Type Parameter
Default type
Description
I extends `Message`
`Message`
The input message type the agent accepts
O extends `Message`
`Message`
The output message type the agent returns
Properties#Property
Type
Description
model?
ChatModel
The language model to use for this agent If not provided, the agent will use the model from the context
instructions?
string | PromptBuilder
Instructions to guide the AI model's behavior Can be a simple string or a full PromptBuilder instance for more complex prompt templates
inputKey?
string
Pick a message from input to use as the user's message
outputKey?
string
Custom key to use for text output in the response Defaults to message if not specified
toolChoice?
`Agent`<any, any> | AIAgentToolChoice
Controls how the agent uses tools during execution Default AIAgentToolChoice.auto
catchToolsError?
boolean
Whether to catch errors from tool execution and continue processing. If set to false, the agent will throw an error if a tool fails. Default true
structuredStreamMode?
boolean
Whether to enable structured stream mode When enabled, the AI model's streaming response will be processed to extract structured metadata. The model needs to include specific format metadata tags (like) in its response, which will be parsed as JSON objects and passed through the stream. This is useful for scenarios that need to extract structured information (like classifications, scores, tags, etc.) from AI responses. Default false
customStructuredStreamInstructions?
{ instructions: string | PromptBuilder; metadataStart: string; metadataEnd: string; parse: (raw) => object; }
Custom structured stream instructions configuration Allows customization of structured stream mode behavior, including: - instructions: Prompt instructions to guide the AI model on how to output structured data - metadataStart: Metadata start marker (e.g., "") - metadataEnd: Metadata end marker (e.g., "") - parse: Function to parse metadata content, converting raw string to object If not provided, the default STRUCTURED_STREAM_INSTRUCTIONS configuration will be used, which outputs structured data in YAML format withintags. Example { instructions: "Output metadata in JSON format at the end of response in markdown code block with json language", metadataStart: "json", metadataEnd: "parse: JSON.parse }
customStructuredStreamInstructions.instructions
string | PromptBuilder
-
customStructuredStreamInstructions.metadataStart
string
-
customStructuredStreamInstructions.metadataEnd
string
-
customStructuredStreamInstructions.parse
(raw) => object
-
memoryAgentsAsTools?
boolean
Whether to include memory agents as tools for the AI model When set to true, memory agents will be made available as tools that the model can call directly to retrieve or store information. This enables the agent to explicitly interact with its memories. Default false
memoryPromptTemplate?
string
Custom prompt template for formatting memory content Allows customization of how memories are presented to the AI model. If not provided, the default template from MEMORY_MESSAGE_TEMPLATE will be used. The template receives a {{memories}} variable containing serialized memory content.
Variables#DEFAULT_OUTPUT_KEY#const DEFAULT_OUTPUT_KEY: "message" = "message"

Enumeration Member	Value	Description
`auto`	`"auto"`	Let the model decide when to use tools
`none`	`"none"`	Disable tool usage
`required`	`"required"`	Force tool usage
`router`	`"router"`	Choose exactly one tool and route directly to it

Name	Type
`instructions`	`PromptBuilder`
`metadataStart`	`string`
`metadataEnd`	`string`
`parse()`	(`raw`) => `object`

Parameter	Type
`input`	`I`
`model`	`ChatModel`
`modelInput`	`ChatModelInput`
`options`	`AgentInvokeOptions`
`toolsMap`	`Map`<`string`, `Agent`<`any`, `any`>>

Property	Type	Description
`model?`	`ChatModel`	The language model to use for this agent If not provided, the agent will use the model from the context
`instructions?`	`string` \| `PromptBuilder`	Instructions to guide the AI model's behavior Can be a simple string or a full PromptBuilder instance for more complex prompt templates
`inputKey?`	`string`	Pick a message from input to use as the user's message
`outputKey?`	`string`	Custom key to use for text output in the response Defaults to `message` if not specified
`toolChoice?`	`Agent`<`any`, `any`> \| `AIAgentToolChoice`	Controls how the agent uses tools during execution Default `AIAgentToolChoice.auto`
`catchToolsError?`	`boolean`	Whether to catch errors from tool execution and continue processing. If set to false, the agent will throw an error if a tool fails. Default `true`
`structuredStreamMode?`	`boolean`	Whether to enable structured stream mode When enabled, the AI model's streaming response will be processed to extract structured metadata. The model needs to include specific format metadata tags (like) in its response, which will be parsed as JSON objects and passed through the stream. This is useful for scenarios that need to extract structured information (like classifications, scores, tags, etc.) from AI responses. Default `false`
`customStructuredStreamInstructions?`	{ `instructions`: `string` \| `PromptBuilder`; `metadataStart`: `string`; `metadataEnd`: `string`; `parse`: (`raw`) => `object`; }	Custom structured stream instructions configuration Allows customization of structured stream mode behavior, including: - instructions: Prompt instructions to guide the AI model on how to output structured data - metadataStart: Metadata start marker (e.g., "") - metadataEnd: Metadata end marker (e.g., "") - parse: Function to parse metadata content, converting raw string to object If not provided, the default STRUCTURED_STREAM_INSTRUCTIONS configuration will be used, which outputs structured data in YAML format withintags. Example `{ instructions: "Output metadata in JSON format at the end of response in markdown code block with json language", metadataStart: "`json", metadataEnd: "`parse: JSON.parse }`
`customStructuredStreamInstructions.instructions`	`string` \| `PromptBuilder`	-
`customStructuredStreamInstructions.metadataStart`	`string`	-
`customStructuredStreamInstructions.metadataEnd`	`string`	-
`customStructuredStreamInstructions.parse`	(`raw`) => `object`	-
`memoryAgentsAsTools?`	`boolean`	Whether to include memory agents as tools for the AI model When set to true, memory agents will be made available as tools that the model can call directly to retrieve or store information. This enables the agent to explicitly interact with its memories. Default `false`
`memoryPromptTemplate?`	`string`	Custom prompt template for formatting memory content Allows customization of how memories are presented to the AI model. If not provided, the default template from MEMORY_MESSAGE_TEMPLATE will be used. The template receives a {{memories}} variable containing serialized memory content.

Type Parameter	Default type	Description
`I` extends `Message`	`any`	The input message type the agent accepts
`O` extends `Message`	`any`	The output message type the agent returns

Type Parameter	Default type	Description
`I` extends `Message`	`Message`	The input message type the agent accepts
`O` extends `Message`	`Message`	The output message type the agent returns

Getting Started

AIGNE CLI

AIGNE Observability

How to guides

Concepts

API Reference

Contributing

agents/ai-agent

Enumerations#

AIAgentToolChoice#

Enumeration Members#

Classes#

AIAgent<I, O>#

Example#

Extends#

Type Parameters#

Indexable#

Constructors#

Constructor#

Parameters#

Returns#

Overrides#

Properties#

tag#

Overrides#

model?#

instructions#

Example#

inputKey?#

outputKey#

Example#

toolChoice?#

Examples#

memoryAgentsAsTools?#

memoryPromptTemplate?#

catchToolsError#

Default#

structuredStreamMode?#

Default#

customStructuredStreamInstructions?#

Methods#

from()#

Type Parameters#

Parameters#

Returns#

Example#

process()#

Parameters#

Returns#

Overrides#

onGuideRailError()#

Parameters#

Returns#

Overrides#

_processRouter()#

Parameters#

Returns#

Interfaces#

AIAgentOptions<I, O>#

Extends#

Type Parameters#

Properties#

Variables#

DEFAULT_OUTPUT_KEY#

agents/agent

agents/guide-rail-agent