0
# Agents and Agent Toolkits
1

2
Autonomous systems that use language models to determine which actions to take. Agents can interact with tools, maintain conversation state, and execute complex multi-step reasoning workflows.
3

4
## Capabilities
5

6
### Agent Executor
7

8
The main orchestrator that manages agent execution, tool calling, and iterative reasoning loops.
9

10
```typescript { .api }
11
/**
12
 * Executes agent actions with tools and manages the reasoning loop
13
 */
14
class AgentExecutor extends BaseChain {
15
  constructor(input: AgentExecutorInput);
16
  
17
  /** Execute the agent with input and return final output */
18
  invoke(input: { input: string }): Promise<{ output: string }>;
19
  
20
  /** Stream agent execution for real-time updates */
21
  stream(input: { input: string }): AsyncGenerator<any>;
22
  
23
  /** Call the agent (legacy interface) */
24
  call(values: ChainValues): Promise<ChainValues>;
25
}
26

27
interface AgentExecutorInput extends ChainInputs {
28
  /** The agent to execute */
29
  agent: BaseAgent | RunnableAgent;
30
  /** Tools available to the agent */
31
  tools: StructuredToolInterface[];
32
  /** Maximum number of iterations before stopping */
33
  maxIterations?: number;
34
  /** Maximum execution time in milliseconds */
35
  maxExecutionTime?: number;
36
  /** Method for early stopping ('force' | 'generate') */
37
  earlyStoppingMethod?: string;
38
  /** Whether the agent can handle parsing errors */
39
  handleParsingErrors?: boolean | string | ((error: Error) => string);
40
}
41
```
42

43
**Usage Example:**
44

45
```typescript
46
import { AgentExecutor, createReactAgent } from "langchain/agents";
47
import { OpenAI } from "@langchain/openai";
48
import { DynamicTool } from "langchain/tools";
49

50
const model = new OpenAI({ temperature: 0 });
51
const tools = [
52
  new DynamicTool({
53
    name: "calculator",
54
    description: "Calculate math expressions",
55
    func: async (input: string) => eval(input).toString(),
56
  }),
57
];
58

59
const agent = await createReactAgent({ 
60
  llm: model, 
61
  tools, 
62
  prompt: reactPrompt 
63
});
64

65
const executor = new AgentExecutor({ 
66
  agent, 
67
  tools,
68
  maxIterations: 10,
69
  verbose: true 
70
});
71

72
const result = await executor.invoke({ 
73
  input: "What is 25 * 4 + 10?" 
74
});
75
```
76

77
### Agent Creation Functions
78

79
Factory functions for creating different types of agents with specific capabilities and reasoning patterns.
80

81
```typescript { .api }
82
/**
83
 * Create a ReAct (Reasoning and Acting) agent
84
 */
85
function createReactAgent(params: {
86
  llm: BaseLanguageModelInterface;
87
  tools: StructuredToolInterface[];
88
  prompt: BasePromptTemplate;
89
  streamRunnable?: boolean;
90
}): Promise<RunnableAgent>;
91

92
/**
93
 * Create an agent that uses OpenAI function calling
94
 */
95
function createOpenAIFunctionsAgent(params: {
96
  llm: BaseLanguageModelInterface;
97
  tools: StructuredToolInterface[];
98
  prompt: BasePromptTemplate;
99
  streamRunnable?: boolean;
100
}): Promise<RunnableAgent>;
101

102
/**
103
 * Create an agent that uses OpenAI tools format
104
 */
105
function createOpenAIToolsAgent(params: {
106
  llm: BaseLanguageModelInterface;
107
  tools: StructuredToolInterface[];
108
  prompt: BasePromptTemplate;
109
  streamRunnable?: boolean;
110
}): Promise<RunnableAgent>;
111

112
/**
113
 * Create a tool-calling agent (generic)
114
 */
115
function createToolCallingAgent(params: {
116
  llm: BaseLanguageModelInterface;
117
  tools: StructuredToolInterface[];
118
  prompt: BasePromptTemplate;
119
  streamRunnable?: boolean;
120
}): Promise<RunnableAgent>;
121

122
/**
123
 * Create an XML-based agent
124
 */
125
function createXmlAgent(params: {
126
  llm: BaseLanguageModelInterface;
127
  tools: StructuredToolInterface[];
128
  prompt: BasePromptTemplate;
129
}): Promise<RunnableAgent>;
130

131
/**
132
 * Create a structured chat agent
133
 */
134
function createStructuredChatAgent(params: {
135
  llm: BaseLanguageModelInterface;
136
  tools: StructuredToolInterface[];
137
  prompt: BasePromptTemplate;
138
}): Promise<RunnableAgent>;
139
```
140

