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

# Welcome to the Engine

> An introduction to the Engine — what it is, what it's for, and how to think about building with it.

The Engine is an agentic runtime. You hand it a message and it runs a
complete agent loop on your behalf — calling the model, calling tools,
asking you for input when it gets stuck, and remembering everything that
happens so the next conversation is smarter than the last.

You can think of the Engine as the part of an AI product that sits between
"the user said something" and "the user got something useful back." It is
not a model. It is not a UI. It is the loop, the memory, the tools, and the
permissions that turn a model into something that can do work.

## When to reach for the Engine

The Engine is a fit when you want:

* **Long-running agents** that do real tasks across many turns, not single-
  shot completions.
* **Persistent memory** — the agent should know what it learned about the
  user yesterday.
* **Tool use** that's safe — sandboxed shell, read/write filesystem, MCP
  connectors to external services, with permission prompts when something
  dangerous shows up.
* **Streaming output** so the user sees thinking as it happens.
* **Human-in-the-loop** — the agent can pause, ask the user a question, and
  resume when they answer.

It is not a fit when you want:

* A bare-metal model API. Use the model provider directly for that.
* A chat UI. Bring your own.
* A multi-tenant SaaS surface. The Engine is single-user; multi-tenancy
  lives upstream.

## The shape of an interaction

Here's the simplest version of how the Engine works. You send a request:

```http theme={null}
POST /execute
X-Engine-Key: <your key>
Content-Type: application/json

{
  "message": "Find the latest commit on the main branch and summarize what changed.",
  "task_id": "task-001"
}
```

The Engine streams back Server-Sent Events:

```
event: thread_lifecycle
data: {"phase": "started", ...}

event: text_delta
data: {"text": "Looking up the most recent commit..."}

event: tool_call
data: {"tool": "bash", "input": {"command": "git log -1 --format=%H"}}

event: tool_result
data: {"output": "8c44ab1..."}

event: text_delta
data: {"text": "The latest commit is 8c44ab1. It..."}

event: thread_lifecycle
data: {"phase": "completed", ...}
```

The events come in real time. The agent loop is running on the server;
you're watching it think.

## The five things to understand

If you understand these five things, you can build anything on the Engine.

### 1. Tasks

A `task_id` identifies a single conversation thread. The Engine keeps state
per task — the conversation history, the tool call results, the working
memory. Every `/execute` call is part of a task. You pick the IDs.

### 2. The agent loop

When you send a message, the Engine drives a loop: it sends the
conversation to the model, gets back a response (which may include tool
calls), runs the tools, feeds the results back to the model, and repeats
until the model says it's done. You watch the loop through the SSE stream.

### 3. Tools

The agent can use three kinds of tools:

* **Built-in** — read files, write files, run bash commands, search the
  web. All sandboxed.
* **MCP connectors** — external services (Slack, Gmail, Notion, etc.) the
  user has connected through the Asset Directory.
* **Skills** — small reusable prompts and scripts you've defined.

You don't have to enable all of them. The agent uses whatever's available.

### 4. Memory

The Engine has long-term memory by default:

* **Episodes** — what happened.
* **Knowledge** — what's true.
* **Social graph** — who's who.

Memory updates as the agent runs and is searchable through the
`/memory/*` endpoints. The next conversation starts with the relevant past
already loaded into context.

### 5. Permissions and HITL

Anything risky — running a destructive shell command, accessing a
restricted path, calling an external service for the first time — pauses
the agent and emits an `hitl_request` event. The agent waits for an answer
through `POST /hitl/respond` before continuing. This is how you let the
agent do real work without giving it free run of your system.

## Where to go next

<CardGroup cols={3}>
  <Card title="Quickstart" icon="rocket" href="./quickstart">
    Send your first request in curl, Python, or Node.
  </Card>

  <Card title="The agent loop" icon="rotate" href="../agents-and-tools/agent-loop">
    What's actually happening between request and response.
  </Card>

  <Card title="API reference" icon="book" href="../api-reference/overview">
    Every endpoint, every parameter.
  </Card>
</CardGroup>