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:

pip install sea-agent-session

Create a client and fetch a session:

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:

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:

from sea_agent_session import new_client_from_config

client = new_client_from_config()

By default, the SDK reads ~/.seaagent/config.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:

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

Fetch one session detail:

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

Read messages directly:

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

Memory APIs

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:

{
    "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:

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

Development

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>