141
**Usage Example:**
142

143
```typescript
144
import { createOpenAIFunctionsAgent, AgentExecutor } from "langchain/agents";
145
import { ChatOpenAI } from "@langchain/openai";
146
import { DynamicStructuredTool } from "langchain/tools";
147
import { z } from "zod";
148

149
const llm = new ChatOpenAI({ temperature: 0 });
150

151
const tools = [
152
  new DynamicStructuredTool({
153
    name: "get_weather",
154
    description: "Get weather information for a city",
155
    schema: z.object({
156
      city: z.string().describe("City name"),
157
      units: z.enum(["celsius", "fahrenheit"]).optional()
158
    }),
159
    func: async ({ city, units = "celsius" }) => {
160
      return `Weather in ${city}: 22°${units === "celsius" ? "C" : "F"}`;
161
    },
162
  }),
163
];
164

165
const agent = await createOpenAIFunctionsAgent({
166
  llm,
167
  tools,
168
  prompt: functionsPrompt
169
});
170

171
const executor = new AgentExecutor({ agent, tools });
172
```
173

174
### Agent Implementations
175

176
Pre-built agent classes for different use cases and reasoning patterns.
177

178
```typescript { .api }
179
/**
180
 * Base agent class
181
 */
182
abstract class BaseAgent {
183
  abstract plan(
184
    steps: AgentStep[],
185
    inputs: ChainValues,
186
    runManager?: CallbackManagerForChainRun
187
  ): Promise<AgentAction | AgentFinish>;
188
}
189

190
/**
191
 * Single action agent base class
192
 */
193
abstract class BaseSingleActionAgent extends BaseAgent {
194
  abstract plan(
195
    steps: AgentStep[],
196
    inputs: ChainValues,
197
    runManager?: CallbackManagerForChainRun
198
  ): Promise<AgentAction | AgentFinish>;
199
}
200

201
/**
202
 * Multi action agent base class
203
 */
204
abstract class BaseMultiActionAgent extends BaseAgent {
205
  abstract plan(
206
    steps: AgentStep[],
207
    inputs: ChainValues,
208
    runManager?: CallbackManagerForChainRun
209
  ): Promise<AgentAction[] | AgentFinish>;
210
}
211

212
/**
213
 * Runnable agent implementation
214
 */
215
class RunnableAgent extends BaseSingleActionAgent implements RunnableInterface<AgentStep[], AgentAction | AgentFinish> {
216
  constructor(fields: RunnableAgentInput);
217
  
218
  invoke(
219
    input: AgentStep[],
220
    options?: Partial<RunnableConfig>
221
  ): Promise<AgentAction | AgentFinish>;
222
  
223
  stream(
224
    input: AgentStep[],
225
    options?: Partial<RunnableConfig>
226
  ): AsyncGenerator<AgentAction | AgentFinish>;
227
}
228

229
/**
230
 * LLM-powered single action agent
231
 */
232
class LLMSingleActionAgent extends BaseSingleActionAgent {
233
  constructor(fields: LLMSingleActionAgentInput);
234
}
235

236
/**
237
 * Chat-based agent
238
 */
239
class ChatAgent extends Agent {
240
  static createPrompt(
241
    tools: StructuredToolInterface[],
242
    args?: ChatCreatePromptArgs
243
  ): BasePromptTemplate;
244
  
245
  static fromLLMAndTools(
246
    llm: BaseLanguageModelInterface,
247
    tools: StructuredToolInterface[],
248
    args?: ChatAgentInput
249
  ): ChatAgent;
250
}
251

252
/**
253
 * Conversational chat agent with memory
254
 */
255
class ChatConversationalAgent extends Agent {
256
  static createPrompt(
257
    tools: StructuredToolInterface[],
258
    args?: ChatConversationalCreatePromptArgs
259
  ): BasePromptTemplate;
260
  
261
  static fromLLMAndTools(
262
    llm: BaseLanguageModelInterface,
263
    tools: StructuredToolInterface[],
264
    args?: ChatConversationalAgentInput
265
  ): ChatConversationalAgent;
266
}
267

268
/**
269
 * Zero-shot reasoning agent (MRKL)
270
 */
271
class ZeroShotAgent extends Agent {
272
  static createPrompt(
273
    tools: StructuredToolInterface[],
274
    args?: ZeroShotCreatePromptArgs
275
  ): BasePromptTemplate;
276
  
277
  static fromLLMAndTools(
278
    llm: BaseLanguageModelInterface,
279
    tools: StructuredToolInterface[],
280
    args?: ZeroShotAgentInput
281
  ): ZeroShotAgent;
282
}
283

284
/**
285
 * Structured chat agent for complex tool interactions
286
 */
287
class StructuredChatAgent extends Agent {
288
  static createPrompt(
289
    tools: StructuredToolInterface[],
290
    args?: StructuredChatCreatePromptArgs
291
  ): BasePromptTemplate;
292
  
293
  static fromLLMAndTools(
294
    llm: BaseLanguageModelInterface,
295
    tools: StructuredToolInterface[],
296
    args?: StructuredChatAgentInput
297
  ): StructuredChatAgent;
298
}
299

300
/**
301
 * XML-based agent for XML-formatted interactions
302
 */
303
class XMLAgent extends Agent {
304
  static createPrompt(
305
    tools: StructuredToolInterface[],
306
    args?: XMLCreatePromptArgs
307
  ): BasePromptTemplate;
308
  
309
  static fromLLMAndTools(
310
    llm: BaseLanguageModelInterface,
311
    tools: StructuredToolInterface[],
312
    args?: XMLAgentInput
313
  ): XMLAgent;
314
}
315

316
/**
317
 * OpenAI function-calling agent
318
 */
319
class OpenAIAgent extends Agent {
320
  static fromLLMAndTools(
321
    llm: BaseLanguageModelInterface,
322
    tools: StructuredToolInterface[],
323
    args?: OpenAIAgentInput
324
  ): OpenAIAgent;
325
}
326
```
327

