Advanced Agent Types

Specialized agent architectures for different reasoning patterns: ReAct for step-by-step reasoning, Plan-and-Execute for complex multi-step tasks, OpenAI Functions for structured tool calling, and Structured Chat for JSON-based interactions. Plus pre-built toolkits for SQL and CSV data analysis.

🧠

ReAct Agent

Reasoning + Acting: thinks step-by-step, uses tools, observes results

📋

Plan-and-Execute

Plans first, then executes each step. Replans on failure.

⚡

OpenAI Functions

Uses OpenAI function calling format for precise tool invocation

💬

Structured Chat

JSON-based tool calling with optional output schema validation

# ReAct Agent — Reasoning + Acting

The ReAct agent follows the Thought → Action → Observation loop. At each step, it reasons about what to do, takes an action (calls a tool), observes the result, and repeats until it can provide a final answer. This is the most general-purpose agent pattern and works well for most tasks.

import { ReActAgent } from 'orkajs/agent/react';
import { OpenAIAdapter } from 'orkajs/adapters/openai';
import type { Tool } from 'orkajs';
 
const llm = new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! });
 
// Define tools
const searchTool: Tool = {
  name: 'web_search',
  description: 'Search the web for current information',
  parameters: [
    { name: 'query', type: 'string', description: 'Search query', required: true }
  ],
  execute: async (input) => {
    const results = await mySearchAPI(input.query as string);
    return { output: results };
  }
};
 
const calculatorTool: Tool = {
  name: 'calculator',
  description: 'Perform mathematical calculations',
  parameters: [
    { name: 'expression', type: 'string', description: 'Math expression to evaluate', required: true }
  ],
  execute: async (input) => {
    const result = eval(input.expression as string); // Use a safe math parser in production
    return { output: String(result) };
  }
};
 
// Create ReAct agent
const agent = new ReActAgent(
  {
    goal: 'Help users find information and perform calculations',
    tools: [searchTool, calculatorTool],
    maxSteps: 10,
    verbose: true,  // Logs each Thought/Action/Observation
    policy: {
      rules: [
        'Always verify information from multiple sources',
        'Show your calculations step by step'
      ]
    }
  },
  llm
);
 
const result = await agent.run('What is the population of France times 2?');
 
console.log(result.output);
// "The population of France is approximately 68 million. 68,000,000 × 2 = 136,000,000."
 
console.log(result.steps);
// [
//   { thought: "I need to find the population of France", action: "web_search", ... },
//   { thought: "Now I need to multiply by 2", action: "calculator", ... }
// ]

🔄 ReAct Loop

Thought: "I need to find the population of France first"
Action: web_search({query: "population of France 2024"})
Observation: "France has approximately 68 million inhabitants"
Thought: "Now I need to multiply 68,000,000 by 2"
Action: calculator({expression: "68000000 * 2"})
Observation: "136000000"
Action: finish({answer: "136,000,000"})

# Plan-and-Execute Agent

The Plan-and-Execute agent separates planning from execution. First, it creates a complete plan of steps. Then, it executes each step one by one. If a step fails and replanOnFailure is enabled, it dynamically adjusts the remaining plan. This architecture is ideal for complex, multi-step tasks where having a clear roadmap improves reliability.

import { PlanAndExecuteAgent } from 'orkajs/agent/plan-and-execute';
 
const agent = new PlanAndExecuteAgent(
  {
    goal: 'Research and analyze data to answer complex questions',
    tools: [searchTool, calculatorTool, databaseTool],
    maxSteps: 15,
    replanOnFailure: true,  // Dynamically adjust plan if a step fails
  },
  llm
);
 
const result = await agent.run(
  'Compare the GDP per capita of France, Germany, and Japan. Which has grown the most in the last 5 years?'
);
 
console.log(result.output);
// Comprehensive comparison with data and analysis
 
console.log(result.plan);
// [
//   { id: 1, description: "Search for France GDP per capita data", status: "completed", result: "..." },
//   { id: 2, description: "Search for Germany GDP per capita data", status: "completed", result: "..." },
//   { id: 3, description: "Search for Japan GDP per capita data", status: "completed", result: "..." },
//   { id: 4, description: "Calculate growth rates for each country", status: "completed", result: "..." },
//   { id: 5, description: "Compare and determine highest growth", status: "completed", result: "..." }
// ]
 
console.log(result.steps);
// Detailed execution trace with timing and token usage per step

✅ When to Use Plan-and-Execute

Complex tasks requiring multiple steps
Research and analysis workflows
Tasks where order of operations matters
When you need a visible execution plan

❌ When NOT to Use

Simple single-step queries
Real-time conversational agents
Tasks where the path is unpredictable

# OpenAI Functions Agent

Uses the OpenAI function calling format for precise, structured tool invocation. Tools are described as JSON schemas, and the LLM responds with structured function calls instead of free-text parsing. This results in more reliable tool usage with fewer parsing errors.

import { OpenAIFunctionsAgent } from 'orkajs/agent/openai-functions';
 
