Getting Started

This guide provides the necessary steps to set up your development environment and run your first AI agent using the AIGNE Framework. The process is designed to be completed in under 30 minutes, offering a practical, hands-on introduction to the framework's fundamental workflow.

We will cover system prerequisites, installation of the required packages, and a complete, copy-paste-ready example that demonstrates how to define, configure, and execute a basic AI agent.

Prerequisites#

Before proceeding, ensure your development environment meets the following requirement:

• Node.js: Version 20.0 or higher is required.

You can verify your Node.js version by executing the following command in your terminal:

node -v

Installation#

To begin, you need to install the core AIGNE package and a model provider package. For this guide, we will use the official OpenAI model provider.

Install the necessary packages using your preferred package manager:

Additionally, you will need an OpenAI API key. Set it as an environment variable named OPENAI_API_KEY.

OPENAI_API_KEY="sk-..."

Quick Start Example#

This example demonstrates the complete process of creating and running a simple "assistant" agent.

1. Create a new TypeScript file named index.ts.
2. Copy and paste the following code into the file.

import { AIAgent, AIGNE } from "@aigne/core";
import { OpenAIChatModel } from "@aigne/openai";

// 1. Instantiate the AI Model
// This creates a connection to the OpenAI API using the specified model.
// The API key is read from the OPENAI_API_KEY environment variable.
const model = new OpenAIChatModel({
  model: "gpt-4o-mini",
});

// 2. Define the AI Agent
// An agent is a unit of work. This AIAgent is configured with
// instructions that define its personality and task.
const assistantAgent = AIAgent.from({
  name: "Assistant",
  instructions: "You are a helpful and friendly assistant.",
});

// 3. Instantiate the AIGNE
// The AIGNE class is the central orchestrator that manages and runs agents.
// It is configured with the model that its agents will use.
const aigne = new AIGNE({ model });

async function main() {
  // 4. Invoke the Agent

Running the Example#

Execute the script from your terminal. If you are using TypeScript, you can use a tool like ts-node.

npx ts-node index.ts

Expected Output#

The output will be the agent's response to the question, formatted as a JSON object. The content of the message field will vary, as it is generated by the AI model.

{
  "message": "The sky appears blue because of a phenomenon called Rayleigh scattering..."
}

Code Breakdown#

The example is composed of four primary steps that represent the core workflow of the AIGNE Framework.

1. Model Initialization: An instance of OpenAIChatModel is created. This object serves as a direct interface to the specified OpenAI model (e.g., gpt-4o-mini). It requires an API key for authentication, which is automatically sourced from the OPENAI_API_KEY environment variable.
2. Agent Definition: An AIAgent is defined using the static from method. This is the fundamental unit of work in the framework. Its behavior is defined by the instructions property, which acts as a system prompt, guiding the AI model's responses.
3. AIGNE Instantiation: The AIGNE class is instantiated. It acts as the execution engine and orchestrator for all agents. By passing the model instance into its constructor, we establish a default model for all agents managed by this AIGNE instance.
4. Agent Invocation: The aigne.invoke() method is called to execute the assistantAgent. The first argument is the agent to run, and the second is the input message. The framework manages the complete lifecycle of the request: sending the prompt and instructions to the model, receiving the response, and returning it as structured output.

This simple example illustrates the modular and declarative nature of the framework, where models, agents, and the execution engine are configured and composed to build powerful AI-driven applications.

Summary#

In this guide, you have successfully set up your environment, installed the necessary AIGNE packages, and built and run a functional AI agent. You have learned the basic workflow: defining a model, creating an agent with specific instructions, and using the AIGNE to invoke it with a user prompt.

With this foundation, you are now ready to explore more advanced topics.

• To understand the fundamental building blocks of the framework in greater detail, proceed to the Core Concepts documentation.
• To learn about the different types of specialized agents and their use cases, see the Agent Types section.