qalatra/docs/Agent fundamentals

Agent fundamentals

What Qalatra means by "agent" — and what makes it different.

In Qalatra, an agent is any folder on disk with an agent.config file. That's it. The folder can contain scripts, prompts, datasets, venvs — whatever the agent needs. The config tells Qalatra how to run it.

Why folders

Agents that live on disk are:

  • Portable. Copy the folder, you've copied the agent.
  • Versionable. Drop it in a git repo. Roll back a bad prompt.
  • Sharable. Someone else's triage-me works for you, too.
  • Composable. Agents can invoke other agents via mcp:dispatch_agent.

Agent lifecycle

  1. Dispatched — triggered by user, schedule, or another agent
  2. Running — Qalatra spawns the process, streams stdout into the task detail panel
  3. Complete — exit 0: task marked done. Non-zero: task marked failed with the real error.

What agents get

Every running agent receives:

  • The MCP server URL + auth token as env vars (QALATRA_MCP_URL, QALATRA_MCP_TOKEN)
  • The invoking task's id as QALATRA_TASK_ID
  • The agent's own folder as cwd

So the simplest working agent is a shell script that calls claude with a prompt. See Writing your own agent.

Where agents live

By default ~/.qalatra/agents/. Configure a second path (e.g. a shared team folder) in Settings → Agents → Paths.