Agents — every field explained

What an agent is, every field in the create form, and which defaults to leave alone until you've shipped something real.

What an agent is

An agent is a saved configuration for answering questions: a system prompt, a model, a project scope, an output shape. Once built, you call it from three places:

The browser (Agents tab → Run).
The Word and Excel add-ins (paste a key, pick an agent, type your input).
Your own code via POST /api/run.php (paste the key in an Authorization header).

Same agent, same answers — no matter which surface you call it from. That consistency is what makes agents worth setting up.

The fields, top to bottom

Name & description

Short human-readable name (shown in dropdowns) and a one-line description (helps teammates understand what it's for). Both visible to anyone who can see the agent.

Projects

Which projects the agent can retrieve from. This is the most-important scoping decision — it's the difference between an "RFP responder" that draws only from past bid documents and one that accidentally pulls passages from your employee handbook.

You can tick multiple projects. The agent retrieves across all of them, treating them as one combined corpus.

System prompt

The instructions the model follows. This is where you encode how the agent should behave: tone, format, hard rules, what to do when it doesn't know.

The best system prompts are short and direct. A few patterns that work:

You are a security questionnaire responder. Answer ONLY from the
provided control evidence. If the question asks about a control
that isn't in the evidence, set needs_review=true and answer
"To be confirmed by Security team." Never claim coverage that
isn't documented.

You are an RFP responder. Match the tone and structure of the
source material from past winning RFPs. Keep answers under 400
words. Cite document names. If the question is not addressed in
the snippets, explain in "gaps" what additional information is
needed.

The retrieved chunks are automatically appended to the prompt before the model sees it — you don't need to write "use the following snippets" or anything like that.

Input template (optional)

A template that wraps the caller's input before it goes to the model. If you leave it blank, the user's input is passed verbatim. Useful when calls come from Excel or the API and you want to add framing the caller shouldn't have to remember.

Leave it blank when the agent is called from the browser (the user is already typing a full question), or from a Word add-in skill that bundles its own prompt template (see Skills).

Set it when calls come from Excel rows or your own code with bare inputs that lack context. Three patterns that work:

RFP question: {input}

Excel users paste a column of bare questions; the template adds "RFP question: " in front of each one so the model knows what kind of task this is.

Vendor security questionnaire item: {question}
Standard: {standard}
Section: {section}

Multi-variable form. The Excel add-in maps spreadsheet columns to these variables — column A → {question}, B → {standard}, C → {section}.

Contract clause to review: {input}

Compare it against our negotiation playbook. Identify any deviation, severity (none|minor|material|blocker), and recommended counter-position.

Template includes both framing and instructions. The system prompt stays high-level; the per-call template is where the structured task lives.

When in doubt, leave it blank and put framing in the system prompt instead. The system prompt runs once per call regardless of template; the input template only fires when you need per-call structure on top.

Grounding mode

When ON (the default for new agents), the system prepends an unbreakable rule: "Answer only from the provided sources. If they don't cover the question, say so." In JSON mode it also forces a needs_review boolean into the output.

Turn it off only when you specifically want the model to reason beyond the corpus (e.g. brainstorming agents, draft generators that need general knowledge). For anything customer- or audit-facing, leave it on.

Model

Which language model generates the answer. Knowledge supports two tiers:

Standard — Mistral Small, GPT-4o mini, Claude Haiku, Gemini Flash. Fast and cheap; ideal for bulk Q&A like questionnaire filling.
Premium — Mistral Large, GPT-4o, Claude Sonnet, Gemini Pro. Better instruction-following and grounding fidelity. Worth the cost for high-stakes outputs.

See Pick the right model for honest guidance — expensive isn't always better, and the right answer is often "the cheap one, twice."

top_k

How many chunks to retrieve and feed to the model. Default is 5; range 1-20.

Lower (3-5) when chunks tend to be self-contained and you want sharp focus.
Higher (8-12) for questionnaire-style agents where the answer might be spread across several controls.
Above 12 only if you're seeing the model miss obvious context — and check whether your chunks are too small first.

Temperature

How "creative" the model can be. Default 0.2; range 0.0-2.0.

0.0-0.3 — factual, deterministic. Use for anything where the answer is in the corpus and you want it back, verbatim where possible. Default for new agents.
0.4-0.7 — slight rewording, smoother prose. Use for drafting Word documents where the source material needs to be re-articulated in your house style.
0.8+ — brainstorming. Rarely the right choice for grounded answers.

max_tokens

Hard ceiling on the answer length. Default 800 tokens (~600 words). Bump up for long-form drafting agents (Word add-in design-doc drafter: 2000-3000), keep low for questionnaire responders (300-500).

Output mode — text vs JSON

Use Text when the answer is for a human to read directly: browser chat, Word add-in drafts, agents you'll only ever call from the SPA. This is the default and the right choice for the vast majority of agents.

Use JSON when the answer is for a machine to parse: Excel add-in (each top-level key becomes a spreadsheet column), your own application code calling the agent via POST /api/run.php, or any workflow that branches on a confidence score / source list / structured verdict.

Surface	Recommended mode	Why
Browser chat / Search	Text	Humans read prose; JSON is harder to skim.
Word add-in (drafting)	Text	Inserts directly into your document.
Word add-in (Verify / Audit skills)	JSON (auto)	The skill needs `findings[]`; you don't pick this — the skill does.
Excel add-in (Answer questionnaire skill)	Text	Single answer per row, written into one column.
Excel add-in (custom agent)	JSON	So `{answer, confidence, source}` spreads into B-D.
Your own code (REST API)	Either, depending on what you parse	JSON if you need structured branching; text if you just store the answer.

JSON mode trade-off. Cheap models (Mistral Small, Gemini Flash) occasionally produce malformed JSON. The runner retries once automatically; persistent failures suggest you should either simplify your schema or upgrade the model (see Pick the right model).

Output schema (JSON mode only)

A JSON object describing the shape you want back. Three patterns that cover almost every Excel use case:

RFP / questionnaire responder:

{
  "answer":     "string",
  "confidence": "number",
  "sources":    ["string"],
  "gaps":       "string"
}

Excel mapping: A=question, B=answer, C=confidence, D=sources (comma-joined), E=gaps. Sort by confidence ascending to find the rows that need human review.

Audit / control evidence mapper:

{
  "evidence_summary": "string",
  "document_name":    "string",
  "page_numbers":     "string",
  "control_owner":    "string",
  "gap_identified":   "boolean"
}

Each row = one auditor control. Filter gap_identified=true to triage gaps.

Contract clause comparator:

{
  "playbook_position":   "string",
  "contract_position":   "string",
  "deviation":           "string",
  "severity":            "string",
  "recommended_response":"string"
}

One row per clause. Sort by severity, work the blockers first.

See Word & Excel add-ins for the column-mapping flow.

Status

active (callable) or disabled (existing keys stop working, agent hidden from dropdowns). Use disabled for retired agents rather than deleting — keeps the call history intact for auditing.

Keys — how to authenticate add-in / API calls

Open an agent → Keys tab → + Mint key. Give it a friendly name ("Word — Sarah's laptop", "Production worker"), copy the token once (we never show it again), paste it into the add-in or your code.

Each key is bound to a single agent. Revoke at any time from the same Keys tab. Per-key rate limits are configurable for agents that get called from automation.

Call history & auditing

Open an agent → Recent calls to see every call: who made it, when, which input, which model, what was returned, how many tokens. Useful for debugging an agent that's drifting, or for surfacing answers that need review.