AI & agents

Agent runtime with tool-use loop

Runs a bounded, recorded model-and-tools loop against the database, so an operator can delegate routine checks to an agent without handing it raw access.

BetaEngine edition 5f8ea3af

What it does

An agent is a name, a system prompt, an allow-list of actions and an optional provider and model. POST /admin/agents/{id}/run sends a task through a loop of model call, tool call and tool result for at most eight turns, and persists the run with its steps, token counts and an estimated cost. Four preset agents are seeded on first boot, and one agent can delegate to another with a depth limit.

How it works

Agents are stored as ordinary entities and managed with POST /admin/agents by an admin role. allowed_actions is a whitelist that fails closed: an empty list means the agent can call nothing, and a call outside the list is refused before it reaches the action. A task is capped at 64 KiB.

A run first records a durable run head, claims it with a lease and assembles context under a budget: the system prompt and the task are mandatory, and up to eight scoped memories recalled for the task are added within a 16,384-token input budget. The loop then asks the provider for a completion (1,024 output tokens, temperature 0.2), executes each requested tool call through one shared gate that checks the allow-list, a 1 MiB payload cap and the approval policy, feeds the result back and repeats. A reply with text and no tool calls ends the loop; reaching the eighth turn ends it with the status hit_max_turns. After every turn the run saves a checkpoint.

Provider choice is per agent. With a provider set, that provider alone is used. Without one, the registry tries providers in order (a local Ollama server first, then Anthropic and an OpenAI-compatible endpoint when their keys are present) until one answers. The finished run is stored with its steps, answer, provider, model, turn count, summed token usage and an estimated cost, and can be listed per agent or across all agents.

POST /admin/agents/{id}/run/stream returns the same run as server-sent events: token, tool_call, tool_result and end. A token event carries the assistant text of a whole turn, because the provider calls are not streamed. The built-in presets are sre, deploy-ops, data-ops and catalog-ops, each with a narrow allow-list. The delegate_to_agent action lets one agent run another by name in the same scope, with a depth cap of three.

Where you reach it

  • HTTPPOST /admin/agents, GET /admin/agents, POST /admin/agents/{id}/run, POST /admin/agents/{id}/run/stream, GET /admin/agents/{id}/runs, GET /admin/runs

Example

Define an agent with two read actions and run itbash
curl -s -X POST "$KYNETRA_URL/admin/agents" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "stock-check",
    "description": "Counts records in a collection",
    "system_prompt": "Answer questions about collection sizes. Be concise.",
    "allowed_actions": ["list_collections", "count_records"]
  }'

curl -s -X POST "$KYNETRA_URL/admin/agents/$AGENT_ID/run" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "task": "How many records are in the orders collection?" }'

Limits

  • Every agent route needs an admin role. Agents are an operator facility, not a per-tenant feature.
  • The built-in actions are an operator facility. Give an agent just the actions it needs, and do not expose agent runs to untrusted users.
  • Multi-turn tool use has been tested with scripted providers. It has not been exercised against hosted providers for this edition, so verify the behaviour with your own provider before relying on it.
  • A run has fixed limits: eight turns, 1,024 output tokens per call and a fixed temperature. They are not per-agent settings.
  • Usage from the agent loop is not recorded in the model-observability metrics, which cover the /v1/llm route alone.
  • Cost figures are estimates; see the scheduler, approvals and cost entry.

Evidence

  • On this siteAI features catalogue
  • Tests6 integration tests with scripted providers cover plain answers, tool-call resolution, run persistence, the turn cap on a runaway loop and unknown-tool handling; 4 cover the durable run store and context assembly; 2 cover delegation; 9 more cover presets, schedules, run recall and the replica rule

Test coverage is listed as present in the engine repository at this edition. This page does not report test results.

KynetraDB is in private preview

Request a preview to talk through the limits above against your own workload.