How to run an evidence comparison
Use this guide when a research question has several findings and you want the agent to compare them. You
start with a question that has findings; you end with an agent run recorded as succeeded, new findings
with origin agent and assertion kinds you can read, and a decision of yours on any hypothesis it
proposed. Starting the run needs evidence.agents.use; following it needs program.agent_runs.read;
deciding a hypothesis needs evidence.hypotheses.approve.
Locally the agent runtime is a fake (AGENT_RUNTIME_URL empty) that returns canned illustrative results.
In every environment the agent only proposes: it writes new records with origin = agent and never
changes an approved record. A person reviews and decides.
Prerequisites
- A question under
Evidence › Questionswith at least one finding. - The worker running (
make workerinapi/), otherwise the run staysqueued.
Open the question
In the rail choose Evidence, then Questions in the panel (/p/<slug>/evidence/questions), and
select the question. The detail shows its statement, status and three agent actions: Compare
findings, Review evidence (finds gaps) and Propose hypotheses. Needs evidence.questions.read.
Start the comparison
Choose Compare findings (needs evidence.agents.use). The button calls
POST /programs/{program_id}/evidence/agent-runs with kind: evidence_compare and the question_id;
the API answers 202 with an AgentRunOut in status queued. The same
action is offered on a finding, where it compares the findings of that finding’s question.
Follow the run
In the rail choose Setup, then Agent runs in the panel (/p/<slug>/setup/agent-runs); needs
program.agent_runs.read. Select the run to read its events (GET .../agent-runs/{run_id}/events,
ordered by seq) and its result_summary. The status moves queued ->
running -> succeeded, or ends
failed with a public error code such as runtime_unavailable or
attribution_leak. A run can be cancelled with Cancel run (needs program.agent_runs.manage).
Read what was proposed
Back under Evidence › Findings the new records carry the chip “Agent-generated, for review” and an
assertion kind in observation, interpretation, assumption or suggestion, with agent_run_id
pointing at the run. Nothing the agent wrote uses the success tone until a person accepts it.
Decide a proposed hypothesis
If the run proposed a hypothesis, open Evidence › Hypotheses, select it (status
proposed) and choose Record decision (needs evidence.hypotheses.approve).
Pick accepted or rejected and give a rationale; the form calls
POST .../evidence/hypotheses/{hypothesis_id}/decision, the status changes and an audit row
hypothesis.decision is written in the same transaction.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| The action buttons are disabled | You lack evidence.agents.use | The scientist, program_lead and program_owner personas hold it |
The run stays queued | No worker | make worker in api/ |
The run ends failed with attribution_leak | The submit lint found forbidden text in the result | The result is discarded by design; start the run again |