const agent = new OpenAIFunctionsAgent(
  {
    goal: 'Help users manage their tasks and calendar',
    tools: [
      {
        name: 'create_event',
        description: 'Create a calendar event',
        parameters: [
          { name: 'title', type: 'string', description: 'Event title', required: true },
          { name: 'date', type: 'string', description: 'Event date (YYYY-MM-DD)', required: true },
          { name: 'time', type: 'string', description: 'Event time (HH:MM)', required: false },
        ],
        execute: async (input) => {
          await calendarAPI.create(input);
          return { output: `Event "${input.title}" created for ${input.date}` };
        }
      },
      {
        name: 'list_events',
        description: 'List calendar events for a date range',
        parameters: [
          { name: 'start_date', type: 'string', description: 'Start date', required: true },
          { name: 'end_date', type: 'string', description: 'End date', required: true },
        ],
        execute: async (input) => {
          const events = await calendarAPI.list(input.start_date, input.end_date);
          return { output: JSON.stringify(events) };
        }
      }
    ],
    // Optional: provide custom function definitions (auto-generated from tools if omitted)
    // functions: [{ name: 'create_event', description: '...', parameters: { ... } }],
    maxSteps: 5,
  },
  llm
);
 
const result = await agent.run('Schedule a team meeting for next Monday at 2pm');
 
console.log(result.output);
// "I've created a 'Team Meeting' event for 2024-03-18 at 14:00."
 
console.log(result.metadata);
// { agentType: 'openai-functions', stepsUsed: 1 }

🔧 Auto-generated Function Schemas

If you don't provide custom function definitions, the agent automatically converts your Tool definitions into OpenAI-compatible function schemas:

// Your Tool definition:
{ name: 'create_event', parameters: [{ name: 'title', type: 'string', required: true }] }
 
// Auto-generated OpenAI function schema:
{
  "name": "create_event",
  "parameters": {
    "type": "object",
    "properties": { "title": { "type": "string" } },
    "required": ["title"]
  }
}

# Structured Chat Agent

The Structured Chat agent communicates entirely through JSON. Every response — whether a tool call or a final answer — is a structured JSON object. This makes it highly predictable and easy to integrate into systems that require structured outputs. You can optionally define an output schema to enforce the format of the final answer.

import { StructuredChatAgent } from 'orkajs/agent/structured-chat';
 
const agent = new StructuredChatAgent(
  {
    goal: 'Analyze customer support tickets and route them',
    tools: [
      {
        name: 'classify_ticket',
        description: 'Classify a support ticket by category and urgency',
        parameters: [
          { name: 'text', type: 'string', description: 'Ticket text', required: true }
        ],
        execute: async (input) => {
          // Classification logic
          return { output: JSON.stringify({ category: 'billing', urgency: 'high' }) };
        }
      },
      {
        name: 'route_ticket',
        description: 'Route a ticket to the appropriate team',
        parameters: [
          { name: 'category', type: 'string', description: 'Ticket category', required: true },
          { name: 'urgency', type: 'string', description: 'Urgency level', required: true }
        ],
        execute: async (input) => {
          return { output: `Routed to ${input.category} team (priority: ${input.urgency})` };
        }
      }
    ],
    // Optional: enforce output format
    outputSchema: {
      type: 'object',
      properties: {
        category: { type: 'string' },
        urgency: { type: 'string' },
        team: { type: 'string' },
        summary: { type: 'string' }
      }
    },
    maxSteps: 5,
  },
  llm
);
 
const result = await agent.run('Customer says: "I was charged twice for my subscription!"');
 
console.log(result.output);
// "Classified as billing/high urgency. Routed to billing team with priority handling."
 
console.log(result.steps);
// All steps are structured JSON — easy to log and audit

# Agent Toolkits

Toolkits are pre-built collections of tools for common data analysis tasks. Instead of defining tools manually, use a toolkit to instantly equip any agent with domain-specific capabilities.

- SQL Toolkit

Provides tools for querying SQL databases: execute queries, inspect schema, and list tables. Supports read-only mode for safety and automatic LIMIT injection.

import { SQLToolkit } from 'orkajs/agent/toolkits/sql';
import { ReActAgent } from 'orkajs/agent/react';
 
const sqlToolkit = new SQLToolkit({
  execute: async (query: string) => {
    // Connect to your database
    const result = await db.query(query);
    return JSON.stringify(result.rows);
  },
  schema: `
    CREATE TABLE users(id INT, name VARCHAR, email VARCHAR, created_at TIMESTAMP);
    CREATE TABLE orders(id INT, user_id INT, amount DECIMAL, status VARCHAR, created_at TIMESTAMP);
    CREATE TABLE products(id INT, name VARCHAR, price DECIMAL, category VARCHAR);
  `,
  readOnly: true,   // Only SELECT queries allowed
  maxRows: 50       // Auto-inject LIMIT 50
});
 
// Use with any agent type
const agent = new ReActAgent(
  {
    goal: 'Answer questions about the database by writing SQL queries',
    tools: sqlToolkit.tools,  // Includes: sql_query, sql_schema, sql_list_tables
    maxSteps: 8,
  },
  llm
);
 
