Agents & Tools

Build structured agents with tools and policies, ensuringdeterministic safety guardrails.

Why Agents?

Agents are LLMs that can take actions. Instead of just generating text, they can call tools (functions) to interact with external systems, databases, APIs, and more. Orka agents follow a structured reasoning loop: they think about what to do, take an action, observe the result, and repeat until they have a final answer.

import { createOrka } from '@orka-js/core';
import { OpenAIAdapter } from '@orka-js/openai';
import type { Tool } from '@orka-js/tools';
 
const orka = createOrka({
  llm: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! }),
  vectorDB: myVectorDB,
});
 
const agent = orka.agent({
  goal: 'Help customers with their orders',
  tools: [getOrder, cancelOrder, refundOrder],
  policy: {
    maxSteps: 5,
    noHallucination: true,
    rules: ['Always verify order exists before any action'],
  },
});
 
const result = await agent.run('What is the status of order ORD-123?');
 
console.log(result.output);      // "Order ORD-123 is currently being shipped..."
console.log(result.toolsUsed);   // ['get_order']
console.log(result.steps);       // Detailed reasoning trace
console.log(result.totalTokens); // Token usage

# Defining Tools

Tools are functions that agents can call. Each tool has a name, description, parameters, and an execute function. The description is crucial — it tells the LLM when and how to use the tool.

import type { Tool } from '@orka-js/tools';
 
const getOrder: Tool = {
  name: 'get_order',
  description: 'Retrieve an order by its ID. Returns order status, items, and shipping info.',
  parameters: [
    {
      name: 'orderId',
      type: 'string',
      description: 'The order ID (e.g., ORD-123)',
      required: true,
    },
  ],
  async execute(input) {
    const order = await db.orders.findById(input.orderId as string);
    if (!order) {
      return { output: '', error: `Order ${input.orderId} not found` };
    }
    return {
      output: `Order ${order.id}: ${order.status}, shipped via ${order.carrier}`,
      metadata: { orderId: order.id, status: order.status },
    };
  },
};
 
const cancelOrder: Tool = {
  name: 'cancel_order',
  description: 'Cancel an order. Only works for orders not yet shipped.',
  parameters: [
    { name: 'orderId', type: 'string', description: 'Order ID to cancel', required: true },
    { name: 'reason', type: 'string', description: 'Cancellation reason', required: false },
  ],
  async execute(input) {
    const result = await db.orders.cancel(input.orderId as string, input.reason as string);
    if (!result.success) {
      return { output: '', error: result.error };
    }
    return { output: `Order ${input.orderId} has been cancelled.` };
  },
};

Tool Interface

Agentic Tool Interface

Functional Contract for LLM Tool-Calling

nameIdentity

string

Unique snake_case identifier (e.g., fetch_user_data).

descriptionSemantics

string

Detailed semantic prompt for LLM decision-making.

parametersValidation

ToolParameter[]

Typed schema with names and required flags.

execute()Execution

Promise<ToolResult>

The operational logic returning output or errors.

# Agent Policies

Policies control agent behavior and add safety guardrails. Use them to limit steps, restrict tools, and enforce rules.

Property	Type	Description
maxSteps	`number`	Maximum reasoning steps
noHallucination	`boolean`	Instruct agent not to hallucinate
rules	`string[]`	Custom rules in natural language
allowedTools	`string[]`	Whitelist of allowed tools
blockedTools	`string[]`	Blacklist of forbidden tools

Reasoning & Action Loop

Orka JS agents leverage a cyclic ReAct architecture to interleave thought processes with real-world interactions.

Think— Reasoning

"I need to find the order status first"

Act— Tool Call

Call get_order({ id: '123' })

Observe— Evidence

"Status: Shipped via FedEx"

Finish— Response

Deliver answer to user

# Agent Result

Property	Type	Description
output	`string`	Final answer from the agent
toolsUsed	`string[]`	Names of tools that were called
steps	`AgentStep[]`	Detailed trace of each reasoning step
totalTokens	`number`	Total tokens consumed
metadata	`object`	Combined metadata from all tool calls

Complete Example

import { createOrka, OpenAIAdapter } from '@orka-js/core';
import type { Tool } from '@orka-js/tools';
 
const orka = createOrka({
  llm: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! }),
  vectorDB: myVectorDB,
});
 
// Define tools
const getWeather: Tool = {
  name: 'get_weather',
  description: 'Get current weather for a city',
  parameters: [
    { name: 'city', type: 'string', description: 'City name', required: true },
  ],
  execute: async (input) => {
    const weather = await weatherAPI.get(input.city as string);
    return { output: `${weather.temp}°C, ${weather.condition}` };
  },
};
 
const sendEmail: Tool = {
  name: 'send_email',
  description: 'Send an email to a recipient',
  parameters: [
    { name: 'to', type: 'string', description: 'Email address', required: true },
    { name: 'subject', type: 'string', description: 'Email subject', required: true },
    { name: 'body', type: 'string', description: 'Email body', required: true },
  ],
  execute: async (input) => {
    await emailService.send(input.to, input.subject, input.body);
    return { output: `Email sent to ${input.to}` };
  },
};
 
// Create agent with policies
const agent = orka.agent({
  goal: 'Help users with weather info and email tasks',
  tools: [getWeather, sendEmail],
  policy: {
    maxSteps: 5,
    noHallucination: true,
    rules: [
      'Always confirm before sending emails',
      'Provide temperature in both Celsius and Fahrenheit',
    ],
    blockedTools: [], // Could block 'send_email' for read-only mode
  },
});
 
// Run the agent
const result = await agent.run('What is the weather in Paris?');
console.log(result.output);
// "The current weather in Paris is 18°C (64°F), partly cloudy."

Advanced Agent Frameworks

High-Autonomy Decision Systems

ReAct & Structured Chat

Dynamic

Dynamic reasoning interleaved with tool use for conversational flexibility.

Plan-and-Execute

Architected

High-level goal decomposition into a fixed roadmap before any tool execution.

OpenAI Functions

Native

Native model-level integration for high-reliability structured data extraction.

Toolkits (SQL, CSV)

Domain-Specific

Specialized connectors for direct interaction with structured data sources.

Need to handle complex reasoning? Explore our specialized documentation.

Tree-shaking Imports

// ✅ Import types
import type { Tool, ToolParameter, ToolResult } from '@orka-js/tools';
 
// ✅ Import agent types for advanced usage
import { ReActAgent, PlanAndExecuteAgent } from '@orka-js/agent';