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
Section titled “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:
AI_ADAPTER=openai AI_API_KEY=sk-... zever doctor --json | head -5Index your docs
Section titled “Index your docs”Ingest documents once, then retrieve top-K context per question. Chunking, batch embedding, and upserting are one call:
# 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
Section titled “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:
# 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
Section titled “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:
# Conceptually: loop.RunStream(ctx, messages) then range over events.# See core/agent/stream.go.Serve your API as agent tools
Section titled “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):
zever compile schema/app.zen --backend=mcp --out ./generatedgo run ./generated/mcp/<module>/mcpserverSeparately, 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
Section titled “Score answers with evals”Pin quality with a dataset and scorers before you ship prompt changes:
# Conceptually: eval.RunSuite(ctx, run, cases, eval.ContainsScorer).# See core/eval/eval.go.What you built
Section titled “What you built”container.Agent()andcontainer.RAG()lazy accessors over shared backendscore/agentloops: run, stream, parallel fan-out, sub-agent toolscore/ragingest, retrieve, hybrid retrieval, grounded answersdsl/backend/mcpmanifests plus a generated stdio server, andtools/zever-mcpfor compiler toolscore/evaldatasets and scorers
Agent() fails with an auth error
Cause: no API key, and the loop needs a real backend. Fix: set AI_API_KEY. Retrieval-only paths work with any embedder.
Hybrid retrieval returns nothing
Cause: hybrid engines index chunks into the keyword backend on ingest. Fix: re-ingest after switching from rag.New to rag.NewHybrid.