Create your first project

You will create a project with one Agent, run its TypeScript check, and receive a model response. Use Node.js 22.18+ within v22 or 24.11+ within v24. The basic template calls OpenAI, so you need an API key and access to the selected model. Prefer an example without provider credentials? Start with the local harness workflow. Already have a TypeScript application? Use the manual quickstart.

Scaffold and install

Run this in the parent directory where you want the new project:

npx @agentium/cli@4.0.0 init my-agent --template basic
cd my-agent
npm install

The destination must not already exist. The CLI creates package.json, tsconfig.json, src/index.ts, .gitignore, and a README. The project uses ESM and includes start and typecheck scripts. Scaffolding creates files; it does not run the model.

my-agent/
├── package.json       # start and typecheck scripts
├── tsconfig.json      # TypeScript and ESM settings
├── src/index.ts       # Agent, prompt, run, and cleanup
├── .gitignore
└── README.md

Configure and verify

In the same terminal:

export OPENAI_API_KEY="your-key"
export OPENAI_MODEL="gpt-6.1-sol"
npm run typecheck
npm start

The type check should exit successfully. Starting the app sends its sample prompt to OpenAI and prints the response, then closes the Agent. Exact wording varies. Keep the key in the server environment; the generated project does not load a .env file automatically. See example model choices if your account uses another model. A type check verifies the program’s types; the successful response verifies this provider connection.

Change one thing

Open src/index.ts. Change the Agent’s instructions and the input passed to run(), then run npm start again. Next, add a lookup tool so the response can depend on application data.

Choose another template

Template	What it creates	Extra requirement
`basic`	One Agent request with cleanup	Text-model credentials
`rag`	In-memory retrieval passed into an Agent	Text and embedding model access
`browser`	A BrowserAgent application	`npx playwright install chromium`, model access
`voice`	A configured VoiceAgent	Host media transport and explicit connection lifecycle

Pass the template to the same init command with a new project name. The voice template is a configuration starting point: running it alone does not connect a microphone. Continue with voice adapters for the media path. The CLI has no harness template in v4; use the harness quickstart.

If setup fails

Symptom	Fix
Destination already exists	Choose a new lowercase project name or use the existing project directly
Unsupported engine	Check `node --version` against the supported Node ranges above
`Missing script: dev`	Use `npm start`; hot reload is a separate CLI command
Authentication or model-access error	Verify the key in this terminal and set a model your account can access
It asks for information instead of using your database	Supply a tool; the initial Agent has no application data integration

Continue with the support assistant tutorial, or choose a build path for your own application.

Start here

Build a support assistant

Setup and release

Create your first project

Scaffold and install

Configure and verify

Change one thing

Choose another template

If setup fails

​Scaffold and install

​Configure and verify

​Change one thing

​Choose another template

​If setup fails

Scaffold and install

Configure and verify

Change one thing

Choose another template

If setup fails