Articles/Agents

Knowledge is the new code for tailored experiences

In AI experiences, what each person sees and what application agents do for them is shaped by role-based knowledge, not just the code around it. Iterate on the experience. Build on a governed knowledge core that tailors it to every role.

Juan J. Perez · Sharely.ai·October 24, 2026·9 min read

In short

Your users deserve an experience built for them: their role, their task, the moment they're in. You get there by iterating, and more and more of that iteration will be done by coding agents.
In AI experiences, knowledge is the new code. Role-based knowledge decides what each person sees and what application agents may do for them, so it needs the rigor code gets: structure, permissions, governance, and consistency with the source.
So the widget and the agent Server SDK are open source, for iterating on the experience, and the governed knowledge core underneath is what tailors it to every role.

Your users deserve an experience built for them

Not a generic one. An experience built for their role, their task and the moment they're in. A technician on a service call needs something different from an operations lead reviewing the week, even when the knowledge behind both is the same.

You won't get that right the first time. Nobody does. You get there by iterating: watching how people use it, changing it, and changing it again, week after week. And that only works if the knowledge underneath is solid.

In the last article, I argued that the experience of the future is being decided now, and that it should stay yours. This one is about how you build it. The short answer: knowledge is the new code.

The experience
Yours · on the open-source widget
How people reach knowledge inside your application.
- Agentic chat
- Search
- Navigation
Tailor it to each person, and keep iterating.
The application agents
Yours · on the open-source Server SDK
The work done for your users, on their behalf.
- Any framework
- Your tools
- Any container
- Coordinated by Temporal
Run them anywhere.
The knowledge core
Managed · Sharely platform
Role-based knowledge that tailors the experience to each person.
- Ingestion
- Index
- Navigation
- Cross-references
- Languages
- Roles
- Authorization
- Governance
- Sync
The new code: governed, consistent with the source.

The experience is where you iterate: how agentic chat, search, and navigation look and behave in your application. The knowledge core is what tailors it: roles, permissions, navigation and languages decide what each person actually gets. Iterate on the first. Build the second the way you build code.

Agentic chat, search, and navigation, tailored to each person

People reach knowledge in three ways. They ask, which is chat. They look, which is search. They wander, which is navigation: moving through a structure until they find what they need. With application agents behind them, all three can do real work, not just return results.

Every application will want all three, and none will want them to look the same. A member portal wants them in its sidebar. A field-service app wants the procedure inside the work order, not in a chat window. A SaaS product wants them in its own design system. And each will keep changing them as it learns what its people need.

One source

Governed knowledge

Infusion pump preventive maintenance

Rev. D
English · Spanish
Technicians only
Equipment › Infusion

Rendered as

An answer, grounded in the procedure, with the source cited.

What's the PM procedure for the infusion pump in bay 3?

Run the four checks in order: occlusion pressure, flow-rate accuracy, alarm test, then battery hold. Log each reading in the work order before you close it.

Infusion pump preventive maintenance · Rev. D

Illustrative example, after the PrecisionCare sample app.

That is why our widget, WebControl, is open source under Apache 2.0. It is a starting point, not a destination. Two script tags give you agentic chat, search, and navigation, governed by your roles. Then it gets out of the way, as far as you want to take it, as often as you want to change it.

1
Drop it in
Two script tags. Agentic chat, search, and navigation appear in your application, governed by your roles.
```
window.sharelyai.initialize({
  workspaceId, baseUrl,
});
window.sharelyai.render();
```
2
Make it yours
Override the theme, choose which views each role sees, and set where it appears.
```
initialize({
  workspaceId,
  theme: { colors: { … } },
  displayMode: { … },
});
```

Go headless

Keep the data layer, drop our UI. The hooks give you threads, sources and categories.

const { messages, sendMessage,
  activeSources } = useSharelyChat();
const cats = useKnowledgeCategories();

4
Fork it
It's Apache 2.0. Change anything, render it anywhere, ship it as your own.
```
git clone github.com/sharelyai/widget
# your components, your flow
```

Every rung is something a coding agent can do for you, because the code is open.

Two kinds of agents

When people say agents, they usually mean one of two very different things. This article depends on both, so it helps to keep them apart.

Coding agents

Write the experience

Works for: Your team
What it changes: The code of the experience
When: At build time, every iteration
Built on: The open-source widget
Governed by: Your code review

“Show search results as cards in our design system.” Done in an afternoon, reviewed, shipped.

Application agents

Work for your users

Works for: Your users
What it changes: What a person sees and gets done
When: At run time, in every session
Built on: The open-source Server SDK
Governed by: The knowledge core, as the user's role

“What's the PM procedure for this pump?” Answered for a technician, from what technicians may see.

