Connect an Agent

Use this page after the Runtime is installed and running. Pick one integration path, pass only the final Agent-facing context to your Agent, then send feedback after the task.


npx aionis setup --profile full-local
cd .aionis-runtime
npm run -s lite:start
curl http://127.0.0.1:3001/health

Pick One Path

Agent host	Use	Give the Agent
Node or TypeScript loop	SDK	`guide.agent_prompt`
Any backend or language	HTTP	`agent_context.prompt_text` from `/v1/guide`
Claude Code, Cursor, Zcode, or MCP host	MCP	`aionis_context.agent_prompt`
File-reading Agent	AIFS	`.aionis/AGENT_INSTRUCTIONS.md`

Do not pass guide_packet, memory_packet, decision traces, snapshots, or raw slots as the main Agent prompt. Keep those for logs, dashboards, and operator review.

SDK

Use the SDK when you own a Node or TypeScript Agent loop.


npm install @aionis/sdk


import { createAionisClient, feedbackFromGuide } from "@aionis/sdk";
 
const aionis = createAionisClient({
  baseUrl: "http://127.0.0.1:3001",
  tenant_id: "default",
  scope: "my-project",
});
 
await aionis.execution.observeStep({
  run_id: "run-001",
  task_signature: "checkout-migration",
  agent_id: "worker-1",
  role: "worker",
  title: "Worker started checkout migration",
  summary: "The Agent is continuing from the accepted migration route.",
  outcome: "neutral",
});
 
const guide = await aionis.guideAgentContext({
  run_id: "run-001",
  consumer_agent_id: "worker-1",
  query_text: "Continue the checkout migration from the accepted route.",
  context_mode: "compact_agent",
  task_context_profile: "coding_verifier",
  context: {
    task_signature: "checkout-migration",
  },
});
 
const result = await agent.run(guide.agent_prompt);
 
if (result.usedMemoryIds?.length) {
  await aionis.feedback(feedbackFromGuide({
    guide,
    run_id: "run-001",
    outcome: result.ok ? "positive" : "negative",
    reason: result.summary,
    used_memory_ids: result.usedMemoryIds,
    used_surface: "use_now",
    actor: "worker-1",
  }));
}

HTTP

Use HTTP when your Agent host is not TypeScript or when Aionis sits behind a service boundary.


curl -s http://127.0.0.1:3001/v1/observe \
  -H 'content-type: application/json' \
  -d '{
    "tenant_id": "default",
    "scope": "my-project",
    "input_text": "The accepted route is to keep Runtime as the source of truth.",
    "owner_agent_id": "worker-1"
  }'
 
curl -s http://127.0.0.1:3001/v1/guide \
  -H 'content-type: application/json' \
  -d '{
    "tenant_id": "default",
    "scope": "my-project",
    "consumer_agent_id": "worker-1",
    "query_text": "Continue from the accepted route.",
    "context_mode": "compact_agent",
    "mode": "full_power"
  }'

Use agent_context.prompt_text as the Agent prompt. Keep guide_trace_id for feedback.


curl -s http://127.0.0.1:3001/v1/feedback \
  -H 'content-type: application/json' \
  -d '{
    "tenant_id": "default",
    "scope": "my-project",
    "target": "memory",
    "guide_trace_id": "guide_trace:...",
    "run_id": "run-001",
    "outcome": "positive",
    "used_surface": "use_now",
    "used_memory_ids": ["mem_123"],
    "reason": "The Agent used the exposed current-state memory successfully."
  }'

MCP

Use MCP when your Agent host can call MCP tools.


npx @aionis/mcp@latest \
  --base-url http://127.0.0.1:3001 \
  --scope-from workspace \
  --workspace-id-store user

For the smallest useful loop:


aionis_context -> Agent action -> aionis_record_step

The Agent-facing text is aionis_context.agent_prompt. Use aionis_record_step after meaningful tool calls, verifier results, or handoff points.

AIFS

Use AIFS when the Agent reads project files better than it calls custom tools. Run AIFS from the Agent workspace, not from the Runtime directory.


npx @aionis/aifs@latest init \
  --base-url http://127.0.0.1:3001 \
  --scope my-project
 
npx @aionis/aifs@latest refresh \
  --base-url http://127.0.0.1:3001 \
  --scope my-project \
  --query "Continue from the accepted route."

Tell the Agent:


Before continuing, read .aionis/AGENT_INSTRUCTIONS.md and follow the Aionis file-surface order.
Use .aionis/current_active_path.md as the active route.
Treat .aionis/do_not_use.md as blocked memory.
Rehydrate pointers in .aionis/rehydrate_needed.md before exact edits.

After The Task

Whichever path you choose, keep these identifiers stable:

Field	Meaning
`tenant_id`	Tenant boundary.
`scope`	Project or workspace boundary.
`run_id`	Execution session.
`task_signature`	Stable task or workflow identity.
`agent_id`	Agent that produced or consumed evidence.
`guide_trace_id`	Feedback attribution key.

Then record the outcome:


Agent action -> feedback -> measure -> snapshot

Use First Agent Loop when you want the complete product loop. Use SDK and API Surface Matrix when you need to confirm which outputs are Agent-facing and which are operator-only.