Core Concepts
This page explains the key ideas behind Arkna in plain English. No jargon, no assumptions. If you understand these five concepts, you understand how Arkna works.
How the Proxy Works
Normally, your AI agent sends requests directly to an AI provider (like OpenAI or Anthropic). The provider processes the request and sends back a response.
With Arkna, your agent sends requests to Arkna's proxy URL instead. A proxy is a middleman: it receives your request, makes a copy for recording, then forwards it to the real AI provider. When the AI responds, Arkna records the response and sends it back to your agent.
From your agent's perspective, nothing changes. It uses the same API key, sends the same requests, and gets the same responses. The only difference is the URL it sends to.
What is a Run?
A Run is one complete task that your agent performs, from start to finish.
For example: you ask your agent to "summarise the Q4 sales report." The agent thinks about what to do, queries a database, reads some documents, and writes a summary. That entire process, from the moment you asked the question to the moment the agent delivered an answer, is one run.
Every run has:
- A trigger: what started it (an API call, a user message, a scheduled task)
- A status: whether it completed successfully, failed, or timed out
- A duration: how long it took
- A cost: how many tokens (units of AI processing) it used
When you look at your Arkna dashboard, the main view shows you a list of runs: every task your agent has performed.
What is a Step?
A Step is one action within a run. If a run is the whole task, a step is a single thing the agent did during that task.
Using the sales report example, the steps might be:
- Reasoning: the agent thinks: "I need to check the sales database"
- Tool call: the agent queries the database
- Reasoning: the agent thinks: "Now I'll format this as a summary"
- Completion: the agent writes the final answer
Arkna records every step so you can play them back one by one and understand the agent's thought process.
Types of Steps
| Step Type | What It Means |
|---|---|
reasoning | The agent is thinking, planning, or deciding what to do next |
tool_call | The agent is using an external tool (see "Tool Calls" below) |
retrieval | The agent is looking something up: searching a database, reading a document, or fetching data |
action | The agent is doing something with real-world impact: sending an email, updating a record, making a purchase |
error | Something went wrong during this step |
completion | The agent has finished and is delivering its final answer |
What is a Tool Call?
A Tool Call happens when your agent uses an external tool or service to get something done. "External" means anything outside the AI itself: a database, a web API, a file system, a payment processor, etc.
Examples of tool calls:
- Querying a PostgreSQL database
- Calling the Stripe API to process a payment
- Searching the web for information
- Reading a file from disk
- Sending a Slack message
Arkna records what tool was called, what arguments were passed, what came back, whether it succeeded or failed, and how long it took.
What is a Session?
A Session groups related runs together. Think of it as a conversation.
If you're chatting with an AI assistant and ask three questions in a row, each question might be its own run, but they all belong to the same session: the same conversation.
Sessions are optional. You don't have to use them. But they're useful when you want to see the full context of a multi-turn interaction, not just individual runs.
How It All Fits Together
Here's the hierarchy, from biggest to smallest:
A session contains one or more runs. Each run contains one or more steps. A step might include one or more tool calls.
Replay
Once Arkna has recorded a run, you can replay it: go back and watch exactly what happened, step by step.
The replay shows you:
- Every step in order: what the agent thought, what it did, and what it got back
- What the agent knew: the system prompt, instructions, and documents available at each step
- Anomalies: anything unusual, like a step that took much longer than expected or a tool call that failed
- A summary: a human-readable description of what the agent did and why
You can access replay through the Arkna dashboard (click on any run) or through the monitoring API.
What is the Hash Chain?
The hash chain is how Arkna proves that a recording hasn't been tampered with.
Here's the idea: every step in a run gets a unique digital fingerprint (called a hash). Each step's fingerprint includes the previous step's fingerprint. This means that if anyone changes even one step, all the subsequent fingerprints won't match, and Arkna will flag the recording as compromised.
Why does this matter? If you're using Arkna for compliance, auditing, or incident investigation, you need to be able to prove that the recording is authentic. The hash chain gives you that proof. When you replay a run, Arkna automatically verifies the hash chain and tells you if everything checks out.
Anomaly Detection
Arkna watches your agent's behaviour over time and automatically spots when something unusual happens. This is called anomaly detection (finding things that are different from the norm).
Arkna looks for:
| What Arkna Watches | Example |
|---|---|
| Error rate spikes | Your agent was failing 2% of the time, now it's failing 30% |
| Duration anomalies | Runs that usually take 3 seconds are now taking 30 seconds |
| Cost anomalies | A run used 50x more tokens than usual (which means 50x the cost) |
| Frequency anomalies | An agent that runs 10 times per hour is suddenly running 1,000 times |
When Arkna detects an anomaly, it raises an alert and can promote it to an incident. Each incident links straight to the recorded run, so you can replay exactly what the agent did, step by step, and export the evidence for your risk committee, auditor, or regulator.