CORE_CONCEPTS

The AKIOS control plane is built around four primitives: Agents, Tools, Memory, and Guardrails. Understanding these is key to building deterministic systems.

AGENTS#

An Agent is a stateful entity that encapsulates a model, a system prompt, and a set of capabilities. Unlike a simple API call, an agent maintains an internal "thought loop" (Observation → Reasoning → Action) until a termination condition is met.

THE_AGENT_LOOP

OBSERVATION

The agent receives a user message or tool output.

REASONING

The model decides what to do next (Call Tool vs. Answer).

ACTION

The agent executes a tool or returns a response.

KEY_INSIGHT

Treat agents as compute processes, not personalities. Single responsibility + strict inputs/outputs = predictable behavior.

TOOLS#

Tools are deterministic adapters between the LLM and your systems. Each tool is a contract the model must follow. If the model hallucinates arguments that don't match the schema, AKIOS intercepts the call before it hits your code.

ANATOMY_OF_A_TOOL

NAMEUnique identifier used by the planner.
DESCRIPTIONNatural language hint for the LLM.
SCHEMAZod/JSON Schema for strict validation.
HANDLERAsync function that executes logic.

typescript

const sqlTool = new Tool({
  name: 'query_db',
  description: 'Execute a SELECT query. Read-only.',
  schema: z.object({ sql: z.string() }),
  handler: async ({ sql }) => {
    // AKIOS automatically validated 'sql' is a string
    return db.query(sql)
  }
})

MEMORY#

Memory allows agents to persist state across interactions. AKIOS provides short-term memory (conversation history) and long-term memory (vector database integration).

SHORT_TERM_MEMORY

Windowed buffer of recent messages. Keeps the immediate context active for the model.

LONG_TERM_MEMORY

Semantic search over past conversations using vector embeddings. Allows recall of facts from days ago.

GUARDRAILS#

Guardrails enforce safety and policy constraints. They can intercept inputs (before they reach the model) or outputs (before they reach the user) to ensure compliance.

INPUT_RAILS

Detect jailbreaks, PII, and off-topic queries before processing.

OUTPUT_RAILS

Prevent hallucination and enforce format (JSON) before returning to user.