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

# Multi-Agent Context Policies

> Context isolation and sharing policies for multi-agent orchestration

The `MultiAgentContextManager` provides per-agent context isolation with controlled sharing policies for multi-agent workflows.

## Quick Start

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import (
    MultiAgentContextManager,
    ContextPolicy,
    ContextShareMode,
    ToolShareMode,
)

# Create multi-agent manager
manager = MultiAgentContextManager()

# Get per-agent managers
agent1_ctx = manager.get_agent_manager("researcher")
agent2_ctx = manager.get_agent_manager("writer")

# Set sharing policy for handoffs
policy = ContextPolicy(
    share=True,
    share_mode=ContextShareMode.SUMMARY,
    max_tokens=5000,
)
manager.set_agent_policy("writer", policy)
```

## Architecture

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TD
    subgraph "Multi-Agent Orchestrator"
        A[Agent 1: Researcher] --> B{Handoff}
        B --> C[Agent 2: Writer]
        C --> D{Handoff}
        D --> E[Agent 3: Editor]
    end
    
    subgraph "Context Isolation"
        F[Agent 1 Context<br/>Isolated]
        G[Agent 2 Context<br/>Isolated]
        H[Agent 3 Context<br/>Isolated]
    end
    
    subgraph "Shared Context"
        I[Summary/Full<br/>Based on Policy]
    end
    
    A --> F
    C --> G
    E --> H
    B --> I
    D --> I
    I -.->|Policy: share_mode| G
    I -.->|Policy: share_mode| H
```

## 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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# View multi-agent context stats
praisonai run agents.yaml
> /context stats

# Shows per-agent breakdown
```

## Best Practices

1. **Default to isolation** - Only share when necessary
2. **Use summaries** - Full context sharing is expensive
3. **Set token limits** - Always bound shared context
4. **Protect recent turns** - Keep last few turns for continuity
5. **Monitor per-agent** - Track each agent's usage separately