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 configAGENTO / AI Agent Runtime
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-runtimeNode.js 20.11+ · TypeScript · Runs in your backend
needs_selectionYour item is eligible. How would you like the refund?
POST /returnsawaiting confirmationLocal illustration. No API requests are sent.
Your endpoints. Your authentication. Your business rules.
Documented release v1.1.001 / WHY AGENTO
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.
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 configDeclare 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 handlingConfigure confirmation for writes. Your app shows the prepared action; your API still enforces permissions and business rules.
Understand confirmation02 / THE INTEGRATION
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.
Keep the method, URL, authentication, and parameter names your API already uses.
Choose a tool-capable model supported by your provider. Supply its API key from your server environment.
Pass the message, session ID, and user token to chat(). Handle results and any requested inputs, choices, or confirmations in your app.
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 languagelanguage: arReply in a configured languageversion: "2"
assistant:
language: auto
models:
routing:
provider: openai
model: YOUR_TOOL_CAPABLE_MODEL
api_key: $ENV:OPENAI_API_KEY
tools:
- id: find-orders
tool:
description: Find the current user's orders by product name.
input_schema:
type: object
properties:
query: { type: string, minLength: 1 }
required: [query]
request:
method: GET
url: https://api.example.com/orders
auth: { type: session }
map:
query:
q: $.query
Replace the example URL and model placeholder. Set OPENAI_API_KEY in your backend environment. The search uses the current user’s API token.
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
“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.
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.
The order ID feeds the item lookup. The item ID feeds eligibility and return options. The selected return option feeds the final request.
Ask the user when several orders, items, or return methods match. Resume with the selected API result, then confirm before creating the return request.
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: $.idorders → items → return options → return requestGET /ordersRead-only lookupSearch orders using the customer’s token and product name.
order_id → purchased itemsGET /order-itemsRead-only lookupRead the items belonging to that order.
item_id → return eligibilityGET /return-optionsRead-only lookupAsk your API which methods this item qualifies for.
options → user selectionneeds_selectionSelectionUse the selected refund method from the API response.
return_option_id → return requestneeds_confirmationConfirmationShow the item and selected method before submission.
explicit confirmationPOST /returnsFinal writeYour API accepts or rejects the request under its policies.
API response → resultIllustrative endpoints and values. Read-only dependencies run before the final write.
04 / CONTROL STAYS WITH YOUR APP
The model interprets the request. Your configuration defines what can run. Your API decides whether the caller is allowed to do it.
Read the architectureInterprets intent and proposes tool inputs.
Validates inputs, resolves dependencies, and executes configured HTTP requests.
Authenticates the caller and enforces permissions and business rules.
Need MCP? Reuse compiled tools through the MCP adapter.
MCP integrationBEFORE YOU START
No. AGENTO runs alongside your application and calls your existing REST endpoints. You define their inputs and request mappings in config.yml.
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 APIYes. 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 flowsThere 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 guideBUILD ON WHAT YOU ALREADY HAVE
Connect it. Verify the result. Then let your users ask for it.