Observe / Guide / Feedback

These three endpoints are the main Runtime loop. They are intentionally narrow: record evidence, compile governed context, then attribute outcome to memory that was actually exposed.


POST /v1/observe  -> record evidence
POST /v1/guide    -> compile governed Agent context
POST /v1/feedback -> attribute outcome to exposed memory

`POST /v1/observe`

Records ordinary memory, execution steps, handoffs, validator results, or host loop events.

Ordinary Memory


curl -s http://127.0.0.1:3001/v1/observe \
  -H 'content-type: application/json' \
  -d '{
    "tenant_id": "default",
    "scope": "checkout-migration",
    "input_text": "Prefer small patches and verify before broad refactors.",
    "memory": {
      "kind": "preference",
      "memory_lane": "private",
      "owner_agent_id": "worker-1"
    }
  }'

Execution Evidence


curl -s http://127.0.0.1:3001/v1/observe \
  -H 'content-type: application/json' \
  -d '{
    "tenant_id": "default",
    "scope": "checkout-migration",
    "input_text": "Legacy adapter attempt failed verifier review.",
    "execution": {
      "run_id": "run-001",
      "agent_id": "worker-1",
      "task_signature": "checkout-migration",
      "title": "Legacy adapter attempt",
      "summary": "Touched unrelated modules and was rejected.",
      "outcome": "failed",
      "target_files": ["src/checkout/legacyAdapter.ts"]
    }
  }'

Use execution evidence when the memory is about a run, branch, validator result, handoff, or workflow. Use ordinary memory for preferences and facts.

`POST /v1/guide`

Compiles governed Agent context and operator traces for a query.


curl -s http://127.0.0.1:3001/v1/guide \
  -H 'content-type: application/json' \
  -d '{
    "tenant_id": "default",
    "scope": "checkout-migration",
    "query_text": "Continue the migration without repeating failed branches.",
    "context_mode": "compact_agent",
    "mode": "full_power",
    "consumer_agent_id": "worker-1",
    "run_id": "run-001"
  }'

Important response fields:

Field	Meaning
`guide_trace_id`	Stable handle used for feedback attribution.
`agent_context.prompt_text`	The prompt-ready governed context.
`agent_context.use_now_memory_ids`	Memory IDs allowed to directly guide the next action.
`agent_context.inspect_before_use_memory_ids`	Relevant memory that needs verification.
`agent_context.do_not_use_memory_ids`	Memory explicitly blocked from direct action.
`agent_context.rehydrate_memory_ids`	Evidence pointers the Agent may need to expand.
`memory_use_receipt`	Compact audit of use/suppress decisions.

`POST /v1/feedback`

Attributes outcomes to memory IDs exposed by a prior guide. This is the closed loop that makes admission data useful.


curl -s http://127.0.0.1:3001/v1/feedback \
  -H 'content-type: application/json' \
  -d '{
    "tenant_id": "default",
    "scope": "checkout-migration",
    "target": "memory",
    "guide_trace_id": "guide_trace:...",
    "run_id": "run-001",
    "outcome": "positive",
    "reason": "The Agent followed the accepted path and avoided the failed branch.",
    "used_surface": "use_now",
    "used_memory_ids": ["mem_123"],
    "actor": "worker-1"
  }'

Feedback is intentionally strict:

Rule	Why
`guide_trace_id` is required for guide attribution	Aionis must know what the Agent was allowed to see.
`used_memory_ids` must be exposed by that guide	Hosts cannot attribute success or failure to hidden memory.
`used_surface` should reflect actual use	Outcome data trains admission quality only when attribution is honest.
Negative feedback is evidence, not automatic deletion	Aionis downgrades and gates through lifecycle rules.

Error Shape

Product facade errors use a bounded error payload:


{
  "error": "guide_trace_used_memory_not_exposed",
  "message": "activate feedback can only be attributed to memory ids exposed by the referenced guide_trace_id",
  "details": {
    "guide_trace_id": "guide_trace:..."
  }
}

Full details: AIONIS_PRODUCT_API_USAGE.md .