Agent troubleshooting

Fix discovery, route, model, and Chat handoff issues.

Use this page when an agent cannot be discovered or called.

Unknown agent

Cause: the generated registry does not contain the requested name.

Fix: check the file path.

server/agents/triager.ts -> triager
server/agents/support/reviewer.ts -> support/reviewer
server/agents/docs/config.ts -> docs

Cause: routes are disabled by default.

Fix: enable route.

nitro.config.ts

export default defineNitroConfig({
  modules: ['@vitehub/agent/nitro'],
  agent: { route: true },
})

Error:

[vitehub] Agent model is required unless the agent defines a custom run() handler.

Fix: pass model, or define run.

export default defineAgent({
  async run() {
    return { text: 'ok' }
  },
})

Cause: a chat definition uses both agent and onDirectMessage.

Fix: choose one owner. Use agent for the default handoff, or write onDirectMessage when you want to own the full flow.

Cause: the app uses @vitehub/agent/cloudflare without Cloudflare's agents runtime package.

Fix: install the Cloudflare package in the app that calls the native router.