For releases that include agento-openapi, generate a config from OpenAPI. That optional feature is documented separately from the 1.0.0 installation flow below.
AGENTO is a server-side ESM package. Use npm to consume the library; use GitHub to inspect the source, report issues, or contribute. Cloning the repository is not an application installation step.
Requirements and release availability
The public package requires Node.js 20.11 or newer and is published as agento-runtime. This guide documents v1.0.0. The configuration format remains version: "2"; that value is independent from the npm package version.
Availability check: verify the package and dist-tags from the npm registry before installing. An E404 means the requested package or version is not available in the registry; it is not a configuration error.
node --version
npm --version
npm view agento-runtime version dist-tags
1. Add the package to your application
Install :
npm install agento-runtime
2. Use the ESM import
In a .mjs file, or an ESM TypeScript application:
import { AgentRuntime } from "agento-runtime";
For .js files, set "type": "module" in your application's package.json. Run the library in your Node backend, not in browser code.
3. Load config.yml once at startup
Create config.yml using the first-tool tutorial. The filename is your choice; the runtime reads the path you pass.
import { AgentRuntime } from "agento-runtime";
const runtime = await AgentRuntime.create({
configPath: "./config.yml",
presentation: "raw",
});
The relative path is resolved from your process's working directory. Include the YAML file in the deployed artifact, or pass configYml as a string or config as an object. Supply exactly one of these three options.
Creation parses and validates the complete configuration. Unknown keys, invalid mappings, unsafe dependencies, missing secrets, or unconfirmed writes fail startup. Handle that failure in your boot process; do not start serving traffic with an unusable runtime.
Keep one runtime per process and immutable configuration. Pass the authenticated sessionId, auth.token, context, and cancellation signal on each operation. Call dispose() during shutdown to stop its credential cleanup timer.
4. Add secrets only when a feature needs them
Direct invoke() with raw output does not require a model key. When you enable a model, its YAML key is an environment reference:
# Root fragment; use a model ID supported by your account.
models:
routing:
provider: openai
model: YOUR_TOOL_CAPABLE_MODEL
api_key: $ENV:OPENAI_API_KEY
Set the value in your server environment or secret manager. For a local shell:
# Bash
export OPENAI_API_KEY="your-development-key"
# PowerShell
$env:OPENAI_API_KEY = "your-development-key"
AGENTO does not automatically load a .env file. Let your framework load it, or use Node's --env-file option when running your application. Never commit real keys.
A service API key uses request.auth.env: SERVICE_KEY, without the $ENV: prefix. A user's access token is passed through the call's auth object. These are three distinct channels; see authentication.
5. Connect your first real endpoint
Follow the quick start for your own API. Begin with a known successful request, document its fields, configure one tool, and compare its real response with your direct call. No mock server is required.
Credential-bearing HTTP calls require HTTPS unless request.allow_insecure_http: true explicitly permits local development transport. Do not carry that development setting into production.
Contribute through GitHub
For library development, clone KhALiLXD/agento, install its development dependencies, and run its tests. That workflow is for changing the library itself. Application developers install the npm package and own their config.yml.