Multi-Agent Context Policies

Context isolation and sharing policies for multi-agent orchestration

from praisonaiagents import Agent

agent1 = Agent(name="agent-1", instructions="Handle research tasks.")
agent2 = Agent(name="agent-2", instructions="Handle writing tasks.")
agent1.start("Apply shared context policy across both agents.")

MultiAgentContextManager gives each agent isolated context with controlled sharing on handoffs.

The user hands off from a researcher agent to a writer; shared context policies control what crosses the boundary.

How It Works

Quick Start

1. Create the manager

   from praisonaiagents import MultiAgentContextManager
   
   manager = MultiAgentContextManager()
   researcher_ctx = manager.get_agent_manager("researcher")
   writer_ctx = manager.get_agent_manager("writer")
   
2. Set a handoff policy

   from praisonaiagents import ContextPolicy, ContextShareMode
   
   policy = ContextPolicy(
       share=True,
       share_mode=ContextShareMode.SUMMARY,
       max_tokens=5000,
   )
   manager.set_agent_policy("writer", policy)
   
3. Prepare handoff context

   shared = manager.prepare_handoff(
       from_agent="researcher",
       to_agent="writer",
       messages=researcher_messages,
   )
   result = writer_ctx.process(messages=shared + writer_messages)
   

Architecture

Context Policy

Share Modes

Mode	Description	Use Case
NONE	No context shared	Independent agents
SUMMARY	Summarized context	Reduce token usage
FULL	Full context (bounded)	Continuity needed

Tool Share Modes

Mode	Description
NONE	No tools shared
SAFE	Only safe tools shared
FULL	All tools shared

Policy Configuration

from praisonaiagents import ContextPolicy, ContextShareMode

policy = ContextPolicy(
    share=True,                           # Enable sharing
    share_mode=ContextShareMode.SUMMARY,  # Share as summary
    max_tokens=5000,                      # Cap shared tokens
    tools_share=ToolShareMode.SAFE,       # Share safe tools
    preserve_system=True,                 # Keep system prompts
    preserve_recent_turns=3,              # Keep last 3 turns
)

Handoff Preparation

# Prepare context for handoff
shared_context = manager.prepare_handoff(
    from_agent="researcher",
    to_agent="writer",
    messages=researcher_messages,
    policy=policy,  # Optional override
)

# shared_context contains messages to pass to writer
writer_ctx = manager.get_agent_manager("writer")
result = writer_ctx.process(
    messages=shared_context + writer_messages,
    system_prompt=writer_system_prompt,
)

Per-Agent Isolation

Each agent has isolated:

• Token budget
• Conversation history
• Optimization state
• Monitoring output

# Each agent tracks independently
agent1_ctx.process(messages=agent1_messages)
agent2_ctx.process(messages=agent2_messages)

# Get combined stats
stats = manager.get_combined_stats()
print(f"Agent 1 tokens: {stats['agents']['researcher']['ledger']['total']}")
print(f"Agent 2 tokens: {stats['agents']['writer']['ledger']['total']}")

Preventing Context Blow-up

Default policies prevent multiplicative context growth:

# Default: no sharing
default_policy = ContextPolicy()  # share=False

# With sharing, always bounded
bounded_policy = ContextPolicy(
    share=True,
    share_mode=ContextShareMode.SUMMARY,  # Compressed
    max_tokens=5000,                       # Hard limit
    preserve_recent_turns=3,               # Only recent
)

Integration with Workflow

from praisonaiagents import AgentTeam
from praisonaiagents import MultiAgentContextManager

# Create context manager
ctx_manager = MultiAgentContextManager()

# Create agents with context awareness
agents = AgentTeam(
    agents=[researcher, writer, editor],
    process="sequential",
)

# Context is managed per-agent automatically
# Handoffs use configured policies

CLI Usage

# View multi-agent context stats
praisonai run agents.yaml
> /context stats

# Shows per-agent breakdown

---

Best Practices

Default to isolation

Keep share=False until a handoff genuinely needs prior context — unbounded sharing multiplies tokens.

Prefer SUMMARY over FULL

ContextShareMode.SUMMARY keeps continuity without copying entire histories into every agent.

Always set max_tokens

Hard-cap shared context so downstream agents cannot inherit runaway message lists.

Preserve recent turns selectively

Use preserve_recent_turns=3 for continuity while still compressing older turns.

---

Related

Handoffs

Delegate tasks between agents with tool and context policies.

Context Manager

Single-agent budgeting and compaction facade.

Multi-Agent Pipelines

Sequential and parallel orchestration patterns.

Workflows

Route, parallel, and loop patterns for agent teams.