Agent Message Anatomy
Learning Headroom
Why Message Anatomy Matters
**Core idea**
Role information makes selective inspection and compression possible.
**Budget example**
Context limit: 1,000 tokens. Used: 760 tokens. Headroom: \(1{,}000-760=240\) tokens.
```mermaid
flowchart LR
A["Application"] --> B["Typed message sequence"]
B --> C["Headroom inspection"]
C --> D["Compress redundant content"]
D --> E["LLM provider"]
E --> F["Response"]
```
Five Message Roles
**Role distinctions**
- System: behavior or environment
- User: request or supplied information
- Assistant: generated reply or action
- Tool call: requested operation
- Tool result: returned data
**Classification**
The request `calculate({a: 7, b: 5})` is a tool call. The returned `{sum: 12}` is a tool result. They are different portions with different jobs.
```mermaid
flowchart TD
S["system: instructions"] --> U["user: request"]
U --> A["assistant: reply or action"]
A --> C["tool-call: operation plus ID"]
C --> R["tool-result: data plus matching ID"]
R --> A2["assistant: next reply"]
```
A Fully Labeled Sequence
**Temperature sequence**
Given city: Oslo. Goal: obtain temperature. The user asks; the assistant emits `get_weather({city: "Oslo"})` with ID `call_17`; the tool returns `{ "city": "Oslo", "celsius": 7 }`; the assistant concludes: `It is 7 degrees Celsius in Oslo.`
```mermaid
sequenceDiagram
participant S as System
participant U as User
participant A as Assistant
participant T as Tool
S->>A: Behavior instructions
U->>A: Temperature request
A->>T: get_weather, call_17
T-->>A: Oslo, 7 Celsius, call_17
A-->>U: Final answer
```
Tool Calls And Results
**Out-of-order results**
Call A asks for the blue cube. Call B asks for the red sphere. Result B arrives first, but its ID is B. Result A arrives second, but its ID is A. Therefore A maps to shelf 1 and B maps to shelf 2.
```mermaid
flowchart LR
A1["assistant tool-call A"] -. "tool_call_id = A" .-> R1["tool-result A: blue cube, shelf 1"]
A2["assistant tool-call B"] -. "tool_call_id = B" .-> R2["tool-result B: red sphere, shelf 2"]
```
Reading A Real Message Object
**Field-by-field check**
First object: role is `assistant`; `tool_calls` contains ID `call_17`; name is `get_weather`; argument is city `Oslo`. Second object: role is `tool`; ID is `call_17`. Equal IDs prove the match.
**Quick check**
If a tool object has `tool_call_id: "call_22"`, which assistant call does it answer? The assistant call whose `id` is exactly `call_22`.
Key Takeaways
**Recite these rules**
- System and user carry instructions or requests.
- Assistant produces replies or actions.
- Tool calls request operations; tool results return data.
- The structure supports repeated-wake analysis and headroom routing.
Back to course