How-to › Use AI to do the integration

How to call a non-entity endpoint from a generated tool layer#

Reach a bulk action the generated client models badly from an agent tool, through its escape hatches or a corrected model, so that auth and retry stay in one place.

Audience
Agent builder
Level
advanced
Topic
Build an agent that calls APIs
Languages
TypeScript and Go
Verified

Your agent needs POST /books:archive, a bulk action, and the generated client offers ArchiveResult().create(), an entity named after the response. The tool’s author gives up and writes a fetch call with the bearer token pasted in. It works until the key rotates, and then every archive request answers 401 while every other tool keeps working.

What you get

You will end up with one agent tool, archive_books, reaching a bulk action four ways, and a test that shows which routes survive a 503 and a token rotation. This is for you if a generated client covers most of your API but not the call your agent needs.

Short answer

Fold the endpoint onto its entity in sdkgen’s guide file and call it through the generated method, so the tool gets the client’s auth, retry, and hooks. Until the model is corrected, call direct() on the same client, which keeps auth and retry but skips hooks. Use prepare() when you need your own fetch. Never give the tool its own copy of the token: it goes stale at the first rotation.

You will need

Node 22 or later, an sdkgen TypeScript SDK for your API, and an endpoint that does not fit list, load, create, update, or remove. Verified 2026-11-20 against Node 22.23.5. The document, api.json, is a Bookshelf API with bearer auth, four book operations, and one custom method in the colon form Google’s API design guide describes.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
Kiota RequestInformationA Kiota client, and a request its builders do not coverA request built by hand, sent through the adapter so auth and middleware still applyThe path is in the document, where a builder already exists
ogen typed operation methodsA Go tool layer over a document that names the operationOne method per operation, so an action is never folded onto an entityYou want entity objects rather than one method per path
Raw fetch inside the toolA one-off call you will delete within daysIts own auth, no retry, no hooks, and nothing regenerated when the spec movesAny tool that outlives the next key rotation
sdkgen direct and prepare escape hatchesThe model has not caught up, and the tool must ship todayThe client’s auth and retry, but no pipeline hooks and an untyped path stringYou can correct the model in the same change
sdkgen guide actionThe endpoint is a verb on an entity the model already hasA guide file to keep, and a $action key a caller has to knowThe endpoint belongs to no entity at all

Voxgig maintains sdkgen. It is the subject of this page, and its two rows say when to pick something else.

The raw fetch is the quickest to write and the first to break, because it owns a second copy of everything the client already does. Kiota and ogen generate a method for every path, so the problem shrinks to calling it. With sdkgen the fix is in the model, and direct() covers the gap until it lands.

See where the model put the bulk action

The model step classifies paths into entities. Given POST /books:archive alone, apidef 8.32.4 named an entity after the ArchiveResult response and gave it a create, with no action. Its guide reference says a custom method such as /schedules:count reads as its verb and becomes an action, which is not what this run did.

The response decided it. In a second run with the archive’s response typed as Book, the heuristic put the archive on book with $action: archive and no guide entry, as model/book.response-typed-book.aontu shows. When the document cannot change, correct the model instead. The guide entry file, .sdk/model/guide/guide.aontu, takes corrections, and regeneration never rewrites it:

# The heuristic named POST /books:archive after its response, as an entity
# called archive_result. Fold it onto book as an action instead.
guide: entity: archive_result: active: false
guide: entity: book: path: "/books:archive": { action: archive: {}, op: create: method: POST }

An action borrows one of the entity’s operation slots, here create, and a caller selects it with $action. Compare the two models:

node model.mjs
before: the heuristic, model/archive_result.before.aontu
  archive_result.create  POST   /books:archive
after: model/guide.aontu, then generate; read from generated/Config.js
  book.create            POST   /books
  book.create            POST   /books:archive  $action: archive
  book.list              GET    /books
  book.load              GET    /books/{bookId}
  book.remove            DELETE /books/{bookId}

After the correction, the archive is a second point of book.create. The SDK under generated/ was built from this corrected model with the retry feature on, as generate.sh records.1

Write the tool four ways

tools.mjs defines one tool, archive_books, with a schema that caps ids at 100, and four implementations. The app builds the client in one place, makeApp, with the token, the retry settings, and a PreRequest hook that tags each request with the tool’s name.

The corrected model is a method call:

export const viaModel = (app) => async (args) => {
  try {
    const book = await app.client.Book().create({ $action: 'archive', ids: checkIds(args) })
    return ok(book.data())
  } catch (err) {
    return fail(err.message)
  }
}

direct() takes a path, a method and a body, and goes through the same client. prepare() builds the same request, auth header included, and returns it unsent, so a tool can hand it to fetch. The fourth route is the one the problem statement describes, a fetch with the token it was given when the tool was built:

export const viaFetch = ({ base, token }) => async (args) => {
  try {
    const res = await fetch(`${base}/books:archive`, {
      method: 'POST',
      headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
      body: JSON.stringify({ ids: checkIds(args) }),
    })
    return res.ok ? ok(await res.json()) : fail(`HTTP ${res.status}`)
  } catch (err) {
    return fail(err.message)
  }
}

Break each route on purpose