328
### Agent Toolkits
329

330
Specialized collections of tools for specific domains and use cases.
331

332
```typescript { .api }
333
/**
334
 * Base toolkit class
335
 */
336
abstract class Toolkit {
337
  abstract tools: StructuredToolInterface[];
338
}
339

340
/**
341
 * JSON manipulation toolkit
342
 */
343
class JsonToolkit extends Toolkit {
344
  constructor(jsonSpec: JsonSpec);
345
  tools: StructuredToolInterface[];
346
}
347

348
/**
349
 * OpenAPI toolkit for REST API interactions
350
 */
351
class OpenApiToolkit extends Toolkit {
352
  constructor(jsonSpec: OpenAPISpec, llm: BaseLanguageModelInterface, headers?: Record<string, string>);
353
  tools: StructuredToolInterface[];
354
}
355

356
/**
357
 * HTTP requests toolkit
358
 */
359
class RequestsToolkit extends Toolkit {
360
  constructor(headers?: Record<string, string>);
361
  tools: StructuredToolInterface[];
362
}
363

364
/**
365
 * Vector store operations toolkit
366
 */
367
class VectorStoreToolkit extends Toolkit {
368
  constructor(
369
    vectorStoreInfo: VectorStoreInfo,
370
    llm: BaseLanguageModelInterface
371
  );
372
  tools: StructuredToolInterface[];
373
}
374

375
/**
376
 * SQL database toolkit
377
 */
378
class SqlToolkit extends Toolkit {
379
  constructor(db: SqlDatabase, llm: BaseLanguageModelInterface);
380
  tools: StructuredToolInterface[];
381
}
382
```
383

