Tasks and Agents

MagicFrog separates two things that are often blurred together: the task — the work being done — and the agent — the named worker doing it. Tasks carry the history and state; agents carry identity, role, persona, and memory. The two surfaces are managed independently, and an agent can participate in any number of tasks at once.

Tasks

A task is the work itself, independent of the agents working on it:

• identity: the task's ID, title, and project
• status: running, idle, or archived
• the last completed run's outcome

The task surface is separate from agent management. Listing, opening, and configuring tasks never touches agent definitions.

Agents

An agent is a named profile: a durable identity that survives across tasks and sessions, independent of any one conversation. Profiles are local Markdown documents — one file per agent under agent-profiles/ in the MagicFrog data directory — so a text editor is a sufficient profile client:

---
name: "Release engineer"
role: "Owns release preparation and changelog accuracy"
status: active
---
You prepare releases. Check the changelog against merged changes before
proposing a version bump.

• id starts with agp_ and is stable across machines.
• name and role are the identity shown wherever the agent participates.
• status is active or archived — archiving retires an agent without deleting its history.
• The document body is the persona: the working instructions the agent carries into every task.
• summary is the agent's rolling work summary; it is updated as work progresses and is reusable across tasks.
• Every profile carries a revision; updates that supply the expected revision fail instead of overwriting a change made elsewhere.

The same profile works locally and in the cloud.

The screenshot shows the real Settings → Agents page: organization agents are read-only and distributed by your organization; personal agents are managed locally. The image captures the empty state as-is, with nothing staged.

The built-in agent: Pi

Pi is the built-in default agent, so a fresh install can run work without adding another runtime. It follows the same rules as every other agent: explicit targets, permissions, capability checks, and audit all apply unchanged. Third-party agents register through the same entry point; changing agents does not change which tools exist or how they are authorized.

Joining a task

Association is explicit in both directions. Pulling an agent into a task creates a roster member; nothing joins implicitly, and removing an agent is likewise an explicit operation.

• Roles: every member carries a role. owner — at most one at a time — is the task owner; other participant roles are free-form and shown in the task's participant list, so every participant can see who holds what role.
• Join context: an agent pulled into a running task receives a summary of the task — the objective, earlier activity, and the most recent history — together with the participant list, delivered into the running conversation.
• Concurrency: several participants can work in the same running task; pulling another agent in does not pause or restart the conversation.
• Multiplicity: one agent can be on any number of task rosters at once. There is no exclusivity lock between tasks.
• Handing over: responsibility moves only through an explicit transfer from the current owner to an existing participant, and every handover is recorded in the task's transfer log. Ownership never drifts.
• Persistence: participant lists persist per task; on error the failure is explicit, never a silent reset to empty.

Mentioning a human

In a group task, an agent can address a human participant with an explicit @ reference. That mention becomes a pending event in the global event inbox: the agent asks by @-mentioning you, you answer on the card, and the reply is written back into the task's conversation.

Sharing inside a task

Everything a task owns lives in that task's own namespace — memory, files, artifacts, and triggers under the task's ID — so participants see each other's work inside the task without ever colliding with another task. Memory keeps the same convention: task-dimension notes under a task ID prefix belong to that task and are visible to its participants.

When a task ends, its resources follow their retention policy: the default keeps them for traceability, and an explicit cleanup reports an error if something cannot be removed — nothing is silently kept and nothing is pretend-deleted.

Memory and roaming for agents

Each named agent gets its own memory: the agent dimension of memory, isolated per agent ID, persisting preferences and role context across sessions. Agent profiles and their memory summaries sync across the machines signed in to your account, so a named agent is the same agent everywhere.