Skip to main content

​
Quickstart Guide

This guide will walk you through creating your first AI agent with AgentLIB. You’ll build a weather assistant that can answer questions using a custom tool.

​
Prerequisites

  • Node.js 18.0.0 or higher
  • An OpenAI API key

​
Step-by-Step Tutorial

1

Install the packages

Install the core runtime and OpenAI provider:
npm install @agentlib/core @agentlib/openai
If you want to use environment variables, also install dotenv:
npm install dotenv
2

Set up environment variables

Create a .env file in your project root:
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o
Then load it in your code:
import 'dotenv/config'
3

Create a tool

Tools are how agents interact with the outside world. Use defineTool to create a type-safe tool definition:
import { defineTool } from '@agentlib/core'

const weatherTool = defineTool({
  schema: {
    name: 'get_weather',
    description: 'Get the current weather for a location.',
    parameters: {
      type: 'object',
      properties: {
        location: { type: 'string' }
      },
      required: ['location'],
    },
  },
  async execute({ location }) {
    // In a real app, you'd call a weather API here
    return {
      location,
      temperature: 22,
      condition: 'sunny'
    }
  },
})
The schema follows the JSON Schema format and describes the tool’s name, purpose, and parameters. The execute function is called when the agent decides to use this tool.
4

Create an agent

Use the fluent builder API to configure your agent:
import { createAgent } from '@agentlib/core'
import { openai } from '@agentlib/openai'

const agent = createAgent({ name: 'weather-assistant' })
  .provider(openai({ apiKey: process.env.OPENAI_API_KEY! }))
  .tool(weatherTool)
The createAgent function returns an AgentInstance with a chainable API:
  • .provider() — Set the LLM provider (OpenAI, Anthropic, etc.)
  • .tool() — Register a tool the agent can use
  • .memory() — Add conversation history (optional)
  • .reasoning() — Choose a reasoning strategy (optional)
  • .use() — Add middleware (optional)
5

Run the agent

Call agent.run() with a user query:
const result = await agent.run('What is the weather in Tokyo?')
console.log(result.output)
// The agent will call get_weather({ location: 'Tokyo' })
// and return a natural language response
The run method returns a RunResult object:
interface RunResult {
  output: string           // Final response
  state: ExecutionState    // Internal state (steps, messages, usage)
}

​
Complete Example

Here’s the full code: 
import 'dotenv/config'
import { createAgent, defineTool } from '@agentlib/core'
import { openai } from '@agentlib/openai'

const weatherTool = defineTool({
  schema: {
    name: 'get_weather',
    description: 'Get the current weather for a location.',
    parameters: {
      type: 'object',
      properties: { location: { type: 'string' } },
      required: ['location'],
    },
  },
  async execute({ location }) {
    return { location, temperature: 22, condition: 'sunny' }
  },
})

const agent = createAgent({ name: 'assistant' })
  .provider(openai({ apiKey: process.env.OPENAI_API_KEY! }))
  .tool(weatherTool)

const result = await agent.run('What is the weather in Tokyo?')
console.log(result.output)

​
Next Steps

Add Memory

Give your agent conversation history

Reasoning Engines

Use ReAct, Planner, CoT, or custom strategies

Middleware

Add logging, rate limiting, or custom hooks

Events

Listen to agent lifecycle events

​
Common Patterns

​
Multiple Tools

Register multiple tools with separate .tool() calls: 
const agent = createAgent({ name: 'assistant' })
  .provider(openai({ apiKey: process.env.OPENAI_API_KEY! }))
  .tool(weatherTool)
  .tool(calculatorTool)
  .tool(searchTool)

​
Typed Agent State

Use generics to add type-safe custom data: 
interface UserContext {
  userId: string
  preferences: Record<string, any>
}

const agent = createAgent<UserContext>({
  name: 'personal-assistant',
  data: { userId: 'user-123', preferences: {} }
})

​
Session-Based Memory

Isolate conversations by session ID: 
import { BufferMemory } from '@agentlib/memory'

const memory = new BufferMemory({ maxMessages: 20 })
const agent = createAgent({ name: 'chat-bot' })
  .provider(openai({ apiKey: process.env.OPENAI_API_KEY! }))
  .memory(memory)

// Each user gets their own history
await agent.run({ input: 'My name is Alice.', sessionId: 'user-1' })
await agent.run({ input: 'What is my name?', sessionId: 'user-1' })
Make sure to load environment variables before creating the agent. If you forget to call import 'dotenv/config', process.env.OPENAI_API_KEY will be undefined.

Build docs developers (and LLMs) love

Get started for freeTalk to us