Metadata-Version: 2.4
Name: sea-agent-session
Version: 0.1.0
Summary: Python SDK for SeaArt agent-gateway session history and memory APIs
Author: SeaArt
License-Expression: MIT
Project-URL: Homepage, https://github.com/SeaArt-Infra/sea-agent-session-py
Project-URL: Repository, https://github.com/SeaArt-Infra/sea-agent-session-py
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: yaml
Requires-Dist: PyYAML>=6.0; extra == "yaml"

# sea-agent-session-py

> Beta: SDK API 和 agent-gateway worker session 行为仍可能随网关版本调整。

Python SDK for `agent-gateway` conversation state APIs. It wraps worker session history plus authenticated user-and-agent memory management.

## Available Resources

| Resource | Client field | What it does |
| --- | --- | --- |
| Sessions | `client.sessions` / `client.Sessions` | List worker sessions, fetch one session detail, and read session messages |
| Memory | `client.memory` / `client.Memory` | List, export, correct, and forget cross-session memory and long-term facts |

## How It Works

1. Create a `Client` with an agent-gateway endpoint and optional API key.
2. The SDK normalizes the endpoint to include `/agent-v2` when needed.
3. Each resource helper sends gateway-compatible HTTP requests with global headers.
4. The SDK unwraps the gateway `{"data": ...}` envelope and returns Python dictionaries.

Session history APIs are read-only; memory APIs also support writes and deletes. `Authorization: Bearer <api-key>` is added automatically when `api_key` is configured. `new_client_from_config()` can reuse `~/.seaagent/config.yaml`; `userId` from that config is sent as the trusted `X-User-ID` production-line identity. Every memory call also requires an explicit terminal `end_user_id`; Agent Gateway derives the full tenant, end-user, and Agent scope.

## Quick Start

Install the package:

```bash
pip install sea-agent-session
```

Create a client and fetch a session:

```python
import os

from sea_agent_session import Client

client = Client(
    endpoint="https://openresty-gateway.gpu-service.dev.seaart.dev",
    api_key=os.environ["AGENT_GATEWAY_API_KEY"],
)

detail = client.sessions.get(
    "google-112779902978566929623",
    "d973bf80-cb37-49c9-abc8-d644ea737690",
    {"include_messages": True},
)

print(detail["session"]["session_id"], len(detail.get("messages", [])))
```

## Configuration

Pass options directly:

```python
client = Client(
    endpoint="https://openresty-gateway.gpu-service.dev.seaart.dev",
    api_key=os.environ["AGENT_GATEWAY_API_KEY"],
    headers={
        "X-User-ID": "production-line-123",
    },
)
```

Or reuse the CLI config:

```python
from sea_agent_session import new_client_from_config

client = new_client_from_config()
```

By default, the SDK reads `~/.seaagent/config.yaml`:

```yaml
endpoint: https://openresty-gateway.gpu-service.dev.seaart.dev
apiKey: sa-xxxxxxxx
userId: production-line-123
```

`endpoint` may be the gateway base URL or a URL that already includes `/agent-v2`. The SDK appends `/agent-v2` before sending requests when it is missing.

## Session APIs

List sessions for a user:

```python
sessions = client.sessions.list(
    "google-112779902978566929623",
    {
        "agent_name": "creative_assistant",
        "limit": 50,
        "offset": 0,
    },
)
```

Fetch one session detail:

```python
detail = client.sessions.get(user_id, session_id, {"include_messages": False})
```

Read messages directly:

```python
messages = client.sessions.messages(user_id, session_id, {"limit": 200, "tail": True})
```

## Memory APIs

```python
items = client.memory.list(agent_id, end_user_id, {"limit": 20, "offset": 0})
snapshot = client.memory.export(agent_id, end_user_id)

client.memory.update(
    agent_id,
    end_user_id,
    memory_id,
    {"content": "Use concise Chinese responses."},
)

client.memory.delete_fact(
    agent_id,
    end_user_id,
    fact_id,
    {"reason": "user_request"},
)
```

Use `list_short_term` for scoped session metadata, `get_preference` and `set_preference` for opt-in control, and `list_candidates` plus `confirm_candidate` to promote a repeated preference into a long-term fact. `delete_account` removes the terminal user's worker, medium-term, and long-term memory for the selected Agent.

Do not send `tenant_id`, `user_id`, or `agent_record_id` in payloads. The SDK writes the required `end_user_id` from its explicit argument and Agent Gateway overwrites the remaining scope fields from the trusted request identity and route Agent ID.

## API Mapping

