> For the complete documentation index, see [llms.txt](https://suzuna.gitbook.io/whitepaper/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://suzuna.gitbook.io/whitepaper/ai-agent-architecture.md).

# AI Agent Architecture

### A focused architecture for wallet intelligence

SUZUNA is designed as a lightweight, read-oriented system. Each user interacts with a wallet-specific agent through Telegram, while the underlying architecture separates user interaction, agent context, blockchain data retrieval, and AI analysis.

The core architecture is:

**User → Telegram Bot → SUZUNA Agent → BNB Chain Data Layer → AI Analysis Layer → Telegram Response**

#### User Layer

The user interacts with SUZUNA entirely through the **SUZUNA Telegram Bot**.

The Telegram interface handles agent deployment and natural-language queries. Users do not need to interact directly with blockchain explorers or technical infrastructure.

#### Telegram Bot Layer

The Telegram bot acts as the primary interface between the user and SUZUNA.

It receives user requests, identifies the relevant agent, and passes the request into the SUZUNA agent layer.

Telegram is an interface layer only. It does not hold wallet assets or provide the agent with permission to perform blockchain transactions.

#### SUZUNA Agent Layer

Each deployed agent is associated with one public BNB Chain wallet address.

The agent maintains the product-level context required to answer questions about that wallet. It does not contain private keys and does not have authority to sign or execute transactions.

When a user asks a question, the agent determines what wallet information is relevant to the request.

#### BNB Chain Data Layer

The BNB Chain Data Layer provides the underlying blockchain information required for analysis.

Depending on the query, SUZUNA can retrieve:

* BNB balance
* Token balances
* Incoming transactions
* Outgoing transactions
* Token transfers
* Contract interactions
* Transaction history

Data is retrieved when required rather than requiring SUZUNA to permanently maintain the complete blockchain history of every wallet.

#### AI Analysis Layer

The **AI Analysis Layer** receives the relevant wallet data together with the user's request.

Its role is to interpret the available blockchain activity and produce a coherent natural-language response.

The AI layer does not independently control the wallet or perform blockchain actions. It operates on the information retrieved by the data layer.

#### Response Layer

After analysis, the response is returned to the user through Telegram.

The result is presented as an understandable explanation rather than a raw collection of blockchain records.

#### Separation of Responsibilities

SUZUNA keeps the main system responsibilities separated:

| Layer                | Primary responsibility                 |
| -------------------- | -------------------------------------- |
| Telegram             | User interaction                       |
| SUZUNA Agent         | Wallet-specific context                |
| BNB Chain Data Layer | On-chain data retrieval                |
| AI Analysis Layer    | Interpretation and response generation |
| Telegram Response    | Delivery of the result                 |

This separation allows SUZUNA to remain focused on wallet intelligence while keeping the agent itself read-only and independent from wallet custody or transaction execution.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://suzuna.gitbook.io/whitepaper/ai-agent-architecture.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.