Introducing agent-ready schemas
No matter their smarts, agents will need information to do work. Among all the information made available to them, they’ll need to decide what to retrieve when, and how to do it. There is no reason to limit them to only submitting a list of keywords; they are capable of writing complex and precise queries to find the information they need.
GPT-6 Astra showing off its innate knowledge of Vespa’s query language
In short, instead of mimicking a casual Google user, they can search like experts. To do this, they need information about what’s available to them: What schemas exist, what fields do they have, and what ranking options are available.
Maintaining that separate from your Vespa schemas is tedious and error prone, so starting from Vespa 8.786.55, this is provided for you automatically.
Providing a skill for your agents
Vespa will automatically generate a set of skills explaining your schemas and expose it as /skills/v1/ on a container’s endpoint when you add the schemas skill below the container tag in services.xml:
<services>
<container>
<search/>
<skills><schemas/></skills>
</container>
…
</services>
Now all you need to do is add an instruction in the prompt to your agent that information about the search service it has available can be found at this path.
This skill is useful as-is, but it becomes even more effective when the content is explained: What data is contained in a schema and how might it be useful, what does each field contain, and what is each rank profile for. You can add this information in the schema as explanation blocks:
schema article {
explanation {
Scientific articles imported from pdf archives.
Individual fields will denote whether the article is peer
reviewed, when it was published, by whom and so on. Titles,
abstracts and full text are searchable
both lexically and as multi-vector representations,
see fields for details.
}
document {
field publish_date type long {
indexing: attribute
explanation: Published data as an epoch seconds timestamp.
}
…
}
rank-profile topical {
explanation {
Orders articles by broad relevance to the described concept,
emphasizing semantic matching while ranking exact lexical
matches higher.
@input query(embedding) the concept as a single embedding
@input query(freshness) the weight (0-1) to give to recency
among topical matches
}
…
}
}
These explanations will be added to the generated skills automatically, and kept up to date as your schema changes, read more in the agent-ready-schemas documentation.
With this information added, agents are much better equipped to formulate effective queries to meet their information needs, as we’ll see in the next section.
Evaluating the effect of agent-ready schemas
How well does the query-time schema skill help agents? Here we present results from evaluating this on one of our own evaluations built for testing agents with access to retrieval on retrieval-intensive tasks, as well as on the STaRK-amazon dataset from Stanford.
Evaluating on agent-discovery-lite-v1
This data set tests agents on tasks which require retrieval on a synthetic data set. The data set is kept small enough for it to be practical to hand-generate authoritative and unique correct answers on each task. This avoids the common problem with such evaluations, which is that there are many potential responses to tasks given the data, and the ones marked as correct are typically found by some naive search process, which biases towards replicating the same uniform retrieval strategy. The limited size also makes it affordable and fast to use this data set for experimentation.
The data set uses the product discovery domain and contains items of the types product, brands, and stores and consists of 2039 documents and 196 tasks and task variants. It is available for download here.
One-shot queries
One-shot querying was used to see how the skill affects writing a correct Vespa query in a single attempt. The model is given a task, the schemas skill (when applicable), and writes one query. It sees no data, gets no error messages, and has no second try. We run the query and compare its results with the correct answer.
A typical task can be:
Which stores opened before 1 January 2015? List their names.
There are 20 task templates, each asked in 3 wordings with 3 sets of parameters. This gives a total of 180 tasks, each run twice for three arms:
- A, no skill: the schema and field names only.
- B, skill without explanations: the structure the skill generates from the schemas, such as field types, rank profiles and how each field can be queried.
- C, full skill: the same structure, plus the explanations the application’s authors wrote into the schema.

Without the skill, the model gets almost nothing right on these tasks. It has to guess how fields are queried, and it can’t know conventions such as millisecond timestamps. Getting access to the schema structure is sufficient to get a reasonable success rate, while tasks that depend on knowledge of the data need the explanations: On such tasks the skill without explanations gets 9% right and the full skill 93%. Without the explanations, the model searches for “Norway” where the data says “NO”, compares millisecond timestamps with seconds, and adds VAT to prices that already include it.
Details: Claude Sonnet 5.5, 1,080 runs. Half the templates were held out while the skill and its explanations were written; the skill does as well on those as on the rest.
Agent queries
We also evaluate by allowing an agent to keep querying the application until it is satisfied. Each agent runs in its own container with the usual tools (shell, files, web search). It can read from the application only through its query and document APIs, and it can’t see the schemas, data files or answers. With the skill (B and C), the agent is told where to fetch it. We use the same 20 task templates and three arms as in the one-shot runs, with 60 tasks per arm.
Agents can do what one-shot models can’t: Run queries and learn from what comes back. An agent that sees “NO” in the brand documents, or 13-digit timestamps, can work out the convention itself. In other cases, the data itself cannot resolve ambiguity, such as whether prices include VAT.

The skill improves performance while cutting cost. While using multiple turns often allows agents to eventually discover the information they need, the skill reduces cost by avoiding this trial and error: When given the full schema skill, the agent ran a quarter of the queries, used 30% less model time and 40% fewer tokens while achieving better correctness.
Evaluating on STaRK-Amazon
We also evaluate the impact of the skill on a more traditional retrieval problem set, STaRK-Amazon. This focuses on providing product recommendations from 1M semi-structured products. The problems are posed in a conversational style, for example:
I've bought some women's weightlifting gloves for myself from Harbringer, and I love them. Can you find me similar gloves for my husband?
Each such problem comes with one or more correct results. The challenge with this data set, is that many problems have a large number of similarly correct answers, but only some of them are graded as correct. This compresses the range of difference you can observe for any improvement, but we can still see a large effect of using the schema skill:

Baseline here is a hybrid (vector and text) search of the full text of the task. No skill is using an agent to solve the task without giving it the skill, and Skill is using the same agent with access to the skill.
Details: Evaluated on the STaRK-Amazon Human-Generated problem set, using Claude Sonnet 5.5. Numbers are averaged over three runs.
MRR measures relevance by how high in the list of recommended products the first expected answer is found. The skill increases relevance by 12% while reducing token cost by 68%. An agent without the skill can figure out much of the missing information from examining search results, but this has a substantial additional cost.
Conclusion and future work
Agents are capable of searching like experts, and this produces better outcomes at reduced cost, in both tokens and queries. With Vespa, you can now easily provide this information for agents in your application by enabling the schemas skill and pointing them to the /skills/v1 endpoint. By generating this automatically from schemas we save the manual work of keeping an external skill up to date. On the platform side we’ll keep the skill up to date with relevant information about features as we add them to the platform.
Schemas often contain values with a limited cardinality such as categories or map keys for structured attributes which would be useful to enumerate for agents. Our next step will be to allow explanations to incorporate information which can be resolved by issuing cacheable queries at runtime, such as “list all the custom attributes for the current tenant”.