Your agent knows your user's name. It remembers they asked about Tokyo yesterday. It pulls up their order history without being asked.

That's not magic — that's context management.

Get it right, and the agent feels intelligent and helpful. Get it wrong, and users repeat themselves constantly while your agent stumbles around clueless.

Let's dive deep into how ADK handles context.

The Three Layers of Context

In ADK, context flows from three sources:

1. Agent Instructions — The persona, rules, and behavior you define upfront

2. Session State — Data that persists across messages in a conversation

3. Tool Context — Information passed to and from tool executions

Master all three and your agent becomes genuinely smart.

Layer 1: Agent Instructions

This is the foundation — your agent's personality and ground rules:

These instructions are included in every LLM call. Think of them as the agent's constant background knowledge.

Layer 2: Session State

This is where conversations come alive. Session state stores data that persists across multiple messages:

Now the agent can reference Sarah by name, knows her phone number, and tracks her pending appointment — all without her repeating anything.

Layer 3: Tool Context

Tools get their own context object that provides access to session state and more:

The ToolContext bridges your tools and your session. Tools can read and write state, making the whole system work together.

Putting It All Together

Here's a complete example showing all three layers working in harmony:

Context Best Practices

Keep state lightweight. Store IDs and keys, not entire objects. Fetch details when needed.

Use clear key names. Prefix by category: user_name, order_id, pref_language.

Don't overload instructions. Keep them focused. Move dynamic data to session state instead.

Clean up stale state. Remove temporary data when it's no longer needed.

Wrapping Up

Context management is what separates a clever demo from a production-ready agent. The three layers work together: instructions set the stage, session state tracks the conversation, and tool context bridges your code and your AI.