> ## Documentation Index
> Fetch the complete documentation index at: https://helpcenter.magure.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Core concepts

> Understand MagOneAI's architecture, terminology, and how structured autonomy powers reliable AI workflows

## Structured autonomy

MagOneAI is built on a philosophy we call **structured autonomy**: you define the workflow structure (predictable, auditable, deterministic), and AI handles the reasoning at each step.

This approach gives you the best of both worlds:

* **Structure you control** — You design the workflow graph: which agents run, in what order, what tools they have access to, and how data flows between steps. This structure is visual, portable (JSON), and version-controlled.
* **AI reasoning at each step** — Within each activity, the AI agent reasons about the input, decides which tools to use, interprets results, and produces output. The AI is powerful but constrained by the structure you defined.

The result is a system that's both intelligent and reliable. You get AI's flexibility without sacrificing predictability or governance.

***

## Key terminology

Understanding these core concepts will help you navigate MagOneAI's platform and build powerful workflows.

<AccordionGroup>
  <Accordion title="Organization">
    The top-level tenant in MagOneAI. Each organization has completely isolated data, users, agents, workflows, and resources. Organizations enable multi-tenancy for enterprise deployments, with independent LLM provider configurations and security policies.
  </Accordion>

  <Accordion title="Project">
    A container within an organization that groups related resources. Each project contains agents, use cases (workflows), tools, and knowledge bases. Projects have their own member management and access control, allowing teams to work independently within an organization.
  </Accordion>

  <Accordion title="Use Case">
    A workflow definition that orchestrates multiple activities to accomplish a business goal. Use cases are built on a visual canvas and exported as portable JSON. Examples: customer onboarding, RFP response generation, document processing, data enrichment pipelines.
  </Accordion>

  <Accordion title="Activity">
    A single node or step in a workflow. MagOneAI supports several activity types:

    * **Agent** — An AI entity that reasons, uses tools, searches knowledge bases, and produces structured output via DSPy
    * **Tool** — Direct execution of an MCP tool with specific parameters
    * **Parallel** — Execute multiple branches simultaneously with configurable merge strategies
    * **Condition** — Branch based on expression-based or AI-powered routing logic
    * **Human Task** — Pause for human approval or input
    * **Sub Use Case** — Call another workflow as a reusable module with input/output mapping
    * **ForEach** — Iterate over a collection, executing a child use case for each item in concurrent batches
  </Accordion>

  <Accordion title="Agent">
    An AI entity with a persona, model, tools, and knowledge bases. Each agent has a name, role, system instructions, and access to specific capabilities. Agents are reusable across multiple use cases within a project.
  </Accordion>

  <Accordion title="Tool">
    An external capability connected via the Model Context Protocol (MCP). Tools provide agents with access to calendars, email, search engines, databases, APIs, and custom integrations. MagOneAI's MCP-native architecture ensures standardized, secure tool connections.
  </Accordion>

  <Accordion title="Knowledge Base">
    A collection of documents indexed in Qdrant for RAG (Retrieval-Augmented Generation). Knowledge bases allow agents to access company-specific information, policies, documentation, and data. Documents are chunked (with optional contextual enrichment), embedded using dual dense + sparse vectors, and retrieved via hybrid search with reranking. Supports HyDE query expansion and agentic RAG for iterative search.
  </Accordion>

  <Accordion title="Trigger">
    The mechanism that starts a workflow execution. MagOneAI supports multiple trigger types:

    * **Manual (in-app)** — Run directly from the Studio canvas
    * **Chat** — Triggered by conversation in MagOneAI Hub
    * **Schedule** — Cron-based recurring execution
    * **API** — REST API endpoint for programmatic execution
  </Accordion>
</AccordionGroup>

***

## How a workflow executes

When you trigger a workflow in MagOneAI, here's what happens under the hood:

<Steps>
  <Step title="Trigger fires">
    A workflow execution begins when a trigger fires — this could be an API call, a scheduled cron job, a manual run from the Studio, or a chat message in MagOneAI Hub.
  </Step>

  <Step title="Temporal workflow starts">
    MagOneAI creates a durable Temporal workflow. This means the execution is crash-resistant, recoverable, and fully auditable. Every state transition is persisted.
  </Step>

  <Step title="Activities execute in order">
    The workflow engine processes activities according to your defined graph. It respects parallel branches (executing simultaneously), condition logic (branching based on evaluation), and sequential flows.
  </Step>

  <Step title="Agent activities reason and act">
    When an Agent activity executes:

    1. The agent receives context (previous outputs, workflow variables)
    2. The LLM reasons about the task and available tools
    3. The agent makes tool calls as needed (search, API calls, data lookups)
    4. The agent produces structured output based on its instructions
  </Step>

  <Step title="Results flow through variables">
    Each activity's output is stored in the workflow's variable store. Subsequent activities can reference these variables, creating a data pipeline through your workflow.
  </Step>

  <Step title="Workflow completes">
    When all activities finish, the workflow completes and returns the final output. The entire execution history is stored for auditing, debugging, and analytics.
  </Step>
</Steps>

<Info>
  **Every workflow execution is durable** — powered by Temporal. If a server crashes mid-execution, the workflow resumes exactly where it left off. No lost work, no manual recovery needed.
</Info>

***

## How MagOneAI ensures security

Security is built into every layer of MagOneAI's architecture:

* **HashiCorp Vault integration** — All API keys, credentials, and secrets are stored in Vault, never in configuration files or databases
* **Organization-level isolation** — Complete data separation between organizations, with no cross-tenant access
* **MCP protocol security** — Standardized, auditable tool connections with OAuth flows for third-party services
* **Audit logging** — Every workflow execution, agent action, and tool call is logged for compliance and debugging

***

## Next steps

Now that you understand the core concepts, dive deeper into how to use the platform:

<CardGroup cols={2}>
  <Card title="Platform guide" icon="compass" href="/platform/admin-portal">
    Explore the three portals: Admin Portal, MagOneAI Studio, and MagOneAI Hub
  </Card>

  <Card title="Workflow builder" icon="diagram-project" href="/quickstart">
    Learn how to build your first AI workflow on the visual canvas
  </Card>
</CardGroup>