Default Project Template
When you initialize a new project with aigne create, a directory is created containing a set of standard files. This default template provides a solid foundation, giving you a ready-to-run chat Agent equipped with a tool for executing JavaScript code. This section breaks down the purpose of each file in the template.
Project Structure Overview#
The files in the default template work together to define your project, configure your Agent, and provide it with tools. The aigne.yaml file acts as the central manifest, linking everything together.
Let's examine each file in detail.
aigne.yaml: The Project's Control Center#
This is the main configuration file for your AIGNE project. It tells the AIGNE CLI which AI model to use, which agents to load, and what tools should be available globally.
chat_model:
provider: openai
name: gpt-4o-mini
temperature: 0.8
agents:
- chat.yaml
tools:
- sandbox.js
- filesystem.yamlKey | Description |
|---|---|
| Defines the AI model provider (e.g., |
| A list of Agent definition files to load. In this template, it loads |
| A list of tool files that are available to all agents in the project. |
chat.yaml: Defining Your Agent#
This file defines the identity and behavior of your chat Agent.
name: chat
description: Chat agent
instructions: |
You are a helpful assistant that can answer questions and provide information on a wide range of topics.
Your goal is to assist users in finding the information they need and to engage in friendly conversation.
input_key: message
memory: true
tools:
- sandbox.jsKey | Description |
|---|---|
| A unique identifier for the Agent. |
| A short description of what the Agent does. |
| The core prompt or system message that guides the AI's behavior. |
| The name of the key used for user input (in this case, |
| A boolean ( |
| A list of tools this specific Agent is permitted to use, such as |
sandbox.js: A JavaScript Execution Tool#
Tools extend your Agent's capabilities beyond simple chat. This file defines a tool that allows the Agent to run JavaScript code in a secure, sandboxed environment. AIGNE inspects the exported function, its description, and its schemas to understand how to use the tool.
import vm from "node:vm";
export default async function evaluateJs({ code }) {
const sandbox = {};
const context = vm.createContext(sandbox);
const result = vm.runInContext(code, context, { displayErrors: true });
return { result };
}
evaluateJs.description = "This agent evaluates JavaScript code.";
evaluateJs.input_schema = {
type: "object",
properties: {
code: { type: "string", description: "JavaScript code to evaluate" },
},
required: ["code"],
};
evaluateJs.output_schema = {
type: "object",
properties: {
result: { type: "any", description: "Result of the evaluated code" },
},
required: ["result"],
};The input_schema tells the AI what data to provide when calling the tool (an object with a code string), and the description helps it understand when to use it.
filesystem.yaml: Filesystem Access Tool#
This demonstrates another way to define a tool, using YAML. This tool is configured to run an external command-line process for filesystem operations, communicating via the Model Context Protocol (MCP).
type: mcp
command: npx
args: ["-y", "@modelcontextprotocol/server-filesystem", "."]Key | Description |
|---|---|
| Specifies the tool type as |
| The command to execute, in this case |
| An array of arguments to pass to the command. |
sandbox.test.js: Ensuring Your Tools Work#
AIGNE includes a built-in test runner. This file contains a basic test for the sandbox.js tool to confirm it executes code correctly. You can run all such tests in your project with the aigne test command.
import assert from "node:assert";
import test from "node:test";
import evaluateJs from "./sandbox.js";
test("evaluateJs should execute script correctly", async () => {
assert.deepEqual(await evaluateJs({ code: "1 + 2" }), { result: 3 });
});.env.local.example: Managing Your Secrets#
This template file is for your environment variables, most importantly your API keys for different AI model providers. To make it active, copy this file to .env.local (which is ignored by Git) and fill in your API key.
# OpenAI
MODEL="openai:gpt-4.1"
OPENAI_API_KEY="YOUR_OPENAI_API_KEY"Now that you understand the structure of a default AIGNE project, the next step is to run it and interact with your new Agent.
Continue to the next section to learn how: aigne run.