Skip to content

AGENTO / AI Agent Runtime

Your API already works.Give it an agent.

Let users search, choose, and take action through conversation. AGENTO turns one request into a flow across dependent REST endpoints, passing results between steps and asking for confirmation before writes.

npm install agento-runtime

Node.js 20.11+ · TypeScript · Runs in your backend

Interactive examplereturns.flow
USER

Return the headphones from my latest order.

AGENTOneeds_selection

Your item is eligible. How would you like the refund?

Execution trace
  1. Find the customer’s order
  2. Resolve the purchased item
  3. Check eligibility + return options
  4. 04Wait for a refund methodWaiting
  5. 05Wait for confirmation
  6. 06Create the return request
POST /returnsawaiting confirmation

Local illustration. No API requests are sent.

Your endpoints. Your authentication. Your business rules.

Documented release v1.1.0

01 / WHY AGENTO

The API is built. The agent plumbing adds up.

Choosing a tool is one step. A useful integration also needs valid inputs, real IDs, session state, and a way to ask before changing data.

Describe the operation once

Define tool inputs, HTTP mapping, and response handling in YAML. Send the user’s message to chat(); AGENTO chooses the tool and prepares its arguments.

Explore the config

Build flows across endpoints

Declare nested dependencies between tools. AGENTO runs the required lookups in order, maps each result into the next step, and resumes after user choices.

See dependency handling

Review before changing data

Configure confirmation for writes. Your app shows the prepared action; your API still enforces permissions and business rules.

Understand confirmation

02 / THE INTEGRATION

One endpoint is enough to start.

Describe an operation in YAML, configure a routing model, and send the user’s message to chat(). AGENTO selects the tool, extracts its inputs, and calls your existing API.

  1. 01

    Define your tool

    Keep the method, URL, authentication, and parameter names your API already uses.

  2. 02

    Configure the routing model

    Choose a tool-capable model supported by your provider. Supply its API key from your server environment.

  3. 03

    Send the user’s message

    Pass the message, session ID, and user token to chat(). Handle results and any requested inputs, choices, or confirmations in your app.

Understand the user’s language. Configure the reply language.

Multilingual requests use the same tools. Set assistant.language to auto to follow the user’s language, or set ar or en to guide replies in a specific language.

language: autoFollow the user’s language
language: arReply in a configured language
Language and assistant settings
Follow the integration guide
runtime.mjsESM / Node.js
import { AgentRuntime } from "agento-runtime";
 
// Create once when your backend starts.
const runtime = await AgentRuntime.create({
  configPath: "./config.yml",
  presentation: "raw",
});
 
// The user message to the agent.
const clientMessage = "Find my headphone order";
// AGENTO selects find-orders and extracts its inputs.
const result = await runtime.chat({
  sessionId: `user-${user.id}`,
  auth: {
    token: user.accessToken,
  },
  message: clientMessage,
});
 
console.log(result);

user comes from your authenticated backend. chat() uses the routing model in config.yml to select the tool; your API enforces the user’s permissions.

03 / DEPENDENCY FLOWS

One request. A flow across your endpoints.

“Return my headphones” needs more than a product name. Your API must find the customer’s order, identify the purchased item, and provide eligible return options. AGENTO connects those lookups before it prepares the return request.

Dependencies can have dependencies

Return options depend on the purchased item; that item depends on the customer’s order. AGENTO resolves the deepest lookup first, then resumes the parent operation.

Results become the next step’s inputs

The order ID feeds the item lookup. The item ID feeds eligibility and return options. The selected return option feeds the final request.

Pause for a choice, then continue

Ask the user when several orders, items, or return methods match. Resume with the selected API result, then confirm before creating the return request.

See a dependency declaration

Fragment on request-return. The complete example also declares return-options → order-items → find-orders, each with its own authenticated request and mapping.

# On the request-return tool:
depends_on:
  - tool: return-options
    arguments:
      query: $.query
    select:
      items_path: $.options
      id_path: $.id
      label_path: $.label
      id_sensitive: true
      facts:
        item: $.item_name
        method: $.label
    map:
      $.return_option_id: $.id
Example execution orderorders → items → return options → return request
  1. 01
    GET /ordersRead-only lookup

    Find the customer’s order

    Search orders using the customer’s token and product name.

    order_id → purchased items
  2. 02
    GET /order-itemsRead-only lookup

    Identify the purchased item

    Read the items belonging to that order.

    item_id → return eligibility
  3. 03
    GET /return-optionsRead-only lookup

    Get eligible return options

    Ask your API which methods this item qualifies for.

    options → user selection
  4. 04
    needs_selectionSelection

    Let the user choose

    Use the selected refund method from the API response.

    return_option_id → return request
  5. 05
    needs_confirmationConfirmation

    Review and confirm

    Show the item and selected method before submission.

    explicit confirmation
  6. 06
    POST /returnsFinal write

    Create the return request

    Your API accepts or rejects the request under its policies.

    API response → result

Illustrative endpoints and values. Read-only dependencies run before the final write.

04 / CONTROL STAYS WITH YOUR APP

Language in. Defined operations out.

The model interprets the request. Your configuration defines what can run. Your API decides whether the caller is allowed to do it.

Read the architecture
  1. 01

    Your model

    Interprets intent and proposes tool inputs.

  2. 02

    AGENTO

    Validates inputs, resolves dependencies, and executes configured HTTP requests.

  3. 03

    Your API

    Authenticates the caller and enforces permissions and business rules.

Need MCP? Reuse compiled tools through the MCP adapter.

MCP integration

BEFORE YOU START

A few practical answers.

Do I need to rebuild my backend?

No. AGENTO runs alongside your application and calls your existing REST endpoints. You define their inputs and request mappings in config.yml.

Can I call a tool directly?

Yes. invoke() is a separate API for an operation your application already knows how to choose. The agent interface is chat(): it takes a user message and selects the configured tool through your routing model.

Read the runtime API
Can one request run through several endpoints?

Yes. A tool can declare read-only dependencies, and those tools can have their own dependencies. AGENTO resolves them in order, maps returned values into parent inputs, pauses for selection when needed, and resumes the flow before the confirmed final operation.

Explore dependency flows
What if I already have an OpenAPI document?

There is a separate guide for generating AGENTO config from OpenAPI. Check the guide’s release availability, review the generated YAML, then load it into the normal runtime. The generator is not a runtime layer.

Read the OpenAPI guide

BUILD ON WHAT YOU ALREADY HAVE

Start with one real API call.

Connect it. Verify the result. Then let your users ask for it.