# 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.

Source: https://voxgig.com/howto/call-a-non-entity-endpoint-from-a-tool

- Audience: agent-builder
- Level: advanced
- Languages: typescript, go
- Verified: 2026-11-20
- Published: 2026-11-20

## 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](https://google.aip.dev/136) describes.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Kiota RequestInformation](https://learn.microsoft.com/en-us/openapi/kiota/abstractions) | 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](https://ogen.dev/docs/examples/) | 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](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch) | 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](https://github.com/voxgig/sdkgen/blob/main/docs/explanation/operation-pipeline.md) | 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](https://github.com/voxgig/apidef/blob/main/docs/reference/guide.md) | 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](https://github.com/voxgig/apidef/blob/main/docs/reference/guide.md) 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:

```aontu title="model/guide.aontu"
# 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:

```bash
node model.mjs
```

```text output
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:

```ts title="tools.mjs"
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:

```ts title="tools.mjs"
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.

```bash
node demo.mjs
```

```text output
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:

```ts title="other/kiota-ts/booksArchive.ts"
     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](https://learn.microsoft.com/en-us/openapi/kiota/abstractions) define a
`RequestInformation` that the request adapter's send methods accept. The adapter runs the
[authentication provider](https://learn.microsoft.com/en-us/openapi/kiota/authentication) and
the [middleware](https://learn.microsoft.com/en-us/openapi/kiota/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:

```go title="other/ogen/oas_client_gen.go"
// 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.

```bash
node --test tool.test.mjs
```

```text output
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

- [Choose between calling an SDK directly and using MCP](/howto/direct-sdk-calls-versus-mcp-in-an-agent)

- [Build a tool-calling loop with the Claude Agent SDK](/howto/tool-calling-loop-with-the-claude-agent-sdk)

- [Generate your first SDK with sdkgen](/howto/first-sdk-with-sdkgen)

- [Rename a generated SDK method without editing the output](/howto/rename-generated-methods-without-editing-output)

- [Call an endpoint your SDK does not model with direct()](/howto/call-an-unmodelled-endpoint-with-direct)

## 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.

[^1]: The colon form has a style guide of its own. Google's [AIP-136](https://google.aip.dev/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.