const result = await agent.run('How many orders were placed last month? What was the total revenue?');
 
// The agent will:
// 1. Use sql_schema to understand the tables
// 2. Write and execute SQL queries
// 3. Synthesize the results into a natural language answer

🛡️ SQL Toolkit Safety Features

readOnly: When true, only SELECT/WITH/EXPLAIN queries are allowed. INSERT, UPDATE, DELETE are blocked.
maxRows: Automatically appends LIMIT to SELECT queries to prevent runaway queries.
schema: Provide the schema so the agent understands the database structure without querying information_schema.

- CSV Toolkit

Provides tools for analyzing CSV data in-memory: search, filter, and aggregate. No database required — just pass your CSV data as a string.

import { CSVToolkit } from 'orkajs/agent/toolkits/csv';
import { ReActAgent } from 'orkajs/agent/react';
 
const csvData = `name,department,salary,start_date
Alice,Engineering,95000,2021-03-15
Bob,Marketing,72000,2020-06-01
Charlie,Engineering,105000,2019-01-10
Diana,Sales,68000,2022-09-20
Eve,Engineering,88000,2023-02-01`;
 
const csvToolkit = new CSVToolkit({
  data: csvData,
  separator: ','  // default
});
 
const agent = new ReActAgent(
  {
    goal: 'Analyze employee data and answer questions',
    tools: csvToolkit.tools,  // Includes: csv_info, csv_search, csv_filter, csv_aggregate
    maxSteps: 8,
  },
  llm
);
 
// Ask questions about the data
const result = await agent.run('What is the average salary in Engineering? Who earns the most?');
 
// The agent will use csv_filter and csv_aggregate tools to find the answer
console.log(result.output);
// "The average salary in Engineering is $96,000. Charlie earns the most at $105,000."
 
// CSV Toolkit tools:
// - csv_info: Get column names, row count, sample data
// - csv_search: Search for rows by column value (partial match)
// - csv_filter: Filter rows with operators (=, !=, >, <, >=, <=, contains)
// - csv_aggregate: count, sum, avg, min, max, distinct

# Combining Agents with Toolkits

You can combine multiple toolkits and custom tools with any agent type:

import { PlanAndExecuteAgent } from 'orkajs/agent/plan-and-execute';
import { SQLToolkit } from 'orkajs/agent/toolkits/sql';
import { CSVToolkit } from 'orkajs/agent/toolkits/csv';
 
const sqlToolkit = new SQLToolkit({ execute: db.query, readOnly: true });
const csvToolkit = new CSVToolkit({ data: reportCSV });
 
// Combine toolkit tools with custom tools
const allTools = [
  ...sqlToolkit.tools,
  ...csvToolkit.tools,
  myCustomSearchTool,
  myCalculatorTool,
];
 
const agent = new PlanAndExecuteAgent(
  {
    goal: 'Cross-reference database records with CSV reports',
    tools: allTools,
    maxSteps: 15,
    replanOnFailure: true,
  },
  llm
);
 
const result = await agent.run(
  'Compare the sales figures in the CSV report with the orders table in the database. Are there any discrepancies?'
);

Agent Type Comparison

Agent	Pattern	Best For	Reliability
Agent (base)	Thought/Action	Simple tool usage	⭐⭐⭐
ReAct	Think → Act → Observe	General-purpose reasoning	⭐⭐⭐⭐
Plan-and-Execute	Plan → Execute → Synthesize	Complex multi-step tasks	⭐⭐⭐⭐⭐
OpenAI Functions	JSON function calls	Precise tool invocation	⭐⭐⭐⭐⭐
Structured Chat	JSON in/out	Structured outputs, auditing	⭐⭐⭐⭐

Best Practices

1. Choose the Right Agent Type

Use ReAct for general tasks, Plan-and-Execute for complex multi-step workflows, OpenAI Functions when you need precise tool calls, and Structured Chat when you need JSON outputs.

2. Set Appropriate Limits

Always set maxSteps to prevent infinite loops. Use policies to restrict tool access and enforce rules.

3. Use Toolkits for Data Analysis

SQLToolkit and CSVToolkit provide battle-tested tools. Always use readOnly mode for SQL in production. Combine multiple toolkits for cross-data analysis.

4. Monitor with verbose Mode

Enable verbose: true on ReActAgent during development to see each Thought/Action/Observation in the console. All agents return detailed steps for production monitoring.

Tree-shaking Imports

// ✅ Import only what you need
import { ReActAgent } from 'orkajs/agent/react';
import { PlanAndExecuteAgent } from 'orkajs/agent/plan-and-execute';
import { OpenAIFunctionsAgent } from 'orkajs/agent/openai-functions';
import { StructuredChatAgent } from 'orkajs/agent/structured-chat';
import { SQLToolkit } from 'orkajs/agent/toolkits/sql';
import { CSVToolkit } from 'orkajs/agent/toolkits/csv';
 
// ✅ Or import from agent index
import { ReActAgent, PlanAndExecuteAgent, SQLToolkit } from 'orkajs/agent';