Project Layout

When you create a new Sagentic project, you'll find a well-organized directory structure that's ready for you to start developing your autonomous agents. Here's what the layout looks like in a freshly scaffolded project:

Files and Directories

foo/
├── agents/
│   └── hello.ts
├── tools/
│   └── tool.ts
├── index.ts
├── package.json
└── tsconfig.json

• agents/: This directory contains the agent files. Each TypeScript file here defines an autonomous agent class that the Sagentic runtime can execute.

• tools/: Tools that agents can use are defined here. These are TypeScript files that export functions which encapsulate specific functionality or logic that agents can leverage.

• index.ts: The main entry point for the Sagentic runtime. Agents that should be recognized by the runtime are re-exported here. This file acts as a registry for the agents in your project.

• package.json: The heart of any Node.js project, this file manages project metadata, scripts, and the list of dependencies.

• tsconfig.json: Configuration file for TypeScript, specifying compiler options and other settings for the TypeScript project.

Adding a New Agent

To introduce a new agent to your project, follow these steps:

1. Create a New Agent File: Inside the agents/ directory, create a new TypeScript file for your agent. For example, you might create foobar.ts.

2. Define the Agent Class: In your new file, define a class that implements the Agent interface from Sagentic. Make sure to export this class as the default export. Here's a basic template:

   import { BaseAgent } from "sagentic";
   
   export default class FooBarAgent extends BaseAgent<...> {
     // ...agent implementation
   }

3. Re-export in index.ts: Open the index.ts file at the root of your project and import your new agent class:

   import FooBarAgent from "./agents/foobar";

   Then, add your agent class to the array of exported agents:

   export default [FooBarAgent /* other agents */];

The index.ts file should export an array of agent classes. If you have multiple agents, simply include them all in this array.

See Your First Agent for a more detailed walkthrough of how agents are constructed.

Adding a New Tool

Adding a new tool is just as straightforward:

1. Create a New Tool File: In the tools/ directory, create a TypeScript file for your new tool.

2. Define and Export the Tool: Define an object or function that encapsulates the tool's functionality. Export this from the file.

   import { FunctionTool } from "sagentic";
   
   // Example tool definition
   export const myTool = (/* parameters */) => {
     return new FunctionTool(/* tool definition*/);
   };

3. Use the Tool in Agents: Import and use your new tool in any agent by importing it in the agent's file.

See Your First Tool for more information on how to define and use tools.

Free-Form Code

Sagentic projects offer the flexibility to include any TypeScript code, allowing you to structure your application as you see fit. As long as your agents are correctly exported in the index.ts entrypoint, your project structure is valid. The code will be compiled as long as it's imported by any of the agents or tools.

For better organization, it's useful to create a separate directory, such as lib/, for your free-form code. This can help keep utility functions, shared interfaces, and other common code neatly organized and easily accessible.

You're also free to use any Node.js library by installing it with npm install or yarn add. This integration with the NPM ecosystem empowers you to extend your agents' capabilities with a wide range of functionalities available through third-party packages.

Understanding package.json

The package.json file in a Sagentic project includes a scripts section that defines shortcuts for common tasks you'll perform.You can, of course, add your own scripts to the package.json file to customize and enhance your development workflow as needed. Here's a breakdown of each script provided in a typical Sagentic project setup:

dev

"dev": "sagentic run"

This script starts the local development server with hot reload. When you run yarn dev or npm run dev, it invokes the Sagentic CLI's run command, which watches for file changes and automatically reloads your agents, making development faster and more interactive.

build

"build": "tsc"

The build script compiles your TypeScript code into JavaScript using the TypeScript compiler (tsc). This is necessary to prepare your code for production deployment, ensuring that all TypeScript is transpiled to JavaScript, which can be executed in the Node.js environment.

deploy

"deploy": "sagentic deploy"

When you're ready to deploy your agents to a live environment, this script will come in handy. Running yarn deploy or npm run deploy triggers the Sagentic CLI's deploy command, which handles the deployment process for you, packaging and sending your code to the Sagentic hosting platform.

TIP

This feature is coming soon! In the meantime, you can deploy your project with the development server bundled on monk.io.

lint

"lint": "eslint --ext .ts src"

Code quality is important, and linting helps maintain it by checking for syntax errors, enforcing coding standards, and identifying potential bugs. This script runs ESLint on your TypeScript files in the src directory (or whichever directory contains your source code), helping you keep your code clean and consistent.