# rajib76/agent_dev_kit architecture

> Architecture diagram of the GitHub repository rajib76/agent_dev_kit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rajib76/agent_dev_kit
- Repository: https://github.com/rajib76/agent_dev_kit

## Overview

1. **Repository purpose**
   - This is a small Python playground for an “agent development kit”: it appears designed to demonstrate different agent orchestration patterns rather than ship a single end-user application.
   - The README is minimal, so the architecture is best understood from the module layout and naming.

2. **Top-level shape**
   - The repo is organized around multiple self-contained agent patterns:
     - `sequential_agent`
     - `parallel_agent`
     - `looping_agent`
     - `multi_agent`
     - `chat_transcript`
     - `examples`
   - Each package likely isolates one orchestration style, making the codebase a collection of reference implementations.

3. **Entry points and shared conventions**
   - There is a root-level `agent.py`, which likely serves as a convenience entry point or top-level demo runner.
   - Each package also has its own `agent.py`, suggesting each subsystem can be executed or imported independently.
   - The `__init__.py` files indicate these are intended as importable Python packages.

4. **Sequential orchestration subsystem**
   - `sequential_agent/agent.py` likely implements a linear pipeline where agent steps run in order and each step consumes the prior output.
   - This is the simplest control-flow boundary in the repo: one agent action feeds the next without branching or concurrency.
   - It likely serves as the baseline pattern for comparing more advanced flows.

5. **Parallel orchestration subsystem**
   - `parallel_agent/agent.py` is the concurrency-oriented package.
   - `parallel_agent/transcript.py` suggests it captures or merges outputs from multiple parallel agent runs into a single transcript or history.
   - The important architectural boundary here is aggregation: independent agent branches produce outputs that must be reconciled into a unified result.

6. **Looping / iterative agent subsystem**
   - `looping_agent/agent.py` likely models repeated reasoning or tool-use cycles until a stopping condition is met.
   - This package represents a control loop boundary, where the agent can continue acting based on its own intermediate outputs.
   - It contrasts with the sequential package by allowing repeated passes over the same task.

7. **Multi-agent / hierarchical orchestration**
   - `multi_agent/agent.py` and `examples/hierarchial_agent_with_sub_agents.py` indicate a supervisor–subagent style architecture.
   - The main agent likely delegates work to specialized sub-agents and then synthesizes their responses.
   - This creates a clear delegation boundary: coordination logic in one place, task execution in subordinate agents.

8. **Conversation and transcript handling**
   - `chat_transcript/agent.py` and `parallel_agent/transcript.py` suggest transcript management is a reusable concern.
   - The system likely records message history, intermediate steps, and possibly tool calls to support debugging or follow-up turns.
   - In architecture terms, transcript state is a shared data layer that crosses agent boundaries.

9. **Examples as scenario drivers**
   - The `examples/` package contains scenario-specific demonstrations:
     - `adk_agent_with_tool.py`
     - `hierarchial_agent_with_sub_agents.py`
     - `human_in_the_loop.py`
     - `human_in_the_loop_follow_up.py`
     - `session_management.py`
     - `state_management.py`
   - These are not core subsystems; they are integration examples showing how the agent patterns behave under different interaction models.

10. **Human-in-the-loop boundary**
   - The two `human_in_the_loop` examples show that some flows intentionally pause for external input before continuing.
   - That implies the architecture supports interruption and resumption, which is a key distinction from fully automated loops.
   - This is important for diagramming because the human is part of the control flow, not just an external consumer.

11. **Session and state management**
   - `session_management.py` and `state_management.py` indicate the repo distinguishes between conversational session context and internal agent state.
   - Session state likely spans multiple turns, while task state is more local to a specific run or branch.
   - These are important persistence boundaries for any diagram: what survives across turns versus what is transient.

12. **Tool integration**
   - `adk_agent_with_tool.py` shows that agents can call out to tools or functions during execution.
   - In the architecture, tools are external capability providers attached to agent logic, not separate subsystems.
   - This implies a control flow of: user/input → agent reasoning → tool invocation → returned result → agent continuation.

13. **Likely dependency structure**
   - The repo looks intentionally lightweight: mostly Python modules and examples, with no visible web server, database, or message broker in the tree.
   - `requirements.txt` is the main clue that external dependencies exist, but the architecture itself appears centered on in-process Python execution.
   - That means the primary boundaries are logical orchestration boundaries, not infrastructure boundaries.

14. **How to draw the diagram**
   - Model the repo as a set of agent-pattern modules around a shared conversation/transcript concept.
   - Show examples as consumers of those modules.
   - Highlight control-flow variations: sequential, parallel, looping, multi-agent delegation, and human-in-the-loop pauses.
   - If needed, treat the root `agent.py` as the top-level convenience or launcher path into the package-level implementations.