Coding agents are how your team iterates on the experience. Point one at the widget and ask for search results in your design system, and it is done in an afternoon, because the code is there to read and change. A closed widget cannot be iterated that way. An open one, under Apache 2.0, can.

Application agents are how your users get work done. They decide in the moment what a person should see, an answer, a checklist, a form already filled in, and they act on that person's behalf. You build them on the Server SDK, and everything they know and may do comes from the governed knowledge core.

Coding agents change the experience. Application agents work inside it. Both get better when the knowledge underneath is right.

Knowledge is the new code

In an application without AI, code decides what each person sees and what they can do. In an AI experience, much of that is decided by knowledge. Which procedure a technician gets. Which answer a guest gets. What an application agent is allowed to do, and on whose behalf. Change the knowledge, and the experience changes for every role that depends on it.

That is what makes the experience tailored. It is also why the knowledge needs the rigor we give code: structure, versions, permissions, review, and a single source of truth.

It is tempting to think the hard part is the index. It isn't. Creating an index is close to trivial now; a coding agent will write you one before lunch. The hard part is everything that has to stay true around it:

a navigation structure people can actually browse,
cross-references between documents,
every language you serve,
every role, so each person sees only what they are permitted to see,
and all of it consistent with the source of truth, every time the source changes.

Each of those is manageable on its own. Together, they multiply.

1edit×3surfaces×4roles×2languages=24places it must be right

Role · language	Search index	Navigation	Agent answers
Technician · English	Rev. C	Rev. C	Rev. C
Technician · Spanish	Rev. C	Rev. C	Rev. C
Clinical specialist · English	Rev. C	Rev. C	Rev. C
Clinical specialist · Spanish	Rev. C	Rev. C	Rev. C
Operations · English	Rev. C	Rev. C	Rev. C
Operations · Spanish	Rev. C	Rev. C	Rev. C
Guest · English	Hidden	Hidden	Hidden
Guest · Spanish	Hidden	Hidden	Hidden

Every place shows Rev. C today. Guests may not see this procedure at all.

Illustrative. Now multiply by every document, and every edit, every day.

At small scale you can catch these by hand. At the scale of a real organization, with thousands of documents and edits every day, drift is silent. Nothing errors. A technician reads last quarter's procedure. A guest sees a document meant for staff. And the application agent, which answers from all of it, repeats the mistake with confidence.

It can be done right. We have spent years on it, and some of you will eventually build your own. But it should not be the first thing you build, and it is not the thing that makes your application different.

Vibe code the experience. Govern the knowledge like code.

Application agents should run anywhere

Behind the chat window, an application agent does work: model calls and tool calls, sometimes many of them. That work should run in containers, and those containers should be able to run anywhere: in your cloud, near your data, in the region your people are in, or in ours.

Running anywhere raises a new problem. Containers fail, scale and move. A turn that half-finished in one place has to finish in another without repeating what it already did. That is what Temporal is for. The Server SDK has a Temporal adapter that runs each chat turn as a durable workflow, with every model call and tool call as its own step. Temporal decides where each step runs, and makes sure it runs to completion.

One chat turn, durable

A container fails. The answer still arrives.

Your application
A technician asks a question
“What's the PM procedure for the pump in bay 3?”
Temporal
One workflow for this turn
Every step from here is recorded.
Agent containers
Container A · your cloud
Model call
Plans the answer.
Sharely
search_knowledge
Runs as the technician's role. Only permitted documents come back.
Agent containers
Container A
✕ Container lost
Mid-step, mid-answer.
Temporal
Retries that one step
On another worker. The search is not run again; its result comes from history.
Agent containers
Container B · another region
Model call, again
Picks up where the turn left off.
Sharely
get_knowledge_item
The full procedure, Rev. D, in Spanish.
Your application
The answer streams back
Content, sources, done. The technician never noticed.
Temporal
Where this is going
Wait for a person
Pause for hours or days for an approval, then carry on.

Illustrative. The last step shows where the SDK is headed, not what ships today.

The same machinery is what will let application agents take on longer work: running in the background for hours, or waiting days for a person's approval before they act. That is where we are taking it.

The contract is open, and it is Vercel's

The Server SDK is how you bring your own application agents to Sharely. An application agent is one function that returns a stream of events. Build it with the Vercel AI SDK, with LangGraph or with your own code. The SDK handles identity: it exchanges your workspace key for a token scoped to the person's role, so every governed tool your application agent calls runs as that person and returns only what they may see.

Between your application agent and the screen, we did not invent a new wire format. The widget speaks Vercel's AI SDK UI Message Stream protocol: server-sent events with typed parts for text, reasoning, tool calls, sources and custom data. It renders them with the AI SDK's own useChat hook.

The contract

Your application agent yields events. The widget renders them.

Your application agent's eventsAI SDK part

