Most portfolio chatbots are a search box that answers in paragraphs. You ask
what someone has worked on, you get prose, and then you scroll to find it
yourself. The model knows the answer and the page it is sitting on stays
exactly where it was.
The one on this site can move the page. Ask to see incident work and it opens
the record filtered to incidents. Ask about a section and it scrolls there.
That is not a different model, it is the same tool-calling mechanism everyone
already has, pointed at the interface rather than at a knowledge base.
The key stays on the server, and that decides the architecture
The first real decision is not about the model. If the browser calls the model
provider directly, the API key is in the browser, and anybody who opens
devtools has your billing. Every "add AI to your site in five minutes" guide
that keeps the key client-side is teaching a mistake that only shows up on an
invoice.
So the request goes to a serverless function, which holds the key, attaches
the system instruction and the tool declarations, calls the model, and streams
the answer back. The client sends the conversation and nothing else. That
single constraint determines most of the rest of the design, and it is worth
accepting it up front rather than discovering it later.
It has a second effect that is easy to miss: because the system instruction is
assembled server-side, it can be changed without shipping a new bundle, and a
visitor cannot read it. The prompt is not secret, but it is also not something
to hand out with the JavaScript.
Five tools, and what they are for
Four of them do something to the page: search the work, open the record with
an optional category filter, scroll to a section, toggle the theme. One of
them, saveLead, records that a visitor wants to be contacted.
The declarations are the interesting part, because they are prompt
engineering wearing a schema. The description on openWork does not just say
what it does, it says when to reach for it and names the one argument value
that will not work. A tool whose description reads "opens the record" gets
called at the wrong moments; a tool that explains its own preconditions gets
called at the right ones. Most of the behaviour people attribute to the system
prompt is actually in the tool descriptions.
Retrieval that is deliberately not a vector database
Before the model answers, a retrieval step pulls the entries most relevant to
the question and puts them in the prompt. It is a substring matcher over the
record. There are no embeddings and no vector store.
For a few dozen entries with distinctive names, that is the correct
engineering. Embeddings would add an index to build, a service to depend on,
a rebuild step to forget, and a class of failure where the nearest neighbour
is confidently wrong. The substring matcher is inspectable, and when it
misses, it misses for a reason you can read.
What it does badly is fail silently. Rename a record or change the category
vocabulary and retrieval quietly returns less, and the bot gets vaguer rather
than erroring. Nothing in the response tells you this happened. That is
precisely why the retrieval layer has tests: not because the matching is
subtle, but because its failure mode is degradation rather than a stack trace,
and degradation does not page anyone.
The same reasoning covers the couplings between the bot and the site. The
categories in the tool declarations have to match the categories in the data,
and the section names it can scroll to have to match the sections that exist.
Both are asserted in tests, because the alternative is a chatbot confidently
offering to scroll somewhere that was renamed six commits ago.
The lead flow, and the gate before it
The tempting build fires saveLead the moment it has five fields. That
produces a form wearing a conversation, and it submits while the visitor is
still mid-thought.
Instead the model has to ask one closing question first, confirming there is
nothing else to add, and only then calls the tool. The reply that follows
carries a request ID, confirms where the transcript was sent, and gives an
address to follow up on with that ID, so the visitor leaves with a reference
rather than a hope.
That gate is one paragraph in the instruction and it is the difference between
a conversation that captures a lead and an interrogation that happens to be
written in sentences.
What I would keep
Tool calling for interface control rather than only for retrieval. The key on
the server, without exception. The smallest retrieval that works, with tests
around it precisely because it fails quietly. And a persona that positions the
work honestly: the site argues that AI is one tool inside systems work rather
than the identity, and a chatbot that oversold itself would contradict the
page it lives on.
Top comments (0)