Main entry points: [`agent.py`](https://github.com/rajib76/agent_dev_kit/blob/main/agent.py) (Root agent), [`chat_transcript/agent.py`](https://github.com/rajib76/agent_dev_kit/blob/main/chat_transcript/agent.py) (Chat transcript), [`multi_agent/agent.py`](https://github.com/rajib76/agent_dev_kit/blob/main/multi_agent/agent.py) (Multi-agent), [`sequential_agent/agent.py`](https://github.com/rajib76/agent_dev_kit/blob/main/sequential_agent/agent.py) (Sequential)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core patterns"]
  node_root_agent["Root agent<br/>entrypoint<br/>[agent.py]"]
  node_sequential_agent["Sequential<br/>orchestration<br/>[agent.py]"]
  node_parallel_agent["Parallel<br/>orchestration<br/>[agent.py]"]
  node_parallel_transcript["Branch transcript<br/>aggregation<br/>[transcript.py]"]
  node_looping_agent["Looping<br/>orchestration<br/>[agent.py]"]
  node_multi_agent["Multi-agent<br/>delegation<br/>[agent.py]"]
  node_chat_transcript["Chat transcript<br/>conversation<br/>[agent.py]"]
end

subgraph group_examples["Examples"]
  node_tool_example["Tool demo<br/>example"]
  node_hierarchical_example["Hierarchical demo<br/>example"]
  node_hitl_example["Human-in-loop<br/>example"]
  node_hitl_followup["Follow-up loop<br/>example"]
end

subgraph group_crosscutting["Cross-cutting"]
  node_human(("Human input<br/>external actor"))
  node_tooling{{"Tool calls<br/>integration"}}
  node_session_state[("Session state<br/>state boundary")]
  node_task_state[("Task state<br/>state boundary")]
end

node_root_agent -->|"launches"| node_sequential_agent
node_root_agent -->|"launches"| node_parallel_agent
node_root_agent -->|"launches"| node_looping_agent
node_root_agent -->|"launches"| node_multi_agent
node_root_agent -->|"uses"| node_chat_transcript
node_parallel_agent -->|"aggregates"| node_parallel_transcript
node_multi_agent -->|"records"| node_chat_transcript
node_sequential_agent -->|"records"| node_chat_transcript
node_looping_agent -->|"records"| node_chat_transcript
node_tool_example -->|"calls"| node_tooling
node_hierarchical_example -->|"demonstrates"| node_multi_agent
node_hitl_example -->|"pauses for"| node_human
node_hitl_followup -->|"resumes with"| node_human
node_session_state -->|"separates from"| node_chat_transcript
node_task_state -->|"supports"| node_looping_agent
node_tooling -->|"extends"| node_sequential_agent
node_tooling -->|"extends"| node_multi_agent
node_human -->|"updates"| node_chat_transcript

click node_root_agent "https://github.com/rajib76/agent_dev_kit/blob/main/agent.py"
click node_sequential_agent "https://github.com/rajib76/agent_dev_kit/blob/main/sequential_agent/agent.py"
click node_parallel_agent "https://github.com/rajib76/agent_dev_kit/blob/main/parallel_agent/agent.py"
click node_parallel_transcript "https://github.com/rajib76/agent_dev_kit/blob/main/parallel_agent/transcript.py"
click node_looping_agent "https://github.com/rajib76/agent_dev_kit/blob/main/looping_agent/agent.py"
click node_multi_agent "https://github.com/rajib76/agent_dev_kit/blob/main/multi_agent/agent.py"
click node_chat_transcript "https://github.com/rajib76/agent_dev_kit/blob/main/chat_transcript/agent.py"
click node_session_state "https://github.com/rajib76/agent_dev_kit/blob/main/examples/session_management.py"
click node_task_state "https://github.com/rajib76/agent_dev_kit/blob/main/examples/state_management.py"
click node_tool_example "https://github.com/rajib76/agent_dev_kit/blob/main/examples/adk_agent_with_tool.py"
click node_hierarchical_example "https://github.com/rajib76/agent_dev_kit/blob/main/examples/hierarchial_agent_with_sub_agents.py"
click node_hitl_example "https://github.com/rajib76/agent_dev_kit/blob/main/examples/human_in_the_loop.py"
click node_hitl_followup "https://github.com/rajib76/agent_dev_kit/blob/main/examples/human_in_the_loop_follow_up.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_root_agent,node_sequential_agent,node_parallel_agent,node_parallel_transcript,node_looping_agent,node_multi_agent,node_chat_transcript toneBlue
class node_tool_example,node_hierarchical_example,node_hitl_example,node_hitl_followup toneAmber
class node_human,node_tooling,node_session_state,node_task_state toneMint
```

## Components

### Core patterns

Primary agent orchestration modules and shared transcript handling.

- [Root agent](https://github.com/rajib76/agent_dev_kit/blob/main/agent.py): entrypoint · Top-level convenience entry point for the playground. · `agent.py`
- [Sequential](https://github.com/rajib76/agent_dev_kit/blob/main/sequential_agent/agent.py): orchestration · Linear agent flow where each step feeds the next. · `sequential_agent/agent.py`
- [Parallel](https://github.com/rajib76/agent_dev_kit/blob/main/parallel_agent/agent.py): orchestration · Concurrent agent flow that runs branches in parallel. · `parallel_agent/agent.py`
- [Branch transcript](https://github.com/rajib76/agent_dev_kit/blob/main/parallel_agent/transcript.py): aggregation · Collects and reconciles outputs from parallel branches. · `parallel_agent/transcript.py`
- [Looping](https://github.com/rajib76/agent_dev_kit/blob/main/looping_agent/agent.py): orchestration · Iterative agent flow with repeated reasoning or tool-use cycles. · `looping_agent/agent.py`
- [Multi-agent](https://github.com/rajib76/agent_dev_kit/blob/main/multi_agent/agent.py): delegation · Supervisor-style orchestration over specialized sub-agents. · `multi_agent/agent.py`
- [Chat transcript](https://github.com/rajib76/agent_dev_kit/blob/main/chat_transcript/agent.py): conversation · Conversation history and transcript handling for agent runs. · `chat_transcript/agent.py`

### Examples

Scenario drivers that demonstrate the patterns in different interaction modes.

- [Tool demo](https://github.com/rajib76/agent_dev_kit/blob/main/examples/adk_agent_with_tool.py): example · Shows an agent invoking a tool during execution. · `examples/adk_agent_with_tool.py`
- [Hierarchical demo](https://github.com/rajib76/agent_dev_kit/blob/main/examples/hierarchial_agent_with_sub_agents.py): example · Demonstrates a supervisor coordinating sub-agents. · `examples/hierarchial_agent_with_sub_agents.py`
- [Human-in-loop](https://github.com/rajib76/agent_dev_kit/blob/main/examples/human_in_the_loop.py): example · Demonstrates pausing for human input before continuing. · `examples/human_in_the_loop.py`
- [Follow-up loop](https://github.com/rajib76/agent_dev_kit/blob/main/examples/human_in_the_loop_follow_up.py): example · Demonstrates resuming a human-in-the-loop conversation. · `examples/human_in_the_loop_follow_up.py`

### Cross-cutting

Conceptual runtime concerns that span multiple agent flows.

- **Human input**: external actor · External participant that can interrupt and resume a flow.
- **Tool calls**: integration · External function or tool execution attached to agent reasoning.
- [Session state](https://github.com/rajib76/agent_dev_kit/blob/main/examples/session_management.py): state boundary · Conversation-scoped context that persists across turns. · `examples/session_management.py`
- [Task state](https://github.com/rajib76/agent_dev_kit/blob/main/examples/state_management.py): state boundary · Run-local or branch-local state used within a specific agent task. · `examples/state_management.py`

## Connections

- Root agent → Sequential: launches · Root entry point can hand off to the sequential pattern.
- Root agent → Parallel: launches · Root entry point can hand off to the parallel pattern.
- Root agent → Looping: launches · Root entry point can hand off to the looping pattern.
- Root agent → Multi-agent: launches · Root entry point can hand off to the multi-agent pattern.
- Root agent → Chat transcript: uses · Root entry point can surface transcript handling.
- Parallel → Branch transcript: aggregates · Parallel execution produces branch outputs that are merged into a transcript.
- Multi-agent → Chat transcript: records · Delegated conversations are tracked in transcript form.
- Sequential → Chat transcript: records · Sequential runs preserve conversation history.
- Looping → Chat transcript: records · Iterative runs preserve intermediate turns and reasoning.
- Tool demo → Tool calls: calls · The example demonstrates a tool invocation boundary.
- Hierarchical demo → Multi-agent: demonstrates · Example drives the supervisor/sub-agent architecture.
- Human-in-loop → Human input: pauses for · The flow intentionally waits for human input.
- Follow-up loop → Human input: resumes with · The follow-up example continues after human input.
- Session state → Chat transcript: separates from · Session-scoped context is distinct from transcript history.
- Task state → Looping: supports · Task-local state is useful for iterative control flow.
- Tool calls → Sequential: extends · Tool use can be embedded in a linear orchestration.
- Tool calls → Multi-agent: extends · Tools can also be used inside delegated sub-agent work.
- Human input → Chat transcript: updates · Human turns become part of the conversation record.
