How it works

The mental model behind Agentfy.ai 2.0. If you've read What is Agentfy.ai 2.0?, this is the next layer down — still plain language, no code.

Three parts: a brain, hands, and knowledge

An agent is made of three pieces that fit together:

• 🧠 Brain — thinks and replies. It reads the message, decides what to do, and writes the answer. The brain is just the api service running for one turn. There is no separate "agent server" — the brain is the api, run on demand.
• 🦾 Hands — does real work. Some jobs need an actual computer: run a script, edit files, drive a live browser, crunch a long task. The brain can't do those itself, so it hands them to a worker — a worker that spins up for the task, streams its progress back, saves the result, and shuts down.
• 📚 Knowledge — what the agent knows. The store's catalog and docs live in a separate knowledge service. The brain doesn't carry it around; it asks for the right facts when needed.

The life of one request

Here's what happens, start to finish, when a customer sends a message:

1. Idle. The agent is just a row in the database — its config, memory, and history. Nothing is running. Nothing costs anything.
2. A message arrives. The shared api fleet picks it up, loads the agent's data from the database, and "becomes" that agent for this one turn.
3. The brain thinks. It can answer directly, look something up in knowledge, or call a tool connected to the store (e.g. check an order via the OpenCart API).
4. Hands, if needed. If the job needs a real OS — scripting, files, a browser — the brain dispatches a task to a worker, which runs it in a worker and reports back.
5. Reply + remember. The agent answers the customer, writes anything worth keeping to memory and history, and the brain lets go. The worker (if any) shuts down on idle.

The agent is always available (it's data, always there) but never always-on (it runs only in steps 2–5). That single property is what makes "an agent for every store" affordable.

What plugs into the brain

The brain stays small on purpose. Capabilities, knowledge, and memory plug in over a standard connector called MCP (think of it as a universal socket for agents):

• Tools — the store's APIs (products, orders), or any other MCP server, attach as actions the agent can take.
• Knowledge — the catalog/docs corpus is just one MCP source the agent queries.
• Memory — short-term (this conversation) and long-term (across conversations) recall.

Swap the sockets and you change what the agent can do — without touching the brain.

What runs all the time vs. on demand

It helps to split everything by lifecycle — how long it lives — rather than by feature:

Part	When it runs	Scales with
Control plane — api Core + the web apps (app, admin)	always on	connections / requests
Brain — api run per turn	only during a turn (scale-to-zero)	traffic
Hands — worker	only during a task (stops on idle)	active tasks

This is a control-plane / data-plane split by lifecycle, not a breakup into many microservices. The pieces that deploy are covered in The pieces.

Where the agent's state lives

Because the brain and hands disappear, all state lives outside them, so any run can pick up where the last left off:

• Postgres — agents, sessions, tasks, messages, billing.
• Object storage — files and artifacts the agent produces.
• Vector + graph — knowledge and long-term memory (via LightRAG).
• Redis — the task queue, events, and locks.

Go deeper

• The pieces — the four things that actually deploy.
• Runtime model — the precise execution model.
• Layered slices — how the code is grouped.
• Glossary — any term you hit here, defined plainly.