384
**Usage Example:**
385

386
```typescript
387
import { JsonToolkit, createJsonAgent, AgentExecutor } from "langchain/agents";
388
import { OpenAI } from "@langchain/openai";
389

390
const jsonSpec = {
391
  type: "object",
392
  properties: {
393
    users: {
394
      type: "array",
395
      items: {
396
        type: "object",
397
        properties: {
398
          name: { type: "string" },
399
          age: { type: "number" }
400
        }
401
      }
402
    }
403
  }
404
};
405

406
const toolkit = new JsonToolkit(jsonSpec);
407
const model = new OpenAI({ temperature: 0 });
408

409
const executor = await createJsonAgent(model, toolkit);
410
const result = await executor.call({
411
  input: "Find all users older than 25"
412
});
413
```
414

415
### Specialized Agent Creation
416

417
Factory functions for creating agents with specific toolkits and capabilities.
418

419
```typescript { .api }
420
/**
421
 * Create a JSON toolkit agent
422
 */
423
function createJsonAgent(
424
  llm: BaseLanguageModelInterface,
425
  toolkit: JsonToolkit,
426
  args?: CreateJsonAgentInput
427
): Promise<AgentExecutor>;
428

429
/**
430
 * Create an OpenAPI toolkit agent
431
 */
432
function createOpenApiAgent(
433
  llm: BaseLanguageModelInterface,
434
  toolkit: OpenApiToolkit,
435
  args?: CreateOpenApiAgentInput
436
): Promise<AgentExecutor>;
437

438
/**
439
 * Create a vector store agent
440
 */
441
function createVectorStoreAgent(
442
  llm: BaseLanguageModelInterface,
443
  toolkit: VectorStoreToolkit,
444
  args?: CreateVectorStoreAgentInput
445
): Promise<AgentExecutor>;
446

447
/**
448
 * Create a vector store router agent
449
 */
450
function createVectorStoreRouterAgent(
451
  llm: BaseLanguageModelInterface,
452
  toolkit: VectorStoreRouterToolkit,
453
  args?: CreateVectorStoreRouterAgentInput
454
): Promise<AgentExecutor>;
455
```
456

457
### Output Parsers
458

459
Specialized parsers for extracting structured information from agent outputs.
460

461
```typescript { .api }
462
/**
463
 * Base output parser for agent actions
464
 */
465
abstract class AgentActionOutputParser extends BaseOutputParser<AgentAction | AgentFinish> {
466
  abstract parse(text: string): Promise<AgentAction | AgentFinish>;
467
}
468

469
/**
470
 * Chat agent output parser
471
 */
472
class ChatAgentOutputParser extends AgentActionOutputParser {
473
  constructor(toolNames: string[]);
474
  parse(text: string): Promise<AgentAction | AgentFinish>;
475
}
476

477
/**
478
 * Zero-shot agent output parser
479
 */
480
class ZeroShotAgentOutputParser extends AgentActionOutputParser {
481
  constructor(toolNames: string[]);
482
  parse(text: string): Promise<AgentAction | AgentFinish>;
483
}
484

485
/**
486
 * Structured chat output parser
487
 */
488
class StructuredChatOutputParser extends AgentActionOutputParser {
489
  constructor(toolNames: string[]);
490
  parse(text: string): Promise<AgentAction | AgentFinish>;
491
}
492
```
493

494
### Scratchpad Formatting
495

496
Utilities for formatting agent reasoning traces and intermediate steps.
497

