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
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Kiota RequestInformation | A Kiota client, and a request its builders do not cover | A request built by hand, sent through the adapter so auth and middleware still apply | The path is in the document, where a builder already exists |
ogen typed operation methods | A Go tool layer over a document that names the operation | One method per operation, so an action is never folded onto an entity | You want entity objects rather than one method per path |
| Raw fetch inside the tool | A one-off call you will delete within days | Its own auth, no retry, no hooks, and nothing regenerated when the spec moves | Any tool that outlives the next key rotation |
| sdkgen direct and prepare escape hatches | The model has not caught up, and the tool must ship today | The client’s auth and retry, but no pipeline hooks and an untyped path string | You can correct the model in the same change |
| sdkgen guide action | The endpoint is a verb on an entity the model already has | A guide file to keep, and a $action key a caller has to know | The 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.
Related how-tos
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
-
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 undercreate, and$actionis what keeps the two apart. ↩︎ Back to text