= { /** * New elements that were not previously present */ newElements?: Partial
; /** * Elements that should be updated */ updateElements?: Partial
; /** * Elements that should be removed * Use "_DELETE_" as the value to mark for deletion */ removeElements?: Partial
; /** * Optional reasoning for the changes */ reasoning?: string; } ``` ### Working with Arrays For array mutations, the framework uses a position-preserving approach: #### Deleting Array Elements ```typescript // Original array { items: [ { id: '1', value: 'keep' }, { id: '2', value: 'delete this' }, { id: '3', value: 'keep' } ] } // Change request to delete second item { removeElements: { items: [ {}, // Keep first item (empty object) "_DELETE_", // Delete second item {} // Keep third item ] } } // Result { items: [ { id: '1', value: 'keep' }, { id: '3', value: 'keep' } ] } ``` #### Updating Array Elements ```typescript // Update specific array elements { updateElements: { items: [ {}, // No change to first item { value: 'updated' }, // Update second item {} // No change to third item ] } } ``` ## Architecture ### Framework-Level Responsibility State management is a core framework responsibility, not delegated to agent types: 1. **BaseAgent** handles all state mutations 2. **PayloadManager** applies change requests with validation 3. **Agent Types** only need to return change requests 4. All agents automatically benefit from safe state management ### Flow of State Changes ```mermaid graph TD A[Agent Executes Prompt] --> B[Returns AgentPayloadChangeRequest] B --> C[BaseAgent Receives Changes] C --> D[PayloadManager.applyAgentChangeRequest] D --> E[Validate Changes] E --> F[Apply Changes Safely] F --> G[Update PayloadAtEnd] G --> H[Pass to Next Step] style C fill:#f9f,stroke:#333,stroke-width:2px style D fill:#bbf,stroke:#333,stroke-width:2px ``` ### Integration Points 1. **Agent Types**: Return `payloadChangeRequest` in their response 2. **BaseAgentNextStep**: Contains `payloadChangeRequest` instead of full payload 3. **BaseAgent.executePromptStep**: Applies changes using PayloadManager 4. **Sub-Agent Execution**: Applies changes with upstream guardrails ## PayloadManager Implementation The `PayloadManager` class provides the core state management functionality: ### Key Methods #### applyAgentChangeRequest ```typescript public applyAgentChangeRequest
( originalPayload: P, changeRequest: AgentPayloadChangeRequest
, options?: { validateChanges?: boolean; logChanges?: boolean; agentName?: string; } ): { result: P; applied: { additions: number; updates: number; deletions: number; }; warnings: string[]; } ``` #### applySubAgentChangeRequest ```typescript public applySubAgentChangeRequest
( parentPayload: P, changeRequest: AgentPayloadChangeRequest
,
upstreamPaths: string[],
subAgentName: string
): {
result: P;
applied: { additions: number; updates: number; deletions: number; };
warnings: string[];
blocked: number;
}
```
### Processing Order
1. **Arrays**: Process all operations in a single pass to maintain index alignment
2. **Objects**: Process deletions, updates, and additions
3. **Nested Changes**: Recursively process even when parent has `{}`
### Deep Recursive Processing
The system handles nested changes correctly:
```typescript
// Even if an array element is marked with {} (keep)
// the system still checks for nested changes
{
removeElements: {
users: [
{
preferences: {
theme: "_DELETE_" // Delete nested property
}
},
{}, // Keep second user as-is
]
}
}
```
## Benefits
### 1. Prevents Data Loss
- LLMs sometimes truncate long responses with "..." or "and more"
- Change-based approach ensures data is never accidentally lost
- Framework validates all mutations
### 2. Token Efficiency
- Only changes are transmitted, not full state
- Dramatic reduction in prompt tokens
- Cost savings on LLM API calls
### 3. Explicit Intent
- Clear what the agent intends to change
- Easier to debug and trace state mutations
- Better audit trail
### 4. Consistency
- All agents use the same state management pattern
- No variation between agent type implementations
- Predictable behavior across the system
## Examples
### Basic State Update
```typescript
// Agent wants to update analysis results
{
updateElements: {
analysis: {
sentiment: 'positive',
score: 0.85
}
},
reasoning: 'Sentiment analysis completed'
}
```
### Complex Nested Changes
```typescript
// Agent making multiple types of changes
{
newElements: {
metrics: {
performance: { cpu: 45, memory: 72 }
}
},
updateElements: {
status: 'processing',
items: [
{ status: 'complete' }, // Update first item
{}, // No change to second
{ status: 'pending' } // Update third item
]
},
removeElements: {
debug: {
logs: "_DELETE_"
}
},
reasoning: 'Updated processing status and metrics'
}
```
### Sub-Agent State Management
Sub-agents use the same pattern, but changes are filtered through upstream paths:
```typescript
// Sub-agent returns changes
const changeRequest = {
updateElements: {
research: { status: 'complete' },
unauthorized: { hack: 'attempt' } // Will be blocked
}
};
// Applied with guardrails
const result = payloadManager.applySubAgentChangeRequest(
parentPayload,
changeRequest,
['research.*'], // Only research path allowed
'ResearchAgent'
);
// result.blocked = 1 (unauthorized change blocked)
```
## Best Practices
### 1. Atomic Changes
Make related changes together in a single request:
```typescript
// Good: Atomic operation
{
updateElements: {
order: { status: 'shipped' },
inventory: { quantity: 45 }
}
}
// Avoid: Separate requests for related changes
```
### 2. Clear Reasoning
Always include reasoning for changes:
```typescript
{
updateElements: { status: 'failed' },
reasoning: 'API endpoint returned 503 error after 3 retries'
}
```
### 3. Preserve Array Order
When modifying arrays, include all elements to maintain order:
```typescript
// Correct: All elements included
{
removeElements: {
tasks: [{}, "_DELETE_", {}, {}] // Delete only second element
}
}
// Wrong: Missing elements
{
removeElements: {
tasks: ["_DELETE_"] // Ambiguous which element
}
}
```
### 4. Use Type Safety
Leverage TypeScript generics for type-safe changes:
```typescript
interface MyPayload {
user: { name: string; age: number };
settings: { theme: string };
}
const changes: AgentPayloadChangeRequest