# Build an agent app

Wire an agent loop, RAG grounding, and an MCP server into a working support assistant.

You will build a support assistant that answers from your docs (RAG), calls tools in an agent loop, and exposes your schema to coding agents over MCP. You need an `AI_API_KEY` for generation and embeddings; retrieval and MCP run locally. Run commands from the repository root.

## Resolve the backends

Every agent app starts from the container. `Agent()` builds a tool-calling loop over the shared `AI` backend, and `RAG()` builds a retrieval engine over `AI` plus `VectorStore`:

```sh
AI_ADAPTER=openai AI_API_KEY=sk-... zever doctor --json | head -5
```

## Index your docs

Ingest documents once, then retrieve top-K context per question. Chunking, batch embedding, and upserting are one call:

```sh
# Conceptually: engine.Ingest(ctx, docs) then engine.Answer(ctx, query, 5)
# See core/rag/rag.go and the RAG section of the AI guide.
```

## Run the loop with tools

Register domain tools, then run. Unknown tools fail closed, and handler errors return to the model as tool turns so it can self-correct:

```sh
# Conceptually: agent.New(client, agent.Options{Model: "gpt-4o", Tools: tools})
# then loop.Run(ctx, messages). See core/agent/agent.go.
```

## Stream progress and fan out

Long runs stream deltas, tool calls, and results as events. Independent tool calls in one step run concurrently with `MaxParallel`, and results keep their order:

```sh
# Conceptually: loop.RunStream(ctx, messages) then range over events.
# See core/agent/stream.go.
```

## Serve your API as agent tools

Compile the schema with the `mcp` backend. It writes one tool manifest per module (`generated/mcp/<module>/mcp.json`), a merged `generated/mcp/mcp.json`, and a runnable stdio server with handler stubs you fill in (`generated/mcp/<module>/mcpserver/main.go`):

```sh
zever compile schema/app.zen --backend=mcp --out ./generated
go run ./generated/mcp/<module>/mcpserver
```

Separately, `go run ./tools/zever-mcp` starts a stdio server that gives coding agents the compiler itself as tools (`zever_compile`, `zever_schema`, `zever_explain`).

## Score answers with evals

Pin quality with a dataset and scorers before you ship prompt changes:

```sh
# Conceptually: eval.RunSuite(ctx, run, cases, eval.ContainsScorer).
# See core/eval/eval.go.
```

## What you built

- `container.Agent()` and `container.RAG()` lazy accessors over shared backends
- `core/agent` loops: run, stream, parallel fan-out, sub-agent tools
- `core/rag` ingest, retrieve, hybrid retrieval, grounded answers
- `dsl/backend/mcp` manifests plus a generated stdio server, and `tools/zever-mcp` for compiler tools
- `core/eval` datasets and scorers

<details>
<summary>`Agent()` fails with an auth error</summary>

Cause: no API key, and the loop needs a real backend. Fix: set `AI_API_KEY`. Retrieval-only paths work with any embedder.
</details>

<details>
<summary>Hybrid retrieval returns nothing</summary>

Cause: hybrid engines index chunks into the keyword backend on ingest. Fix: re-ingest after switching from `rag.New` to `rag.NewHybrid`.
</details>

## Next steps

- [AI guide](https://zenta-dev.github.io/zever/guides/integrations/ai/): The LLM facade, loop, and RAG.
- [Agent skill](https://zenta-dev.github.io/zever/guides/extend/agent-skill/): The Claude Code skill.
- [Container](https://zenta-dev.github.io/zever/concepts/container/): Lazy resolution and close order.