If your API already has OpenAPI, use the OpenAPI generator as an alternative config-authoring path when your installed release includes it. Review the result before continuing with runtime integration.
You already have a working API. Start by making AGENTO call one operation you understand, then add natural-language access to that same operation. You do not need a mock server or a replacement backend.
You will produce three things: a reusable api-context.md describing your API, a config.yml containing one tool, and a real request whose result you can compare with a direct API call.
Using a model to help prepare the files is optional. Running the first tool does not require a model: first verify the HTTP integration, then introduce conversation.
1. Choose an operation you can already call
Choose a read-only endpoint, such as searching services or listing products. Call it with your usual HTTP client and keep the successful request and a sanitized response. Start with an operation that does not create, charge, update, or delete anything.
Record its method, complete URL, required fields and their locations, and authentication scheme. These facts come from your API. Do not change the API to fit the names in this tutorial.
We will explain the mapping using GET /services?q=hair. This is an illustrative contract, not a hosted demo. Your API might use /products?search=phone; preserve that contract when adapting the example.
2. Create a portable API context document
If you already know the contract, write it down yourself and continue. To use a model, provide your OpenAPI document, endpoint documentation, or route definitions with sanitized request and response examples.
Open the API-analysis prompt and send it with those sources to any model. It asks for api-context.md, not speculative configuration based on a project name.
The resulting document should explain the first operation, each request field's type and location, authentication, response structure, documented errors, and where each value originates. User input, trusted server context, constants, and IDs obtained from another endpoint are different sources.
Review the document. Ask where a required field or constraint came from. One sample containing id does not prove that the field always exists or that another operation accepts it. Keep unknown details marked UNKNOWN until you resolve them.
You can also fill in the api-context.md template manually.
Save the reviewed document with your project, without secrets. You can give it to another model later without repeating this conversation. AGENTO does not load Markdown; this document helps you and your tools author the YAML.
3. Generate or write one tool, then understand it
Use the explanation below to write the configuration yourself. Alternatively, give a model your reviewed api-context.md, the configuration-generation prompt, and the portable AGENTO reference. It includes the core configuration chapters so a new model conversation has the required library context.
Ask for a complete file with one tool. Converting every endpoint at once makes it harder to identify why the first call fails.
If your API matches the public search contract above, the starting configuration is:
version: "2"
assistant:
name: Agento #Your agent's name
language: auto
timezone: UTC
system_prompt: |
Help users find and book appointments using the available tools.
Do not invent availability or claim a booking before it completes.
models:
routing:
provider: openai
model: gpt-5.6-luna
api_key: $ENV:OPENAI_API_KEY
temperature: 0
tools:
- id: search-services
tool:
description: Search available services by the user's search phrase.
input_schema:
type: object
properties:
query:
type: string
minLength: 1
required: [query]
request:
method: GET
url: https://YOUR_API_HOST/services
auth:
type: none
map:
query:
q: $.query
Replace the host, path, fields, and authentication with your actual contract before running it. YOUR_API_HOST is deliberately a placeholder.
Read the file from the outside in. version: "2" selects the AGENTO configuration format, not your API version. tools is a list of operations. Its first item has an internal identifier, search-services, which we will use in invoke(). The identifier need not match your backend route name.
The tool block describes the operation and its accepted inputs. description will help the model decide when to use it after conversation is enabled. It does not configure an HTTP request.
input_schema requires an object containing a non-empty string named query. This is the tool's input contract. We chose a readable name for it; the API still expects q.
request.method and request.url define the actual HTTP operation. auth.type: none is appropriate only for a public endpoint. Editing the tool description does not change that URL or method.
Mapping Tool Inputs to the API
request.map.query connects the tool inputs to the query parameters expected by the API.
q: $.query
This means:
qis the parameter name expected by the API.$.queryis the value taken from the tool inputs.
For example, if the tool input is:
{ "query": "hair" }
AGENTO will send:
GET /services?q=hair
In short: the left side is the API parameter name, and the right side is where its value comes from in the tool inputs.
We have not added a model, retries, or an output schema. First verify the real request. Then use the verified response contract to add response validation.
4. Configure Authentication
Authentication is defined per tool inside request.auth.
For a public endpoint:
auth:
type: none
No user token is required.
If the endpoint must run with the permissions of the current user:
auth:
type: session
In this case, the token is not stored in config.yml. Your application passes the current user's Access Token at runtime:
{
sessionId: `user:${user.id}`,
auth: {
token: user.accessToken,
}
}
These two values serve different purposes:
sessionId → identifies the user's AGENTO session
auth.token → authenticates that user with your API
user.id and user.accessToken come from your own application and authentication system. AGENTO does not log users in or generate Access Tokens.
For example, in a web application they may come from your authenticated request:
const user = req.user;
and then be passed to AGENTO:
const request = {
sessionId: `user:${user.id}`,
auth: {
token: user.accessToken,
},
};
Use a stable sessionId for the same conversation or user when you want AGENTO to keep the session context.
If the selected tool uses auth.type: none, you do not need to provide auth.token.
Service API Keys
Some APIs use a shared credential that belongs to your application rather than to an individual user.
For that case:
auth:
type: api-key
env: $ENV:SERVICE_KEY
header: X-API-Key
SERVICE_KEY is the name of the environment variable containing the credential. A $ENV: prefix indicates that AGENTO should read it from the environment file.
The distinction is simple:
session → dynamic credential for the current user
api-key → static credential for the application/service
none → no authentication
5. Send a Message to AGENTO
Create the Runtime once when your application starts:
import { AgentRuntime } from "agento-runtime";
const runtime = await AgentRuntime.create({
configPath: "./config.yml",
presentation: "raw",
});
Reuse that Runtime for incoming requests instead of creating a new one for every message.
Let AGENTO Choose the Tool
When an AI provider is configured, use chat() for normal Agent behavior:
const result = await runtime.chat({
sessionId: `user:${user.id}`,
auth: {
token: user.accessToken,
},
message: "Find hair services",
});
You only provide the user's message.
AGENTO handles the rest:
User Message
↓
Understand Request
↓
Select Tool
↓
Collect Inputs
↓
Execute API Request
You do not need to manually specify search-services.
If the selected tool uses:
auth:
type: session
AGENTO uses the auth.token supplied with the current request when calling your API.
For public tools, the same call can simply be:
const result = await runtime.chat({
sessionId: `user:${user.id}`,
message: "Find hair services",
});
Direct Tool Execution
Sometimes your application already knows exactly which tool should run. In that case, use invoke():
const result = await runtime.invoke({
sessionId: `user:${user.id}`,
auth: {
token: user.accessToken,
},
tool: "search-services",
arguments: {
query: "hair",
},
});
invoke() skips AI tool selection and executes the specified tool directly.
6. Interpret the result
For completed, inspect result.data and compare it with the direct API call using the same values. An empty list can be a valid success.
For needs_input, inspect missing and provide the required field. Remove query from the input file to observe this behavior: an incomplete search should not reach the API.
For error, inspect error.code and error.message. A missing argument differs from an invalid one: { "query": 15 } violates the string schema. AUTH_REJECTED calls for checking credentials, not renaming the argument.
If create() rejects before a result exists, fix the configuration-loading or validation error first. An invalid URL and a missing service-key environment variable are startup issues.
needs_selection and needs_confirmation require user interaction. This minimal read tool introduces neither. If you add those policies later, do not automatically select or confirm in the runner; follow the result-handling guide.
7. Continue from a verified integration
This quick start is complete when the tool sends the expected request to your API, you can explain where every value came from, and you understand the resulting status.
Continue with understanding config.yml, tool inputs, mapping, and responses. Then add a model to turn a user's message into a call to the same working tool.