Agents Overview

An agent in Open Astra is a configured AI entity with its own model, system prompt, skill set, tool set, and permission profile. Agents are the primary unit of work — every conversation, background task, and scheduled job runs inside an agent.

What makes an agent

Component	Description
Model	The underlying LLM (provider + model ID). Can be swapped at runtime.
System prompt	The agent's persona and instructions. Supports template variables from context.
Skills	High-level capabilities composed from tools. E.g. `web-research`, `code-review`.
Tools	Individual callable functions available during the agent loop.
Memory	Access to session, daily notes, user profile, knowledge graph, and procedural tiers.
Permissions	Workspace grants, quotas, and approval requirements for sensitive actions.

Agent lifecycle

When a user sends a message, the agent goes through a fixed lifecycle:

Context assembly — workspace files, memory results, and tool definitions are injected into the prompt.
Budget pre-flight — estimated token cost and tool calls are checked against quotas before inference starts.
Inference — the model generates a response or tool calls.
Tool execution — any tool calls are run, results are appended, and inference continues.
Post-turn save — the conversation is persisted and memory extraction runs asynchronously.

See Agent Loop for the full technical breakdown.

Capability categories

Category	Pages
Core	Creating, Loop, Context, Cloning, Budget Pre-Flight
Observability	Metrics, Compaction Forecast
Orchestration	Swarms, Blackboard, Debate, Meta-Controller, Planner
Reliability	Self-Healing, Approvals, Quotas, Ethical Check
Autonomous	Deep Research, Dream Mode, Heartbeat, Scheduled

Defining agents

Agents can be defined three ways: in astra.yml, via the REST API, or directly in the database. The YAML approach is recommended for version-controlled deployments.

yaml

agents:
  - id: assistant
    displayName: Assistant
    model:
      provider: openai
      modelId: gpt-4o
    systemPromptTemplate: You are a helpful assistant for {{workspace.name}}.
    skills:
      - web-research
      - code-review
    tools:
      - file_read
      - file_write

See Creating Agents for the full configuration schema.

Next steps

Creating Agents — full config schema and API
Agent Loop — how the turn lifecycle works
Spawning & Swarms — multi-agent orchestration
Budget Pre-Flight — cost controls before inference