Teaching

A teach is a request plus the answer it should get. Your organization’s model learns from it in the background and keeps answering while it does.

You teach from inside a conversation. Tell your assistant what A8 got wrong, and it calls the teach tool on A8’s MCP server. Approving that call records the teach.

§1What a teach is

The request is the one you send to judge, and the answer is the verdict it should get:

A correction is a teach of a request you already sent, with the answer you wanted. Your assistant sends the same input and format it judged, and the answer you named:

{
  "input": [
    {"role": "system", "content": "Which queue does the ticket belong in?"},
    {"role": "user", "content": "It arrived crushed. I want a refund."}
  ],
  "format": {
    "properties": {"queue": {"enum": ["billing", "shipping", "account"]}}
  },
  "answer": {"queue": "billing"}
}

The result says when the teach was recorded and whether it replaced an earlier answer:

{"recorded_at": "2026-10-22T14:03:11Z", "replaced": false}

Teaching needs the models:train permission. See API keys.

§1.1Two ways to teach

• Name the answer. A8 records it when you approve the call.
• Say what you want learned, in your own words. For example, “double-charge tickets go to billing, even when the order came late”. A8 proposes the request and the answer it would record. A8 records it when you agree and your assistant teaches the proposal.

§1.2One criterion per teach

A teach covers one criterion. When a schema’s properties carry criteria of their own, teach each criterion in a request of its own. See Check one subject against several criteria.

§2The same request, a new answer

A request is the same when its input and format match exactly as JSON: the same strings and values, whatever the key order. Teaching it again with a different answer replaces the old answer, and the result says replaced: true.

A follow-up is taught with the whole conversation as its input, A8’s earlier responses included. The answer is the verdict the latest user message should get.

A request phrased differently is a separate example, and both count. Each request replaces its own answer alone.

§3When a teach lands

A teach is recorded the moment you approve it. A fit follows once your organization has been quiet for about a minute, so a hundred teaches in a row become one fit. Until the fit completes, a8 answers from the version it already serves.

Each fit produces a version named by a horizon, a timestamp. A version whose horizon is at or after a teach’s recorded_at includes that teach. Every response names the version that answered in model, so any verdict tells you whether your latest teaching is in it.

§4Retracting

retract removes an example taught by mistake, such as a throwaway fixture or a wrong paste. It takes the request alone, its input and format, and the next version is fitted from the examples that remain. The result says whether the request had a taught answer to remove:

{"retracted": true}

To correct an answer, teach the same request with the right one. Retract an example that should leave the model.

§5Finding what you taught

Ask A8. “What have I taught you about refunds?” returns the taught examples most relevant to the question, word for word, ready to retract or teach again. This is recall, and it needs the models:explain permission. Recall lists the examples in the version that answers: a teach appears once its fit lands, and a retracted example leaves with the next fit. See Precedents.

§6Checking that it took

Test the model the way you would test a student: ask it new questions with answers you know, and compare. See Testing A8.

§7Scope

Teaching is scoped to your organization. Your examples stay in it and train its model alone. They shadow the reference model for the criteria you teach, and the reference model answers the rest.

When you teach a criterion the reference model already covers, your examples take its place in your model. That criterion then earns its accuracy levels on your examples, so a criterion taught with a handful of examples can promise less than the reference model did. The promise follows the evidence.

The reference model stays as published, and you can call it directly as a8-1-1@reference. Run the same test against both to measure what your teaching changed.

§8Edge cases

§9Related concepts

• Horizons: the versions a fit produces, and pinning
• Precedents: the taught examples behind a verdict, and recall
• Accuracy and abstention: the levels a criterion earns from its examples
• MCP: the teach and retract tools and their schemas