Agent System Overview

The Agent system is the AI brain of OpenClaw -- responsible for interacting with large language models, executing tool calls, managing streaming output, and maintaining conversation context.

Source Location

src/agents/                             # ~312 files
├── pi-embedded-subscribe.ts           # Agent execution main entry
├── pi-embedded-subscribe.types.ts     # Parameter type definitions
├── pi-embedded-subscribe.handlers.tools.ts  # Tool call handling
├── pi-embedded-helpers.ts             # Helper functions
├── pi-tools.ts                        # Tool definitions and registration
├── pi-tool-policy.ts                  # Tool policies
├── pi-session.ts                      # Agent sessions
├── pi-models.ts                       # Model configuration
├── pi-streaming.ts                    # Streaming processing
├── pi-context.ts                      # Context management
└── ...                                # Additional modules

Core Flow

Key Concepts

Concept	Description	Source File
Agent Session	AI conversation session	pi-session.ts
Embedded Subscribe	Agent execution main loop	pi-embedded-subscribe.ts
Block Chunker	Message merging and chunking	pi-embedded-subscribe.ts
Tool Factory	Tool registration and policies	pi-tools.ts
Delta Buffer	Streaming delta buffer	pi-embedded-subscribe.ts

Agent Execution Model

Agent execution is a loop-based process:

In each iteration:

1. Send the user message (and context) to the AI model
2. Receive streaming response deltas
3. If the model requests tool calls, execute the tools and feed results back to the model
4. Repeat until the model produces a final reply

Chapter Navigation

1. Agent Runtime -- subscribeEmbeddedPiSession deep dive
2. Tool Calls -- Tool definitions, policies, execution
3. Streaming -- Delta buffering, block merging, callbacks