AI Agents with Tool Calling

AxilJS provides an AI agent API for building TypeScript and Node.js AI applications with tool calling, multi-step execution, custom tools, and streaming.

An Agent can receive a user request, decide which tools to use, execute those tools, and return the final response. This makes it suitable for applications that need AI models to interact with external functions or services.

Setup#

Create an agent with an AI provider and one or more tools.

import { Agent, createTool, calculatorTool } from '@axiljs/ai'
 
const agent = new Agent({
  provider: ai,
  tools: [calculatorTool, weatherTool],
  maxIterations: 10
})

The tools option defines the functions available to the agent. maxIterations controls the maximum number of agent execution steps.

Run an AI Agent#

Use agent.run() to execute a request and receive the result.

const result = await agent.run('What is 25 * 4?')
 
result.response
result.steps

The returned result provides the agent's final response along with its execution steps.

This execution model is useful when an AI agent needs to perform one or more tool calls before producing its final answer.

Create Custom AI Tools#

You can define application-specific tools with createTool().

For example, a weather tool can expose a function that an agent can call when it needs weather information.

const weatherTool = createTool({
  name: 'get_weather',
  description: 'Get weather for a city',
  parameters: {
    type: 'object',
    properties: { city: { type: 'string' } },
    required: ['city']
  },
  handler: async ({ city }) => ({ city, temp: '22C' })
})

A custom tool defines:

• name — the identifier used by the agent.
• description — explains what the tool does.
• parameters — describes the tool input.
• handler — contains the function executed when the tool is called.

This allows you to connect AxilJS agents to application logic, APIs, databases, services, and other external capabilities.

Stream Agent Execution#

For applications that need incremental agent execution, use runStream().

for await (const step of agent.runStream('Calculate 2^10')) {
  console.log(step.thought, step.toolCalls, step.finalAnswer)
}

The stream exposes individual execution steps as they become available. Each step can include the agent's thought, toolCalls, and finalAnswer.

Streaming is useful for interactive AI applications where you want to observe or process agent execution progressively instead of waiting for the complete result.

Agent Workflow#

A typical AxilJS agent workflow consists of:

1. Create an Agent with an AI provider.
2. Register built-in or custom tools.
3. Send a request with agent.run().
4. Allow the agent to execute the required tools.
5. Read the final response and execution steps.
6. Use runStream() when incremental execution is required.

User Request
     │
     ▼
   Agent
     │
     ├──► Tool Call
     │       │
     │       ▼
     │   Tool Handler
     │       │
     │       ▼
     │   Tool Result
     │       │
     └───────┘
     │
     ▼
Final Response

When to Use AxilJS Agents#

AxilJS agents are useful when an AI application needs to go beyond generating text and interact with executable tools.

Common use cases include:

• AI assistants with external tools
• Calculator and utility agents
• Weather and API integrations
• Database-aware AI applications
• Automated workflows
• Multi-step AI operations
• Interactive streaming agents