Suppose your application already has a service-search API. You want a user to type “Find hair coloring services” instead of filling out a search form. AGENTO connects those two interfaces: a model interprets the request, while the runtime validates values and executes the HTTP operation allowed by your configuration.
AGENTO runs inside your backend. It does not replace your API or let a model invent arbitrary URLs and permissions.
What changes in an existing application?
In a direct API integration, your code chooses the operation and its inputs. With AGENTO you describe the available operations in config.yml, then let a model choose an appropriate operation and extract arguments from the user's message.
An available operation is a tool. A search tool may call one endpoint. A booking tool may first need to look up availability. A tool is an operation definition, not a new model or necessarily a separate service.
The runtime is the AgentRuntime instance your server creates. It holds configuration and conversation state, validates inputs, coordinates selection and confirmation, and executes HTTP. The model supplies language understanding when you add chat().
Your application still authenticates callers, owns their sessions, and displays results or questions. Your API still enforces permissions and business rules.
Follow one search request
The user asks for hair coloring services. The model chooses search-services and supplies a search phrase as query. The runtime checks that it is a valid string.
The mapping q: $.query sends that value to the API as the query parameter q. Your application receives the response and can display data directly or request a language-based presentation.
These are separate decisions: a description helps choose an operation, input_schema defines acceptable arguments, and request.map defines the outgoing HTTP request. A good description cannot fix the wrong API parameter name.
Start with invoke(), supplying the tool and inputs yourself. After it works, use chat() to obtain those choices from language. The configured HTTP operation stays the same.
Follow this path for your first integration
- Install the library in your backend.
- Connect a real endpoint: prepare
api-context.md, create one tool, and compare it with a working direct request. - Understand config.yml: separate tool settings from runtime settings and add only what the operation needs.
- Define inputs, map them to HTTP, and control responses.
- Add a model, understand tool routing, and handle runtime results in your UI.
You now have a reading integration you can explain from user message to API response. Custom stores and MCP are not prerequisites.
When does one operation need other tools?
“Book tomorrow” provides a date, not an internal availability ID. A dependency obtains that ID from the API and asks for a choice when several slots exist.
Booking also changes data. Add a review and confirmation step before POST. The booking example is an optional isolated exercise for those policies, not a prerequisite for connecting your own API.
For browsing categories and opening the selected category's products, use navigation.
Read the remaining chapters when needed
During host integration, use the runtime API reference, authentication, and sessions. Before release, examine HTTP failure policies, observability, and production readiness.
When something fails, follow troubleshooting, then look up the returned code in errors. These chapters are references, not a linear course you must finish first.
Terms used throughout this guide
An API contract describes an endpoint's request, response, authentication, and constraints. It comes from your system's evidence.
A schema defines the accepted shape of data. input_schema describes tool arguments; output_schema validates a response.
A mapping connects a value's source to its destination. It is not JavaScript inside YAML or automatic forwarding of everything a model produced.
A dependency is a tool whose data another tool needs, not an npm package dependency.
A session stores conversation and pending workflow state. Its identifier does not authenticate the caller; your backend binds it to its owner.
This guide documents the public package agento-runtime@1.0.0. The npm package version is separate from the configuration format, which remains version: "2". Check installation before running commands.