# How to Add a Conversation Using the TencentDB Agent Memory Python SDK

> Easily add conversations with the TencentDB Agent Memory Python SDK. Use the add_conversation method for seamless message thread submission and automatic context resolution.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: how-to-guide
- Published: 2026-08-27

---

**Use the `add_conversation` method on the `MemoryClient` or `AsyncMemoryClient` class to submit message threads via a POST request to the `/v3/conversation/add` endpoint, while the SDK automatically injects tenant isolation parameters and resolves session contexts.**

The TencentDB Agent Memory Python SDK manages conversational data through a strict-isolation architecture that prevents cross-tenant leakage. Adding a conversation requires instantiating a client with team, agent, user, and session identifiers, then passing a structured message list to the `add_conversation` method, which handles payload construction, null-value filtering, and transport.

## Configure the Isolation Context

The SDK enforces data isolation through a four-tuple of identifiers supplied at client instantiation. When creating a `MemoryClient`, you must provide `team_id`, `agent_id`, `user_id`, and optionally `session_id`. These values are stored in an internal `_IsolationCtx` object defined in [`tencentdb_agent_memory/v3/client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tencentdb_agent_memory/v3/client.py) (lines 9-23).

The isolation context automatically merges these identifiers into every request body via `self._iso.base_body()`. If you need to override isolation parameters for a specific call without mutating the original client, the SDK provides a `with_isolation` clone method that returns a new client instance with modified context.

## Invoke the add_conversation Method

To persist a conversation turn, call `add_conversation` on your client instance. The method signature accepts a `messages` parameter containing a list of dictionaries, where each dictionary specifies a `role` (e.g., "user", "assistant") and `content` string.

The implementation in [`tencentdb_agent_memory/v3/client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tencentdb_agent_memory/v3/client.py) (lines 30-41) enforces a critical server constraint: conversation writes require a non-empty `session_id`. The SDK invokes `self._iso.resolve_session_for_write(session_id)` to inject the client-level session ID if the call does not explicitly provide one, ensuring the server receives a valid isolation scope.

```python

# pip install tencentdb-agent-memory

from tencentdb_agent_memory import MemoryClient

client = MemoryClient(
    team_id="team-123",
    agent_id="agent-abc",
    user_id="user-xyz",
    session_id="session-001"
)

response = client.add_conversation(
    messages=[
        {"role": "user", "content": "Hello, how's the weather?"},
        {"role": "assistant", "content": "It's sunny in Beijing today."}
    ]
)

print("Add-conversation response:", response)

```

## Override Session Context for Specific Calls

While the client stores a default `session_id`, you can override it per-call by passing the `session_id` parameter directly to `add_conversation`. This temporarily bypasses the client-level default without modifying the underlying `_IsolationCtx`.

```python
response = client.add_conversation(
    messages=[{"role": "user", "content": "What is the stock price?"}],
    session_id="session-002"  # Optional override for this request only

)

```

## Request Construction and Transport Layer

Before transmission, the method constructs a JSON payload combining isolation fields, the resolved session ID, and the messages array. The SDK filters out null values using `_strip_none` to ensure clean request bodies (see [`v3/client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/v3/client.py) lines 30-43).

The actual HTTP POST to `{_V3}/conversation/add` is executed by `self._stub.post`, defined in the low-level transport layer ([`tencentdb_agent_memory/_http.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tencentdb_agent_memory/_http.py)). This stub handles authentication headers, retry logic, and JSON serialization.

## Asynchronous Conversation Writes

For async workflows, use `AsyncMemoryClient`, which mirrors the synchronous API. The async variant awaits the same stub call, maintaining identical isolation semantics and payload construction.

```python
import asyncio
from tencentdb_agent_memory import AsyncMemoryClient

async def add_conversation_async():
    async_client = AsyncMemoryClient(
        team_id="team-123",
        agent_id="agent-abc",
        user_id="user-xyz",
        session_id="session-003"
    )
    resp = await async_client.add_conversation(
        messages=[{"role": "user", "content": "Async demo"}]
    )
    print(resp)

asyncio.run(add_conversation_async())

```

## Summary

- **Strict isolation**: Every `MemoryClient` requires `team_id`, `agent_id`, `user_id`, and `session_id` to prevent cross-tenant data leakage.
- **Session resolution**: The SDK automatically validates or injects `session_id` via `_iso.resolve_session_for_write()` before transmitting to `POST /v3/conversation/add`.
- **Payload construction**: The `add_conversation` method merges isolation context, resolved session IDs, and message lists, filtering nulls with `_strip_none`.
- **Dual interface**: Both synchronous (`MemoryClient`) and asynchronous (`AsyncMemoryClient`) implementations use the same transport stub and isolation logic defined in [`v3/client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/v3/client.py).

## Frequently Asked Questions

### What parameters are required to add a conversation using the Python SDK?

You must instantiate the client with `team_id`, `agent_id`, and `user_id`. The `session_id` can be set at the client level or passed per-call to `add_conversation`, but the server requires a non-empty value. The `messages` parameter must contain a list of dictionaries with `role` and `content` keys.

### Can I override the session ID for a single add_conversation call?

Yes. Pass the `session_id` argument directly to the `add_conversation` method. The SDK uses `resolve_session_for_write()` to prioritize the call-level parameter over the client-level default stored in `_IsolationCtx`, allowing temporary context switching without cloning the client.

### How does the SDK handle asynchronous conversation writes?

The `AsyncMemoryClient` class provides an `add_conversation` coroutine that awaits the same HTTP stub used by the synchronous client. It maintains identical isolation semantics and payload construction, differing only in its async/await interface.

### Where does the SDK implement the conversation addition logic?

The primary implementation resides in [`tencentdb_agent_memory/v3/client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tencentdb_agent_memory/v3/client.py) (lines 30-43), which handles session resolution, payload assembly, and the `_strip_none` filter. The HTTP transport layer is implemented in [`tencentdb_agent_memory/_http.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tencentdb_agent_memory/_http.py), which executes the POST request to the `/v3/conversation/add` endpoint.