demo.mjs calls the tool through each route against a stand-in on 127.0.0.1 in three situations. In the first nothing goes wrong. In the second the API answers 503 once. In the third the key rotates, the API accepts only the new one, and the app rebuilds its client.

node demo.mjs
route                   plain                 one 503               token rotated         app hook ran
Book().create $action   {"archived":2} (1)    {"archived":2} (2)    {"archived":2} (1)    yes
direct()                {"archived":2} (1)    {"archived":2} (2)    {"archived":2} (1)    no
prepare() + fetch       {"archived":2} (1)    HTTP 503 (1)          {"archived":2} (1)    no
fetch, copied token     {"archived":2} (1)    HTTP 503 (1)          HTTP 401 (1)          no
(n) = requests the API received

All four agree when nothing fails, which is why the raw fetch passes review. The retry feature wraps the transport, so direct() retried the 503 as the model route did. Only the model route ran the app’s hook, because direct() and prepare() skip the operation pipeline. The copied token is the only one refused after rotation: the other three read auth from the client the app rebuilt.

Call the archive from clients that model every path

Kiota builds one request builder per path, so this action arrived as client.booksArchive.post(body), with no model to correct:

     post(body: ArchiveRequest, requestConfiguration?: RequestConfiguration<object> | undefined) : Promise<ArchiveResult | undefined>;
    /**
     * Archive several books in one call
     * @param body The request body
     * @param requestConfiguration Configuration for the request such as headers, query parameters, and middleware options.
     * @returns {RequestInformation}
     */
     toPostRequestInformation(body: ArchiveRequest, requestConfiguration?: RequestConfiguration<object> | undefined) : RequestInformation;

Kiota’s escape hatch is for a path the document lacks. Its abstractions define a RequestInformation that the request adapter’s send methods accept. The adapter runs the authentication provider and the middleware, whose retry handler is on by default in TypeScript and acts on 429 and 503. Run once against the stand-in, the builder and a hand-built RequestInformation sent through adapter.send each retried a 503 and sent the rotated token, which is what direct() gives an sdkgen tool.

ogen generated a typed Go method for the operation, and the client asks its SecuritySource for the token on every call:

// ArchiveBooks invokes archiveBooks operation.
//
// Archive several books in one call.
//
// POST /books:archive
func (c *Client) ArchiveBooks(ctx context.Context, request *ArchiveRequest) (*ArchiveResult, error) {
	res, err := c.sendArchiveBooks(ctx, request)
	return res, err
}

A Go tool calls client.ArchiveBooks(ctx, req) and passes the tool’s context through. sendArchiveBooks also opens an OpenTelemetry span and counts the request, so a raw http.Client call beside it loses the token source and the telemetry. ogen was not run against the stand-in, so these points come from its generated code for this api.json.

Check it worked

Nine tests pin the table and the model. They check both heuristic models, that the archive sits on book.create, and that only the model route ran the hook. They assert which routes retried and that only the copied token got a 401. The last three check that the API saw the current token, and that bad ids and a misspelled action are refused before any request.

node --test tool.test.mjs
1..9
# tests 9
# suites 0
# pass 9
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 466.104139

When it goes wrong

Archive calls answer 401 after a deploy while every other tool works. The tool holds its own copy of the token, taken at startup, so the rotation never reached it. Build the request from the client with prepare() or direct(), so auth lives in one place.

The tool’s requests are missing a header the rest of the agent’s traffic carries. The tool calls direct(), and the header comes from a PreRequest hook, which direct() skips. Correct the model and call the generated method, or set the header in the direct() call itself.

create rejects with Operation "create" action "archiv" is not valid. A misspelled $action fails in the client, before any request. Keep the action name in one constant in the tool layer, not in each call.

When not to do this

Do not keep a raw fetch in a tool that outlives the week it was written. It costs a second copy of auth, retry, and every hook, which stay as written when the client changes.

Do not correct sdkgen’s model for an endpoint that belongs to no entity. A guide action needs an entity and an operation slot to ride in, so a service-wide report has nowhere sensible to go. Call it with direct() and say so in the tool’s description.

Do not choose sdkgen for an API that is mostly actions. Kiota or ogen give every path its own method, so there is no model to correct, and ogen passes the tool’s context.Context through to the request. Pick Kiota when the agent also needs clients in several languages from one document.

Last verified

Verified 2026-11-20 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, @voxgig/apidef 8.32.4, Kiota 1.38.0 and ogen v1.25.0. Every output block is what the command preceding it printed, against a stand-in on 127.0.0.1. sdkgen ran once in generate.sh, and its compiled SDK is committed under generated/. Kiota and ogen generated from the same document once, and the excerpts are their output. Kiota’s TypeScript client was run once against the stand-in, outside the gate, with @microsoft/kiota-bundle 1.0.0-preview.114. ogen’s client was not run.

Footnotes

  1. The colon form has a style guide of its own. Google’s AIP-136 gives a custom method as a verb after a colon, and its first example archives a book, posted to /v1/{name=publishers/*/books/*}:archive. It asks that the verb in the method’s name contain none of the standard verbs: Get, List, Create, Update or Delete. The corrected model files the archive under create, and $action is what keeps the two apart. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.