# Understanding the Agentic Loop

> The three-layer architecture: Layer 1 (Simplified Agent), Layer 2 (Stateful Session), and Layer 3 (Transport Adapters).

- Repository: google-antigravity/antigravity-sdk-python
- GitHub: https://github.com/google-antigravity/antigravity-sdk-python
- Human wiki: https://grok-wiki.com/public/wiki/google-antigravity-antigravity-sdk-python-2abd361a7867
- Complete Markdown: https://grok-wiki.com/public/wiki/google-antigravity-antigravity-sdk-python-2abd361a7867/llms-full.txt

## Source Files

- `README.md`
- `google/antigravity/agent.py`
- `google/antigravity/conversation/conversation.py`
- `google/antigravity/connections/connection.py`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [google/antigravity/agent.py](google/antigravity/agent.py)
- [google/antigravity/conversation/conversation.py](google/antigravity/conversation/conversation.py)
- [google/antigravity/connections/connection.py](google/antigravity/connections/connection.py)
- [google/antigravity/connections/local/local_connection.py](google/antigravity/connections/local/local_connection.py)
- [google/antigravity/conversation/README.md](google/antigravity/conversation/README.md)
- [README.md](README.md)
</details>

# Understanding the Agentic Loop

The Google Antigravity SDK is built on a modular, three-layer architecture designed to decouple agent logic from session state and transport mechanics. This separation of concerns ensures that the "Agentic Loop"—the iterative cycle of reasoning, tool execution, and state management—remains robust, testable, and portable across different backends.

By organizing the SDK into three distinct layers, developers can choose the level of abstraction that fits their needs, from a "batteries-included" high-level Agent to low-level transport control. This architecture also facilitates the implementation of advanced features like session resumption, history compaction, and platform-agnostic safety policies.

## Architectural Blueprint

The architecture follows a nested dependency model where higher layers wrap lower ones to add specialized functionality.

```mermaid
graph TD
    subgraph Layer1["Layer 1: Agent (Lifecycle & Config)"]
        A[Agent Class] --> B[Hook Runner]
        A --> C[Tool Runner]
        A --> D[Trigger Runner]
        A --> L2
    end

    subgraph L2["Layer 2: Conversation (Stateful Session)"]
        E[Conversation Class] --> F[History Management]
        E --> G[Turn Tracking]
        E --> H[Usage Tracking]
        E --> L3
    end

    subgraph L3["Layer 3: Connection (Transport Adapters)"]
        I[Connection Interface] --> J[LocalConnection]
        I --> K[Wire Protocol]
    end

    style Layer1 fill:#f9f,stroke:#333,stroke-width:2px
    style L2 fill:#bbf,stroke:#333,stroke-width:2px
    style L3 fill:#dfd,stroke:#333,stroke-width:2px
```

Sources: [google/antigravity/conversation/README.md:16-35](), [google/antigravity/agent.py:15-31]()

## Layer 1: Simplified Agent (Lifecycle & Config)

The **Agent** layer is the primary entry point for most developers. It manages the declarative setup of the agent, including its tools, hooks, and safety policies. It is responsible for the overall lifecycle of a session, ensuring that all components (transports, tool runners, and triggers) are correctly initialized and torn down.

### Key Responsibilities
- **Lifecycle Management**: Uses async context managers (`__aenter__`/`__aexit__`) to manage resource initialization and cleanup.
- **Declarative Configuration**: Consolidates tools, policies, and MCP servers into a single `AgentConfig`.
- **Convenience API**: Exposes the `chat()` method, which abstracts away the complexity of the underlying loops.

```python
# google/antigravity/agent.py:195-204
async def chat(self, prompt: types.Content) -> types.ChatResponse:
  """Sends a prompt and returns the final response."""
  return await self.conversation.chat(prompt)
```

Sources: [google/antigravity/agent.py:36-183](), [README.md:32-36]()

## Layer 2: Stateful Session (Conversation)

The **Conversation** layer manages the "memory" of the agentic loop. It is decoupled from the transport layer, allowing it to focus purely on session state, token usage, and history management.

### Key Responsibilities
- **History Accumulation**: Automatically records every step (text, tool calls, thinking) into a persistent history.
- **Turn & Compaction Tracking**: Tracks where individual turns start and where history has been compacted to optimize context windows.
- **Usage Monitoring**: Aggregates token counts across multiple turns for cost and performance analysis.

### Layer Comparison

| Concern | Owner | Implementation Detail |
|:---|:---|:---|
| **Config & Policies** | Layer 1 (Agent) | Declarative setup; defines *capabilities*. |
| **History & Turns** | Layer 2 (Conversation) | Stateful session; tracks *interactions*. |
| **Wire Protocol** | Layer 3 (Connection) | Transport plumbing; moves *bytes*. |

Sources: [google/antigravity/conversation/conversation.py:59-87](), [google/antigravity/conversation/README.md:37-43]()

## Layer 3: Transport Adapters (Connection)

The **Connection** layer is the lowest level of the SDK, providing a platform-agnostic interface for interacting with agent backends. It abstracts the wire protocol and binary execution details.

### Key Responsibilities
- **Wire Protocol**: Handles the serialization and deserialization of messages (e.g., Protobuf over WebSockets for local execution).
- **Process Management**: In the case of `LocalConnection`, it manages the lifecycle of the underlying `localharness` binary.
- **Backend Abstraction**: Provides a unified `Connection` interface that Layer 2 APIs depend on, ensuring portability between local and hosted backends.

```python
# google/antigravity/connections/connection.py:15-23
"""Base interfaces for connections in the Google Antigravity SDK.
A Connection is the SDK's public interface for interacting with an agent
backend... Layer 2 APIs depend ONLY on this interface."""
```

Sources: [google/antigravity/connections/connection.py:15-38](), [google/antigravity/connections/local/local_connection.py:785-830]()

## Summary

The three-layer architecture of the Google Antigravity SDK ensures that concerns are strictly isolated: the **Agent** handles "who" the agent is (config), the **Conversation** handles "what" happened (state), and the **Connection** handles "how" they talk (transport). This design allows the SDK to scale from simple scripts to complex, multi-modal applications while maintaining a consistent and reliable agentic loop.

Sources: [google/antigravity/conversation/README.md:12-35]()