| Method | Gateway API | Notes |
| --- | --- | --- |
| `sessions.list` | `GET /v1/worker/users/{user_id}/sessions/` | Supports `agent_name`, `limit`, `offset` |
| `sessions.get` | `GET /v1/worker/users/{user_id}/sessions/{session_id}` | Supports `include_messages`, `message_limit`; gateway defaults include messages |
| `sessions.messages` | `GET /v1/worker/users/{user_id}/sessions/{session_id}/messages` | Supports `limit`, `offset`, `tail`; gateway defaults to tail mode |
| `memory.list_short_term` | `GET /v1/agents/{agent_id}/memory/short-term` | Scoped session metadata only |
| `memory.list`, `memory.export` | `GET /v1/agents/{agent_id}/memory/...` | Medium-term memory is cross-session |
| `memory.get_preference`, `memory.set_preference` | `GET/PUT /v1/agents/{agent_id}/memory/preferences` | Read or change memory opt-in |
| `memory.list_candidates`, `memory.confirm_candidate` | `GET /candidates`, `POST /candidates/{candidate_id}/confirm` | Review and promote repeated preferences |
| `memory.update`, `memory.delete` | `PUT/DELETE /v1/agents/{agent_id}/memory/{memory_id}` | Correct or forget one medium-term item |
| `memory.list_facts`, `memory.create_fact` | `GET/POST /v1/agents/{agent_id}/memory/facts` | Manage long-term facts |
| `memory.update_fact`, `memory.delete_fact` | `PUT/DELETE /v1/agents/{agent_id}/memory/facts/{fact_id}` | Version or forget one long-term fact |
| `memory.delete_account` | `DELETE /v1/agents/{agent_id}/memory/account` | Remove all persisted layers for one terminal user |

Pagination follows gateway behavior: session list defaults to 50 and caps at 200; message list defaults to 200 and caps at 1000.

## Response Shape

`sessions.get()` returns:

```python
{
    "session": {
        "session_id": "d973bf80-cb37-49c9-abc8-d644ea737690",
        "user_id": "google-112779902978566929623",
        "message_count": 0,
        "file_count": 0,
    },
    "messages": [
        {
            "role": "user",
            "content": "我是bcd",
            "timestamp": "2026-06-22T09:37:54.179943+00:00",
        }
    ],
}
```

`sessions.messages()` returns:

```python
{
    "user_id": "google-112779902978566929623",
    "session_id": "d973bf80-cb37-49c9-abc8-d644ea737690",
    "items": [],
    "limit": 200,
    "offset": 0,
    "tail": True,
}
```

## Development

```bash
python3 -m unittest discover -s tests
```

<script
  type="text/plain"
  data-doc-skill
  data-doc-skill-id="sea-agent-session-py"
  data-doc-skill-label="SeaAgent Session Python SDK"
  data-doc-skill-filename="sea-agent-session-py-SKILL.md"
  data-doc-skill-version="1"
>
---
name: sea-agent-session-py
description: Access SeaArt Agent Gateway worker session history and authenticated Agent memory from Python through the official sea-agent-session package. Use to list or read sessions and messages, and to manage cross-session memory or long-term facts.
---

# SeaAgent Session Python SDK

Use `sea-agent-session` for Agent Gateway conversation state. Keep chat generation in `sea-agent-sdk`; use this SDK only for session history and memory.

## Workflow

1. Inspect `pyproject.toml` and use Python 3.10 or newer.
2. Add the package with the project's environment manager, for example `pip install --upgrade sea-agent-session`.
3. Create one `Client` with the gateway endpoint, API key, and authenticated-user header.
4. Use `sessions` for read-only worker history and `memory` for user-and-agent-scoped memory.
5. Run the project's focused test or `python3 -m unittest discover -s tests` after changing the integration.

The SDK appends `/agent-v2` when the configured endpoint does not already contain it. It unwraps the gateway `data` envelope. Use a service-side API key and do not place it in browser code.

## Create A Client

```python
from sea_agent_session import Client

client = Client(
    endpoint=os.environ["AGENT_GATEWAY_ENDPOINT"],
    api_key=os.environ["AGENT_GATEWAY_API_KEY"],
    headers={"X-User-ID": authenticated_user_id},
)
```

Use `new_client_from_config()` only when the service intentionally shares `~/.seaagent/config.yaml`.

## Read Sessions

Pass the target user ID in session paths. Limit messages instead of loading an unbounded history.

```python
detail = client.sessions.get(
    user_id,
    session_id,
    {"include_messages": True, "message_limit": 100},
)
```

Use `client.sessions.list` with `agent_name`, `limit`, and `offset` to browse sessions. Use `client.sessions.messages` with `tail` for recent messages or an explicit offset for pagination.

## Manage Memory

Memory is scoped by the trusted `X-User-ID` production line, the explicit terminal `end_user_id`, and the route Agent ID. Do not send `tenant_id`, `user_id`, or `agent_record_id` in a memory payload because the gateway derives them.

```python
items = client.memory.list(agent_id, end_user_id, {"limit": 20})
client.memory.update(
    agent_id,
    end_user_id,
    memory_id,
    {"content": "Use concise Chinese responses."},
)
```

Use `client.memory.export` for a snapshot. Use `list_facts`, `create_fact`, `update_fact`, and `delete_fact` for long-term facts. Use `list_candidates` and `confirm_candidate` for promotion review; treat `delete`, `delete_fact`, and `delete_account` as user-authorized state changes.

## Verify And Protect Data

Run `python3 -m unittest discover -s tests` from the package root. Verify a session read before adding memory writes or deletes. Do not log complete conversation history, memory content, API keys, or user identifiers beyond the minimum required for safe diagnostics.
</script>
