Skip to main content

​
Overview

The AutonomousEngine implements an open-ended reasoning loop where the agent decides when it’s done by explicitly calling a finish tool. This is the most flexible engine, suitable for long-horizon tasks, research, and multi-step automation. Unlike other engines that terminate based on tool calls or step counts, the autonomous engine runs until the agent signals completion.

​
When to Use

Use AutonomousEngine when:
  • Tasks are open-ended with no fixed termination criteria
  • The agent should decide when it has gathered enough information
  • You need long-horizon reasoning (research, analysis, automation)
  • Task complexity varies and can’t be predicted upfront
  • You want maximum agent autonomy

​
Constructor

import { AutonomousEngine } from '@agentlib/reasoning'

const engine = new AutonomousEngine(config)

​
Configuration

​
maxSteps
number
default:30
Absolute maximum steps before forcing termination. Safety limit to prevent infinite loops.
​
finishToolName
string
default:"finish"
Tool name the agent must call to signal completion. This tool is automatically injected into the tool list.
​
finishToolDescription
string
Description shown to the model for the finish tool. Default: “Signal that you have completed the task. Call this with your final answer.”

​
Usage Example

import { Agent } from '@agentlib/core'
import { AutonomousEngine } from '@agentlib/reasoning'
import { searchTool, browserTool, analysisTool } from './tools'

const agent = new Agent({
  name: 'research-agent',
  model: myModelProvider,
  tools: [searchTool, browserTool, analysisTool],
  reasoning: new AutonomousEngine({
    maxSteps: 50,
    finishToolName: 'complete_research'
  })
})

const result = await agent.run({
  input: 'Research the history of neural networks and create a timeline of major breakthroughs'
})

​
How It Works

  1. Inject Finish Tool: Automatically adds a finish tool to the available tool list
  2. Agent Loop:
    • Model thinks and may call tools
    • Tool results are appended to conversation
    • Process repeats
  3. Termination: Loop ends when:
    • Agent calls the finish tool → uses its result argument as final output
    • Agent responds without any tool calls → uses response content as final output
    • maxSteps is reached → throws error

​
Finish Tool Schema

The automatically injected finish tool has this schema: 
{
  "name": "finish",
  "description": "Signal that you have completed the task. Call this with your final answer.",
  "parameters": {
    "type": "object",
    "properties": {
      "result": {
        "type": "string",
        "description": "Your final answer or output."
      }
    },
    "required": ["result"]
  }
}

​
Agent Usage Example

The model calls the finish tool to signal completion: 
{
  "name": "finish",
  "arguments": {
    "result": "Timeline of Neural Networks:\n1943: McCulloch-Pitts neuron model\n1958: Perceptron (Rosenblatt)\n1986: Backpropagation (Rumelhart et al.)\n2012: AlexNet wins ImageNet\n2017: Transformer architecture (Vaswani et al.)\n2022: ChatGPT released"
  }
}

​
Step Emissions

  • ThoughtStep: Emitted when the model generates content (with or without tool calls)
  • ToolCallStep / ToolResultStep: Emitted for all tool executions (including finish)
  • ResponseStep: Emitted with the final result when finish is called

​
Error Handling

Max steps reached without finish call: 
[AutonomousEngine] Max steps (30) reached. The agent did not call "finish".
Token budget exceeded (if policy set): 
[AutonomousEngine] Token budget exceeded.

​
Comparison with ReactEngine

FeatureAutonomousEngineReactEngine
TerminationAgent calls finish toolModel stops calling tools
ControlAgent-drivenModel-driven
Use CaseOpen-ended tasksBounded tool-using tasks
Default maxSteps3010
Finish ToolRequiredNot applicable

​
Best Practices

  1. Set appropriate maxSteps: Balance autonomy with safety
  2. Use token budgets: Prevent runaway costs in production
  3. Monitor step emissions: Track agent progress and detect loops
  4. Clear instructions: Tell the agent when/how to call finish
  5. Test thoroughly: Autonomous agents can be unpredictable

​
System Prompt Recommendation

Add clear termination instructions: 
const agent = new Agent({
  name: 'researcher',
  systemPrompt: `You are a research assistant. Use available tools to gather information.

When you have completed your research and have a comprehensive answer, call the 'finish' tool with your final result. Do not call finish until you are confident your answer is complete and accurate.`,
  reasoning: new AutonomousEngine()
})

​
String Alias

const agent = new Agent({
  name: 'my-agent',
  reasoning: 'autonomous' // Uses default AutonomousEngine
})

​
Implementation Reference

Source: packages/reasoning/src/engines/autonomous.ts:49

Build docs developers (and LLMs) love

Get started for freeTalk to us