Mapping with an AI agent

An agent is an assistant you ask, in plain language, to map part of your project. It runs in an open-source chat client — LibreChat, in a tab beside Linkr, or OpenCode — and acts on Linkr through the MCP server, with your personal API key and therefore your rights. It works on the project itself: no export, no file to re-import.

What you need

• An install with a backend, and Linkr’s MCP server started by the administrator — see MCP server.
• Your API key, created in Linkr and pasted into the chat client.
• The concept-mapping skill, installed in the client — see Skills.
• OMOP vocabularies for the project — see Target Concepts. Without them, the agent cannot search for any target, and tells you so.
• A model allowed to see the data — see the box further down.

How it goes

1. You ask, for example: “Map the unmapped Blood Gas concepts of the MIMIC-IV Demo mapping project.”
2. The agent locates the project — how many concepts are mapped, which vocabularies are available — then asks its questions once for the session: should it leave suggestions (the default) or create mappings; which scope to cover — a category, the most frequent ones, specific codes; how many candidates per concept.
3. It works in batches of about ten concepts. For each, it reads the source concept and its metadata, searches the OMOP vocabulary, examines the finalists, then writes its proposals.
4. After each batch, it sums up what it wrote, what it left out and why, and how many remain. You decide whether to continue, change scope or stop.

A code whose label and metadata say nothing interpretable — a lone letter, an anonymised code — is not mapped: the agent lists it in its summary.

What the agent writes into the project

• AI suggestions, by default. Each carries a target, a score, a SKOS equivalence and a mandatory comment justifying the choice. They join the project’s scores file under the method ai/<model>, and show in the Suggestions tab in the Agentic category.
• Mappings, only if you asked for them, and only for the choices you confirmed one by one in the conversation. They are created with the Unchecked status, so they go through evaluation like any other.

Linkr checks what the agent writes: an unknown source code, a missing, invalid or non-standard target, a missing comment or a non-SKOS equivalence gets the whole batch refused. Nothing is ever overwritten — neither a suggestion nor an existing mapping.

Following its work in Linkr

Linkr updates while the agent works. Each batch is also recorded in the Notifications bell, at the top of the screen: “12 AI suggestions added”, or “3 mappings added”, marked Added by MCP.

The notification’s Show details button opens a table of the batch, one row per proposal: Source concept, Code, Target concept, Concept id, Equivalence, Score, Status (for mappings) and Comment. You can read the agent’s reasoning without leaving the current screen. The Open the Mapping Editor tab button — or Open the Mappings tab, for mappings — takes you to the project.

In the editor, the source concept table’s Has a suggestion from filter, set to Agentic, keeps only the concepts the agent has left something on.

Removing suggestions

If a batch is wrong, ask the agent to withdraw it: it can remove its suggestions, all of them or those of a few concepts, then start again. You can also do it yourself: Manage suggestions → Methods in the file, bin next to the ai/<model> method (see The combined score).

Mapping onto a data dictionary

If you ask it to, the agent maps onto a data dictionary first — the concept sets imported into the workspace, such as the INDICATE Data Dictionary — and falls back to the full OMOP vocabulary only when no concept set fits. It takes its targets from each set’s resolved concepts, and follows the Mapping Notes in its description: the default target, the rules by specimen or method, the excluded concepts.

It offers two directions:

• Source-first (default) — it goes through your codes and finds the best target for each. Every one of your codes gets looked at.
• Dictionary-first — it goes through the concept sets, category by category, and gathers for each one all the source concepts that belong to it. Every concept set gets filled in turn, and you know which ones are still empty.

Suggestions taken from a concept set keep the link to that set — the panel’s Concept Set column — and count in the Data dictionary category.

The concept-mapping skill

A skill is a procedure written in plain language that the agent reads and applies. This one, shipped with Linkr, gives it the mapping method — it is what makes any model work in the same rigorous way from one session to the next. Its main rules:

• Read the metadata of each code before choosing — unit, value distribution, wards, measurement frequency. That is what separates two close targets: a distribution that does not fit the target is a strong sign of error, even with a very similar label.
• Be strict on equivalence: exactMatch only when nothing is lost; closeMatch by default as soon as a qualifier differs — specimen, method, site, timing.
• Justify every proposal with a comment written for the reviewer, in your language, in one or two full sentences, citing what decided and saying precisely what is lost for any inexact equivalence.
• Never invent a concept id: every target comes from a vocabulary search, a suggestion or a concept set, and must be standard and valid.
• Never validate on your behalf: without your explicit agreement, concept by concept, the agent leaves suggestions, not mappings.

The skill follows the open Agent Skills format: it works with any model, in any client that reads that format. It lives in the Linkr repository, under packages/linkr-mcp/skills/concept-mapping/; the Skills page explains how to install it in LibreChat or OpenCode.

Going further

• Suggestions — the tab where the agent’s proposals land, and the precomputed scores.
• Agents — what an agent can do in Linkr, and how you stay in control.
• MCP server — create your API key and connect LibreChat or OpenCode.
• Evaluation — review and validate mappings, including those created by an agent.