---
title: "Ask Cernion for compact evidence, guardrails and process context"
method: POST
path: "/api/copilot/ask-cernion-agent"
tags: ["Personal Agent"]
---

# Ask Cernion for compact evidence, guardrails and process context

`POST /api/copilot/ask-cernion-agent`

## Request

- Base URL: `https://api.cernion.de`
- URL: `https://api.cernion.de/api/copilot/ask-cernion-agent`
- Auth: none declared

Read-only Copilot action. Returns compact structured evidence and guardrails from Cernion entity search, Knowledge RAG, datapoints and object-store context. It does not run the heavy Personal Agent chat path and does not execute, confirm, sign, delete or modify process data.

## Query parameters

- `token` string

## Request body

- object
  - `question` string, required: User question to answer with Cernion evidence and process context.
  - `sessionId` string: Optional stable Copilot conversation/session identifier.
  - `context` object: Optional tenant, user, object, process or document context.
  - `inputs` object: Optional canonical structured input values (e.g. assetType, location, minCapacity, maxCapacity, commissioningYear, limit) for Blueprint read-only REST-plan compilation. Separate from `context`.
  - `domain` 'auto' | 'vnb' | 'vdmi' | 'znp' | 'grid-connection' | 'edm' | 'finance' | 'process': Optional domain hint for routing.
  - `mode` 'answer' | 'evidence' | 'process_check' | 'prepare_intent': Controls whether the answer should focus on evidence or process checks.
  - `maxEvidence` integer: Maximum number of evidence items returned.
  - `includeFederatedKnowledge` boolean: Opt-in only (default false, does not change the default evidence sources/output shape). When true, additionally queries `knowledge-rag.federatedSearch` (Marktkommunikation/regulatory collections) and includes it as an advisory `evidenceBySource.federatedKnowledge` entry.
  - `token` string: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.

## Response `200`

Compact Cernion answer for Copilot composition

- object
  - `sources` object[]: Per-turn source timings and status, without document contents.
    - `name` string, required
    - `status` string, required
    - `hitCount` integer, required
    - `ms` integer, required
  - `success` boolean, required
  - `sessionId` string
  - `question` string
  - `shortAnswer` string, required
  - `groundingAnswer` string, required: Prompt-ready Cernion grounding package for Copilot composition. Contains user question, answer, evidence, guardrails, risks, open questions and answer rules in one text field.
  - `consultingBrief` string: Optional backend-generated consulting brief for Copilot. It structures the evidence but is not a standalone source of facts.
  - `confidence` 'high' | 'medium' | 'low'
  - `evidence` object[], required
    - `source` string
    - `value` string
    - `retrievalHint` string: Optional vector/retrieval text for topic orientation; not standalone answer evidence.
  - `processContext` string[], required
  - `evidenceBySource` object: Evidence grouped by source: entities, knowledge, datapoints, and object-store objects.
  - `guardrails` string[]: Instructions Copilot must apply before composing the final answer.
  - `entities` string[]
  - `risks` string[]
  - `openQuestions` string[], required
  - `recommendedNextSteps` string[], required
  - `allowedActions` string[], required
  - `forbiddenActions` string[], required
  - `routing` object
  - `resolved` object: Blueprint/Capability resolution outcome (energychain/cernion-energy-tools#271). kind is "blueprint" when a read-only execution plan was compiled, "none" otherwise.
    - `kind` 'blueprint' | 'none'
    - `id` string
    - `version` string
    - `source` string
  - `canonicalInputs` object: Normalized inputs used to compile the execution plan, if any.
  - `recommendedEndpoints` object[]: Read-only endpoint recommendations (energychain/cernion-energy-tools#271 architecture follow-up). Cernion recommends which approved read-only endpoint(s) are the evidence surface for this request and what each result set means fachlich — it does not execute them or synthesize a final answer; that is the responsibility of the consuming agent/orchestrator. May contain more than one complementary endpoint.
    - `method` string
    - `path` string
    - `query` object
    - `resultSemantics` object: Fachliche Bedeutung des Result-Sets dieses Endpoints.
      - `kind` string
      - `description` string
  - `execution` object, nullable: Alias of recommendedEndpoints[0] for backward compatibility with #271 consumers that only read a single plan, or null when none is available.
    - `mode` string
    - `method` string
    - `path` string
    - `query` object
  - `policy` object
    - `readOnly` boolean
    - `sideEffects` string
    - `tenantScoped` boolean
    - `externalSideEffects` boolean
  - `noPlanReason` string: Present when resolved.kind is "none" — explains why no executable read-only plan was available.

---

[API](https://skmtc.dev/cernion/apis/cernion-energy-tools-api.md) · [All operations](https://skmtc.dev/cernion/apis/cernion-energy-tools-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cernion/apis/cernion-energy-tools-api/revisions/cdb94473b538?raw)