498
```typescript { .api }
499
/**
500
 * Format scratchpad for OpenAI tools
501
 */
502
function formatToOpenAIToolMessages(
503
  steps: AgentStep[]
504
): BaseMessageInterface[];
505

506
/**
507
 * Format log entries to messages
508
 */
509
function formatLogToMessages(
510
  steps: AgentStep[],
511
  templateToolResponse?: string
512
): BaseMessageInterface[];
513

514
/**
515
 * Format scratchpad content to XML
516
 */
517
function formatToXML(steps: AgentStep[]): string;
518

519
/**
520
 * Format agent log to message format
521
 */
522
function formatLogToMessage(
523
  steps: AgentStep[],
524
  templateToolResponse?: string
525
): BaseMessageInterface;
526
```
527

528
### Initialization Functions
529

530
Helper functions for setting up agent executors with various configurations.
531

532
```typescript { .api }
533
/**
534
 * Initialize agent executor
535
 */
536
function initializeAgentExecutor(
537
  tools: StructuredToolInterface[],
538
  llm: BaseLanguageModelInterface,
539
  agentType?: AgentType,
540
  verbose?: boolean,
541
  callbackManager?: BaseCallbackManager
542
): Promise<AgentExecutor>;
543

544
/**
545
 * Initialize agent executor with options
546
 */
547
function initializeAgentExecutorWithOptions(
548
  tools: StructuredToolInterface[],
549
  llm: BaseLanguageModelInterface,
550
  options?: InitializeAgentExecutorOptions
551
): Promise<AgentExecutor>;
552
```
553

554
## Types
555

556
### Agent Types
557

558
```typescript { .api }
559
interface RunnableAgentInput {
560
  runnable: RunnableInterface<AgentStep[], AgentAction | AgentFinish>;
561
  defaultRunName?: string;
562
  streamRunnable?: boolean;
563
}
564

565
interface LLMSingleActionAgentInput {
566
  llmChain: LLMChain;
567
  outputParser: AgentActionOutputParser;
568
  stop?: string[];
569
}
570

571
interface ChatAgentInput extends AgentInput {
572
  humanMessage?: string;
573
  systemMessage?: string;
574
  outputParser?: AgentActionOutputParser;
575
}
576

577
interface ChatConversationalAgentInput extends AgentInput {
578
  outputParser?: AgentActionOutputParser;
579
}
580

581
interface ZeroShotAgentInput extends AgentInput {
582
  outputParser?: AgentActionOutputParser;
583
}
584

585
interface StructuredChatAgentInput extends AgentInput {
586
  outputParser?: AgentActionOutputParser;
587
  inputVariables?: string[];
588
}
589

590
interface XMLAgentInput extends AgentInput {
591
  outputParser?: AgentActionOutputParser;
592
}
593

594
interface OpenAIAgentInput extends AgentInput {
595
  outputParser?: AgentMultiActionOutputParser;
596
}
597
```
598

599
### Toolkit Types
600

601
```typescript { .api }
602
interface JsonSpec {
603
  type: string;
604
  properties?: Record<string, any>;
605
  items?: any;
606
  required?: string[];
607
}
608

609
interface OpenAPISpec {
610
  openapi: string;
611
  info: any;
612
  paths: Record<string, any>;
613
  components?: any;
614
}
615

616
interface VectorStoreInfo {
617
  vectorStore: VectorStore;
618
  name: string;
619
  description: string;
620
}
621

622
interface CreateJsonAgentInput {
623
  prefix?: string;
624
  suffix?: string;
625
  inputVariables?: string[];
626
  maxIterations?: number;
627
}
628

629
interface CreateOpenApiAgentInput {
630
  maxIterations?: number;
631
  earlyStoppingMethod?: string;
632
  verbose?: boolean;
633
}
634
```
635

636
### Agent Action Types
637

638
```typescript { .api }
639
interface AgentAction {
640
  tool: string;
641
  toolInput: any;
642
  log: string;
643
  messageLog?: BaseMessageInterface[];
644
}
645

646
interface AgentFinish {
647
  returnValues: Record<string, any>;
648
  log: string;
649
  messageLog?: BaseMessageInterface[];
650
}
651

652
interface AgentStep {
653
  action: AgentAction;
654
  observation: string;
655
}
656
```