event: message_start→ start
event: thinking_start→ reasoning-start
event: thinking_delta→ reasoning-delta"Find the PM procedure for this pump…"
event: thinking_end→ reasoning-end
event: tool_call_start→ tool-input-available{ name: "search_knowledge" }
event: tool_call_end→ tool-output-available{ results: 3 }
event: content_delta→ text-start, text-delta"Run the four checks in order:"
event: content_delta→ text-delta" occlusion pressure, flow rate, …"
event: sources→ source-document[{ title: "Infusion pump PM", rev: "D" }]
event: message_end→ finish{ finishReason: "stop" }
event: done→ end of stream

What the widget draws

What's the PM procedure for the pump in bay 3?

Thought for a moment

search_knowledge3 results

Run the four checks in order: occlusion pressure, flow rate, alarm test, battery hold.

Infusion pump preventive maintenance · Rev. D

Left, events from the Server SDK protocol. Right, the part of Vercel's AI SDK UI Message Stream protocol each one becomes in the widget, which renders them with the AI SDK's useChat.

That choice matters more than it looks.

Application agents built with the AI SDK drop in. The Server SDK's Vercel adapter wraps a streamText call as a Sharely application agent, with the same tools and models you already use.
You are not locked into our interface. The AI SDK's hooks run in React, Vue, Svelte and Angular, and component libraries like AI Elements build on the same protocol. A different front end is a change of components, not a new integration.
It is documented, and it is not ours. A protocol that many teams build on outlives any one vendor, including us. That is the point of open edges.
It already describes where application agents are going. The protocol has parts for custom data, which is how application agents will render richer interfaces, and for tool approval requests, which is how they will ask a person before they act.

Put together, the pieces look like this.

Yours

Your application

Your portal, site or product. Your code, your login.

The widget

Open source

@sharelyai/widget-*

Agentic chat
Search
Navigation

Or your own UI on its headless hooks.

Your login stays the source of truth. The widget gets a signed token for this user and role.

Managed

Sharely platform

Identity and roles, threads, routing, and governed tools.

search_knowledge
semantic_search
get_knowledge_item
list_taxonomies
get_taxonomy_knowledge

Every tool runs as the calling user's role.

Yours

Your application agents

Each one a handler that returns a stream of events, with your prompts and tools, running on your agent server.

Vercel AI SDK
LangGraph
Your own code
Your tools

The Server SDK

Open source

@sharelyai/server

Identity, streaming, governed tools, and adapters for the AI SDK and Temporal.

In containers, anywhere. Each turn coordinated by Temporal.

The knowledge core

Managed · the new code

Fed from your sources of truth: your sites, your documents, your systems of record.

Ingestion
Index
Navigation
Cross-references
Multi-language
Multi-role
Authorization
Governance
Sync with the source

Because the contracts are open, the pieces are interchangeable. Any application agent that speaks the protocol can sit behind the widget. Any interface that reads it can sit in front of the application agent. The governed core stays the same underneath both.

Start with the open pieces

Everything at the edges is public, under Apache 2.0.

Apache 2.0

The widget

WebControl: agentic chat, search, and navigation, as one embeddable bundle or as layered React packages with headless hooks.

@sharelyai/widget-services
@sharelyai/widget-ui-chat
@sharelyai/widget-ui-search
@sharelyai/widget-ui-browse

sharelyai/widget

Apache 2.0

The Server SDK

Bring your own application agents. One handler, a stream of events, governed tools that run as the user's role, and adapters for the Vercel AI SDK and Temporal.

@sharelyai/server
@sharelyai/adapter-vercel-ai
@sharelyai/adapter-temporal
@sharelyai/protocol

sharelyai/sharely-server-sdk

Apache 2.0

The sample app

PrecisionCare: one portal, four roles, and a role-aware assistant over governed content, with the widget embedded.

Next.js reference app
One-command onboarding

sharelyai/precisioncare-sample

Knowledge is the new code. Iterate on the experience, and govern the knowledge that tailors it.

References

Stream Protocols · Vercel AI SDK documentationThe UI Message Stream protocol: server-sent events with typed parts for text, reasoning, tools, sources and custom data.
AI SDK UI overview · Vercel AI SDK documentationuseChat and the other hooks, across React, Vue, Svelte and Angular.
AI Elements · VercelA component library for AI interfaces, built on shadcn/ui and the AI SDK.
Temporal documentation · TemporalDurable execution: workflows, activities, retries and signals.
sharelyai/widget · GitHub · Apache 2.0WebControl, including the adapter that speaks the AI SDK UI Message Stream protocol.
sharelyai/sharely-server-sdk · GitHub · Apache 2.0The Server SDK, with its Vercel AI SDK and Temporal adapters.

Building on the open pieces?

Tell us what you are building and who it serves. Or pick a time and walk us through it.

Schedule time with us