# langchain-ai/ambient-agent-101 architecture

> Architecture diagram of the GitHub repository langchain-ai/ambient-agent-101, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/langchain-ai/ambient-agent-101
- Repository: https://github.com/langchain-ai/ambient-agent-101

## Overview

Ambient Agent 101 is a tutorial-backed email assistant that triages incoming messages, responds or notifies as appropriate, and can involve a human reviewer and retain learned preferences. The graph shows the documented workflow variants, tool integrations, Gmail ingestion, and optional evaluation. Source excerpts are partial, so uncertain internal routing and unsampled tool behavior are not represented.

Main entry points: [`src/email_assistant/email_assistant_hitl_memory_gmail.py`](https://github.com/langchain-ai/ambient-agent-101/blob/main/src/email_assistant/email_assistant_hitl_memory_gmail.py) (Gmail assistant), [`src/email_assistant/email_assistant.py`](https://github.com/langchain-ai/ambient-agent-101/blob/main/src/email_assistant/email_assistant.py) (Triage agent), [`src/email_assistant/email_assistant_hitl_memory.py`](https://github.com/langchain-ai/ambient-agent-101/blob/main/src/email_assistant/email_assistant_hitl_memory.py) (Memory assistant), [`src/email_assistant/tools/base.py`](https://github.com/langchain-ai/ambient-agent-101/blob/main/src/email_assistant/tools/base.py) (Tool registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Assistant workflows"]
  node_base_agent["Triage agent<br/>[email_assistant.py]"]
  node_hitl_agent["Human review"]
  node_memory_agent["Memory assistant"]
  node_gmail_agent["Gmail assistant"]
end

subgraph group_tools["Tools and integrations"]
  node_tool_registry["Tool registry<br/>[base.py]"]
  node_mock_email["Email tools<br/>[email_tools.py]"]
  node_calendar["Calendar tools<br/>[calendar_tools.py]"]
end

subgraph group_gmail["Gmail operations"]
  node_gmail_tools["Gmail tools<br/>[gmail_tools.py]"]
  node_ingest["Email ingestion<br/>[run_ingest.py]"]
  node_scheduler["Gmail scheduling<br/>[setup_cron.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_eval_data["Email examples<br/>[email_dataset.py]"]
  node_evaluation["Triage evaluation<br/>[evaluate_triage.py]"]
end

node_email_user(("Email user"))
node_llm(("Language model"))
node_reviewer(("Human reviewer"))
node_inbox["Agent Inbox"]
node_memory_store[("Preference store")]
node_gmail_api["Google APIs"]
node_langgraph_server["LangGraph server"]

node_email_user -->|"submits email"| node_base_agent
node_base_agent -->|"requests triage and response"| node_llm
node_base_agent -->|"gets tools"| node_tool_registry
node_base_agent -->|"invokes tools"| node_mock_email
node_base_agent -->|"invokes tools"| node_calendar
node_email_user -->|"submits email"| node_hitl_agent
node_hitl_agent -->|"requests review"| node_inbox
node_reviewer -->|"reviews actions"| node_inbox
node_hitl_agent -->|"requests response"| node_llm
node_hitl_agent -->|"gets tools"| node_tool_registry
node_email_user -->|"submits email"| node_memory_agent
node_memory_agent -->|"reads and updates preferences"| node_memory_store
node_memory_agent -->|"requests review"| node_inbox
node_memory_agent -->|"requests response"| node_llm
node_memory_agent -->|"gets tools"| node_tool_registry
node_email_user -->|"submits email"| node_gmail_agent
node_gmail_agent -->|"reads and updates preferences"| node_memory_store
node_gmail_agent -->|"requests review"| node_inbox
node_gmail_agent -->|"requests response"| node_llm
node_gmail_agent -->|"gets tools"| node_tool_registry
node_tool_registry -.->|"loads optionally"| node_gmail_tools
node_gmail_agent -->|"invokes Gmail tools"| node_gmail_tools
node_gmail_tools -->|"calls APIs"| node_gmail_api
node_ingest -->|"fetches messages"| node_gmail_api
node_ingest -->|"creates graph runs"| node_langgraph_server
node_scheduler -.->|"schedules ingestion"| node_gmail_api
node_eval_data -->|"provides examples"| node_evaluation
node_evaluation -->|"evaluates triage"| node_base_agent

click node_base_agent "https://github.com/langchain-ai/ambient-agent-101/blob/main/src/email_assistant/email_assistant.py"
click node_hitl_agent "https://github.com/langchain-ai/ambient-agent-101/blob/main/src/email_assistant/email_assistant_hitl.py"
click node_memory_agent "https://github.com/langchain-ai/ambient-agent-101/blob/main/src/email_assistant/email_assistant_hitl_memory.py"
click node_gmail_agent "https://github.com/langchain-ai/ambient-agent-101/blob/main/src/email_assistant/email_assistant_hitl_memory_gmail.py"
click node_tool_registry "https://github.com/langchain-ai/ambient-agent-101/blob/main/src/email_assistant/tools/base.py"
click node_mock_email "https://github.com/langchain-ai/ambient-agent-101/blob/main/src/email_assistant/tools/default/email_tools.py"
click node_calendar "https://github.com/langchain-ai/ambient-agent-101/blob/main/src/email_assistant/tools/default/calendar_tools.py"
click node_gmail_tools "https://github.com/langchain-ai/ambient-agent-101/blob/main/src/email_assistant/tools/gmail/gmail_tools.py"
click node_ingest "https://github.com/langchain-ai/ambient-agent-101/blob/main/src/email_assistant/tools/gmail/run_ingest.py"
click node_scheduler "https://github.com/langchain-ai/ambient-agent-101/blob/main/src/email_assistant/tools/gmail/setup_cron.py"
click node_eval_data "https://github.com/langchain-ai/ambient-agent-101/blob/main/eval/email_dataset.py"
click node_evaluation "https://github.com/langchain-ai/ambient-agent-101/blob/main/eval/evaluate_triage.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_base_agent,node_hitl_agent,node_memory_agent,node_gmail_agent,node_email_user,node_reviewer toneBlue
class node_tool_registry,node_mock_email,node_calendar,node_memory_store toneAmber
class node_gmail_tools,node_ingest,node_scheduler,node_gmail_api,node_langgraph_server toneMint
class node_eval_data,node_evaluation toneRose
class node_llm,node_inbox toneIndigo
```

## Components

### Assistant workflows

- [Triage agent](https://github.com/langchain-ai/ambient-agent-101/blob/main/src/email_assistant/email_assistant.py): `src/email_assistant/email_assistant.py`
- [Human review](https://github.com/langchain-ai/ambient-agent-101/blob/main/src/email_assistant/email_assistant_hitl.py): `src/email_assistant/email_assistant_hitl.py`
- [Memory assistant](https://github.com/langchain-ai/ambient-agent-101/blob/main/src/email_assistant/email_assistant_hitl_memory.py): `src/email_assistant/email_assistant_hitl_memory.py`
- [Gmail assistant](https://github.com/langchain-ai/ambient-agent-101/blob/main/src/email_assistant/email_assistant_hitl_memory_gmail.py): `src/email_assistant/email_assistant_hitl_memory_gmail.py`

### Tools and integrations

- [Tool registry](https://github.com/langchain-ai/ambient-agent-101/blob/main/src/email_assistant/tools/base.py): `src/email_assistant/tools/base.py`
- [Email tools](https://github.com/langchain-ai/ambient-agent-101/blob/main/src/email_assistant/tools/default/email_tools.py): `src/email_assistant/tools/default/email_tools.py`
- [Calendar tools](https://github.com/langchain-ai/ambient-agent-101/blob/main/src/email_assistant/tools/default/calendar_tools.py): `src/email_assistant/tools/default/calendar_tools.py`

### Gmail operations

- [Gmail tools](https://github.com/langchain-ai/ambient-agent-101/blob/main/src/email_assistant/tools/gmail/gmail_tools.py): `src/email_assistant/tools/gmail/gmail_tools.py`
- [Email ingestion](https://github.com/langchain-ai/ambient-agent-101/blob/main/src/email_assistant/tools/gmail/run_ingest.py): `src/email_assistant/tools/gmail/run_ingest.py`
- [Gmail scheduling](https://github.com/langchain-ai/ambient-agent-101/blob/main/src/email_assistant/tools/gmail/setup_cron.py): `src/email_assistant/tools/gmail/setup_cron.py`

### Evaluation

- [Email examples](https://github.com/langchain-ai/ambient-agent-101/blob/main/eval/email_dataset.py): `eval/email_dataset.py`
- [Triage evaluation](https://github.com/langchain-ai/ambient-agent-101/blob/main/eval/evaluate_triage.py): `eval/evaluate_triage.py`

### Other components

- **Email user**
- **Language model**
- **Human reviewer**
- **Agent Inbox**
- **Preference store**
- **Google APIs**
- **LangGraph server**

## Connections

- Email user → Triage agent: submits email
- Triage agent → Language model: requests triage and response
- Triage agent → Tool registry: gets tools
- Triage agent → Email tools: invokes tools
- Triage agent → Calendar tools: invokes tools
- Email user → Human review: submits email
- Human review → Agent Inbox: requests review
- Human reviewer → Agent Inbox: reviews actions
- Human review → Language model: requests response
- Human review → Tool registry: gets tools
- Email user → Memory assistant: submits email
- Memory assistant → Preference store: reads and updates preferences
- Memory assistant → Agent Inbox: requests review
- Memory assistant → Language model: requests response
- Memory assistant → Tool registry: gets tools
- Email user → Gmail assistant: submits email
- Gmail assistant → Preference store: reads and updates preferences
- Gmail assistant → Agent Inbox: requests review
- Gmail assistant → Language model: requests response
- Gmail assistant → Tool registry: gets tools
- Tool registry → Gmail tools: loads optionally
- Gmail assistant → Gmail tools: invokes Gmail tools
- Gmail tools → Google APIs: calls APIs
- Email ingestion → Google APIs: fetches messages
- Email ingestion → LangGraph server: creates graph runs
- Gmail scheduling → Google APIs: schedules ingestion
- Email examples → Triage evaluation: provides examples
- Triage evaluation → Triage agent: evaluates triage