Choosing an Agent Topology

An agent topology assigns identity, memory, conversations, tools, and shared files across an application. The central rule is simple: use one agent wherever identity and long-term memory should be shared. Use separate agents wherever those things should remain independent.

In Letta's state model, every conversation on an agent shares that agent's memory. A new conversation separates message threads. It is not a privacy or tenancy boundary.

Choose the boundary before the count

The useful question is not “How many agents should this application have?” Ask which experiences should change the same future behavior.

Topology	Shared identity and memory	Separate message history	Best fit
One agent, one main conversation	Yes	No	Personal partner, continuous work thread
One agent, several conversations	Yes	Yes	Parallel topics for one person or role
One agent per user	No	Yes	Personalized products with user-specific memory
Several role agents	No	Yes	Independent responsibilities, tools, or policies
Several agents with shared memory	Shared files only	Yes	A team working from common plans or knowledge

The table separates two ideas that are easy to blur. Conversations organize interaction with one identity. Shared memory repositories let independent identities work on common files.

One agent with one main conversation

Use one main conversation when the work benefits from a continuous thread and topic boundaries do not help the user. A personal research partner or project collaborator often begins here.

This topology has the fewest routing decisions. It also concentrates context, so the application's retrieval and compaction behavior must keep long histories usable.

One agent with several conversations

Use several conversations when one agent should remember across distinct threads. Product planning, email, and research can each have their own conversation while sharing the same preferences and long-term memory.

The conversation guide treats the split as a user preference rather than a correctness rule. Long threads can compact and continue. Start a new conversation to separate work, not because the old thread reached an arbitrary age.

Do not use conversations to separate users who should not share memory. A fact learned in one conversation can shape another conversation on the same agent.

One agent per user

Use a separate agent for each user when personalization should accumulate independently. Store the user-to-agent mapping in application state, and route every request through the authenticated user rather than an agent ID supplied by the client.

const agentId = await userAgents.requireAgentFor(authenticatedUser.id);
const conversationId = await threads.requireConversation({
  agentId,
  applicationThreadId,
});

await using session = client.resumeSession(conversationId, sessionOptions);

This topology gives each user an independent MemFS and conversation set. The application still must enforce access control around the mapping, tools, repositories, and execution environments. Separate agents do not repair a caller that can request someone else's agent ID.

Several agents for distinct roles

Create separate agents when responsibilities need different identities, memories, tools, or authority. A researcher and a publisher may work for the same user while remaining separate agents. The researcher can accumulate source judgment without inheriting publication credentials; the publisher can enforce a narrow release procedure without absorbing every research thread.

Role agents should exchange explicit artifacts rather than assume shared interior state. A report, task packet, source bundle, or proposed change is easier to inspect than an informal handoff that depends on one agent impersonating another.

Avoid creating a new agent for every temporary task. If no identity or memory should accumulate, use deterministic code, a one-shot prompt, or a new conversation on an existing agent. Agent proliferation creates routing, cleanup, and evaluation work without necessarily creating useful specialization.

Several agents with shared memory

Shared memory gives cloud-hosted agents access to the same organization-owned Git repository. Each agent keeps its own MemFS. The shared repository holds common files such as plans, product knowledge, research, or team conventions.

Choose the attachment lifetime deliberately:

• session resources attach a repository for the life of one SDK session;
• client.agents.repositories.attach() keeps the repository attached until explicit detachment.

Shared memory is collaborative storage, not merged identity. Agents must commit and push changes, and other agents must synchronize before they observe those commits. Use content-hash preconditions or Git review when concurrent edits should fail rather than overwrite each other.

Do not place material in a shared repository unless every attached agent should be able to retrieve it. Public and Private Knowledge explains why filtering after retrieval is too late for sensitive context.

A default progression

Begin with one agent and one conversation. Add conversations when thread separation improves navigation. Split into separate agents when memory, identity, tools, or authority need different owners. Add shared memory only when independent agents need a common working surface.

This progression keeps topology changes tied to an observed boundary. “Multi-agent” is not a quality level. Sometimes it is simply several agents discovering, at great expense, that they all needed the same file.

Your First Persistent Agent provides the smallest runnable application. Agent Authority and Effects covers the permission and effect boundaries that each topology still needs.