DocsAgents, Tools, Memory

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

1
Observation: The agent receives a user message or tool output.
2
Reasoning: The model decides what to do next (Call Tool vs. Answer).
3
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#

State Management

Akios provides two types of memory out of the box. You can swap the storage backend (Redis, Postgres, In-Memory) without changing your agent logic.

Short-term Memory

The context window. Stores the current conversation history.

  • Ephemeral (session-based)
  • Limited by model context size
  • Automatically summarized

Long-term Memory (RAG)

Vector storage for retrieving relevant documents based on semantic similarity.

  • Persistent
  • Infinite capacity
  • Retrieved via "Recall" tool

Guardrails#

Deterministic Safety

Guardrails are synchronous validators that run before the LLM sees the prompt (Input Rails) and after the LLM generates tokens (Output Rails).

Security Note

Always implement guardrails outside the prompt. "Please do not do X" in a system prompt is a suggestion, not a constraint. AKIOS guardrails are code, not English.
typescript
const guardrails = new Guardrails({
  input: [
    DetectPII,       // Redact emails/phones
    DetectInjection  // Block "Ignore previous instructions"
  ],
  output: [
    ValidateJSON,    // Ensure valid JSON syntax
    BlockCompetitors // Regex filter for competitor names
  ]
})
Previous← DeploymentNextStreaming & Events →