Sagentic AF CLI

The Sagentic CLI is a command-line interface that helps you create, build, and deploy autonomous agents. It's the primary tool for developing agents with Sagentic AF. This document provides an overview of the Sagentic CLI and its commands.

How to Install

You can install the Sagentic CLI using npm or yarn. To install the CLI globally, run the following command:

npm

npm install -g @sagentic-ai/sagentic-af

yarn

yarn global add @sagentic-ai/sagentic-af

See the installation guide for more information.

Help

To get help with the Sagentic CLI, run the following command:

sagentic help

You can also get help with a specific command by running:

sagentic help <command>

Here's an example of the help output:

Usage: sagentic [options] [command]

😎 Sagentic Agent Framework CLI

Options:
  -V, --version                        output the version number
  -h, --help                           display help for command

Commands:
  init [options] [path]                Initialize a new project
  new                                  Scaffold agents and tools
  run [importPaths...]                 Run a project
  deploy                               Deploy a project to sagentic.ai
  spawn [options] <name> [options...]  Spawn an agent
  help [command]                       display help for command

Commands

The Sagentic CLI provides several commands to help you manage your Sagentic projects. Here's a brief overview of each command.

init

Usage: sagentic init [options] [path]

Initialize a new project

Arguments:
  path               Path to the project (default: ".")

Options:
  -n, --name <name>  Name of the project
  -h, --help         display help for command

The init command initializes a new Sagentic project in the specified directory. You can use the -n or --name option to specify the name of the project that will be used in the package.json file. This project name will be used to namespace your agents and tools upon deployment to Sagentic Platform.

When called without a path, the init command will create a new project in the current directory.

When called with a path, the init command will create a new project in the specified directory creating it if it doesn't exist. If the directory is not empty, the init command will abort.

new

Usage: sagentic new [options] [command]

Scaffold agents and tools

Options:
  -h, --help           display help for command

Commands:
  agent <name> [type]  Scaffold a new agent
  tool <name>          Scaffold a new tool
  help [command]       display help for command

The new command provides subcommands to scaffold new agents and tools. You can use the agent subcommand to create a new agent, and the tool subcommand to create a new tool.

agent

Usage: sagentic new agent [options] <name> [type]

Scaffold a new agent

Arguments:
  name        Name of the new agent
  type        Type of the new agent (default: "reactive")

Options:
  -h, --help  display help for command

The agent subcommand scaffolds a new agent in the src/agents directory of your project and adds an export for it to index.ts file.

You can use the type option to specify the type of agent you want to create. Currently available types are: reative and one-shot. The default type is reactive.

The name of the agent should be in PascalCase and should not contain the word Agent at the end. For example, Hello is a valid name, but HelloAgent is not.

tool

Usage: sagentic new tool [options] <name>

Scaffold a new tool

Arguments:
  name        Name of the new tool

Options:
  -h, --help  display help for command

The tool subcommand scaffolds a new tool in the src/tools directory of your project.

The name of the tool should be in camelCase and should not contain the word Tool at the end. For example, search is a valid name, but searchTool is not.

run

Usage: sagentic run [options] [importPaths...]

Run a project

Options:
  -h, --help  display help for command

The run command starts local development server. You can use the importPaths argument to specify the paths to packages exporting agent constructors implementing Sagentic interfaces. In most cases it's perfectly fine to ignore this. If no import paths are provided, the run command will run the project in the current directory.

The local development server will be available at http://localhost:3000 by default. You can use the PORT environment variable to specify a different port. The server will automatically reload when you make changes to your agents and tools.

This command is useful for testing your agents and tools locally before deploying them to the Sagentic platform.

deploy

Usage: sagentic deploy [options]

Deploy a project to sagentic.ai

Options:
  -h, --help  display help for command

The deploy command deploys your project to the Sagentic platform. This command will deploy your project to the Sagentic platform. You can use the SAGENTIC_API_KEY environment variable to specify your Sagentic API key. If the SAGENTIC_API_KEY environment variable is not set, the deploy command will abort. It is recommended to set the SAGENTIC_API_KEY environment variable in your .env file or in your CI/CD environment.

spawn

Usage: sagentic spawn [options] <name> [options...]

Spawn an agent

Arguments:
  name             Name of the agent to spawn
  options          Options for the agent, as key=value pairs

Options:
  -l, --local      Spawn the agent locally
  -u, --url <url>  URL of the sagentic server
  -d, --details    Show extra details about the session
  -h, --help       display help for command

The spawn command spawns an agent. It is a convenient way to invoke an agent without having to use curl or another HTTP client.

Specify the name of the agent to spawn as the first argument. You can use the options arguments to specify the options for the agent as key=value pairs.

The name of the agent should be fully qualified, including the project name and the agent name. For example, your-username/your-project/YourAgent.

TIP

Read more about naming conventions here.

You can use the --local option to spawn the agent locally. You can use the --url option to specify the URL of the Sagentic server. You can use the --details option to show extra details about the session.