Recording a nanobot session and replaying it offline — plus two config gotchas

[xizhuomengcontin]

I record agent runs for a living (I maintain OrcaReplay, Apache-2.0), so I spent this evening finding out whether nanobot can be captured and replayed. It can — but not the way it works for most frameworks, and the reason is specific enough to nanobot that it seemed worth writing down here rather than in my own docs.

The finding: nanobot pins its origin in config, so environment variables do not reach it

Most Python agent frameworks end up at AsyncOpenAI() with no arguments, which reads OPENAI_BASE_URL from the environment. That makes out-of-process capture trivial: launch the agent with that variable pointed at a local proxy and you are done.

nanobot does not do that. In providers/openai_compat_provider.py the client is built as:

self._client = AsyncOpenAI(
    api_key=self._api_key_for_client,
    base_url=self._effective_base,
    ...
)

and _effective_base comes from the provider spec in config.json. OPENAI_BASE_URL appears nowhere in the package — I grepped. So the usual trick is a no-op here, which is a reasonable design (explicit config beats ambient environment) but means a recorder has to meet nanobot where it actually looks.

The answer is to give nanobot a provider that points at the recorder, which your providers.custom slot already supports.

What actually worked

1. Start a recording proxy that nanobot can be pointed at.

orca attach --for exec
# info attached run=run_bb6a05db3d7a proxy=http://127.0.0.1:53581

2. Point a custom provider at it.

{
  "providers": {
    "custom": {
      "api_key": "your-real-key",
      "api_base": "http://127.0.0.1:53581/v1"
    }
  },
  "agents": {
    "defaults": {
      "model": "custom/your-model",
      "provider": "custom"
    }
  }
}

3. Run nanobot normally. Your key is unchanged — the proxy forwards it upstream.

nanobot agent -m "Say hello in three words." -c ./nb-config.json
# 🐈 nanobot
# the stub answered

4. Replay it with the provider gone.

orca attach --replay run_bb6a05db3d7a
# info attached ... serving=run_bb6a05db3d7a exchanges=1 egress=blocked

Repoint api_base at the new port, run the same command, and nanobot produces the same answer with the upstream process killed — I verified that by terminating the origin first, then running nanobot again and watching it still answer. No provider is contacted and no tokens are spent; nanobot's own loop, tools and session handling run for real.

Being precise about the evidence: I stopped the replay proxy with a process kill rather than ctrl-C, so I do not have its closing verdict line — what I can state is that the origin was dead and the recorded answer still came back.

Two config gotchas that cost me ten minutes

Both are pydantic validation errors that are clear once you read them, but neither is obvious from the outside:

• api_type accepts only auto / chat_completions / responses — "openai" is rejected.
• More surprising: api_type is only accepted under providers.openai. Setting it on providers.custom fails with "providers.<name>.api_type is only supported for providers.openai", even though custom has the field in its schema. Leaving it unset works fine and auto does the right thing.

If that restriction is deliberate, it might be worth dropping the field from the non-openai provider models so the schema stops advertising something it rejects. Happy to open an issue if that is useful rather than known.

Why anyone would want this

A recorded run is a session you can hand to someone else. A nanobot bug that only shows up on the fourth tool iteration becomes something a maintainer can reproduce without your API key and without spending anything, and the same recording works as a regression test in CI.

Two limits I would rather state than have someone discover:

• egress=blocked means model-provider egress, not network isolation. Replay stops the model call, but nanobot's own tools still run for real — a web tool that fetched a URL fetches it again. It is not a sandbox.
• A matching replay is not a determinism result. The model is not re-asked; its recorded answers are served back. Whether a fresh run behaves the same way is a different question.

Tested against nanobot-ai 0.3.0 on Python 3.12, with a deterministic local origin standing in for a provider.