# Agent-level action RAG

`@AgentSpec.knowledge()` and `@AgentSpec.retrieval()` are the annotation
counterparts of `AgentBuilder.addKnowledgeSource` and
`AgentBuilder.retrieval`. Both members are `@since 0.14.0` in TnsAI 0.14.0 (`TnsAI@c2bb5306`). They ship in Maven Central `0.14.1`.

They configure **action-level** RAG on the Agent class. They are not the
chat-turn corpus.

## Two corpora

| Declaration | Entry point | Corpus |
|---|---|---|
| Class-level `@KnowledgeSource` + `@ChatKnowledge` | Chat / stream | Chat-turn grounding |
| `@AgentSpec.knowledge()` + `@AgentSpec.retrieval()` | Action dispatch | Action-level `_rag_context` |
| Role- or method-level `@KnowledgeSource` / `@Retrieval` | Action dispatch | Same action-level path |

Empty `knowledge` is a no-op. An all-default `@Retrieval` is also a no-op, so
existing agents stay unchanged.

## Declarative

```java
@AgentSpec(
    description = "Answers from the product handbook",
    knowledge = {
        @KnowledgeSource(
            name = "handbook",
            type = KnowledgeSource.KnowledgeType.FILE,
            path = "knowledge/handbook")
    },
    retrieval = @Retrieval(
        strategy = Retrieval.Strategy.HYBRID,
        sources = "handbook",
        queryParam = "question",
        topK = 5)
)
public final class HandbookAgent extends Agent {
    @Override
    protected LLMClient getLLM() {
        return new AnthropicClient("claude-sonnet-4-20250514");
    }

    @Override
    protected List<Role> getRoles() {
        return List.of(/* action Role with a String query parameter */);
    }
}
```

`AgentSpecExtractor` reads those members during initialization:

- duplicate `KnowledgeSource.name()` values fail initialization
- `retrieval.topK < 0` fails initialization
- `Agent.getKnowledgeSources()` / `getRetrieval()` (`@since 0.13.0`) now
  default to that extractor in TnsAI 0.14.0

A builder that already added sources or set a `RetrievalConfig` wins.
`ConfigurableAgent` overrides the `Agent` defaults with the builder list.

## Not this page

- Role- or method-level `@Retrieval` walkthrough — still
  [RAG](index.md) and the declarative tutorial
- Chat-turn `@ChatKnowledge` — still the chat-level path on the RAG index
- Maven Central `0.14.1` — these members are in the published JARs