SDK 0.2.0: two-client architecture (UserClient + AgentClient)

[AlexLiu190625]

⚠️ Breaking change

0.1.0 code breaks on upgrade. from xagent_sdk import XAgentClient and
MeResponse now raise ImportError. This is intentional — there is no
deprecation alias. See the migration table below.

What this does

Splits the single XAgentClient into two clients over a shared
_BaseClient, matching the two key types the backend issues:

• UserClient — authenticates with a personal key
  (xag_personal_<prefix>_<secret>). Owns the management surface:
  me(), templates.{list,get}, agents.{list,create,create_from_template,rotate_key}.
• AgentClient — authenticates with an agent runtime key
  (xag_<prefix>_<secret>). Owns tasks.{create,append,get,steps,wait,run}.

A SaaS app uses UserClient to mint an agent + one-time runtime key,
then hands the runtime key to AgentClient to drive chat tasks.

Migration from 0.1.0

0.1.0	0.2.0
from xagent_sdk import XAgentClient	from xagent_sdk import AgentClient (tasks) / UserClient (management)
client.me() → MeResponse(agent_id, ...)	UserClient.me() → UserPrincipal(user_id, ...)
client.tasks.*	AgentClient.tasks.* (unchanged surface)

sed -i '' 's/XAgentClient/AgentClient/g' your_app.py covers the rename;
identity lookups move to UserClient.me() with a different field shape.

New public surface

• Clients: UserClient, AgentClient
• Dataclasses: UserPrincipal, Template, TemplateDetail,
  AgentSummary, AgentCreateResult, RotateKeyResult
• Errors: TemplateNotFound (server code template_not_found),
  MalformedResponse (SDK-coined, for decode-shape failures)

Validation

• 131 unit tests pass; mypy strict + ruff + codespell clean.
• Public surface pinned to an exact 28-name set; a re-export of the old
  names trips CI (test_public_surface.py + a repo-wide grep guard).
• Every SDK method exercised against a live backend: me, templates
  list/get, agents list/create/create_from_template (both
  generate_runtime_key modes)/rotate_key, tasks
  create/get/steps/append, and the 404 → typed-exception mappings
  (TemplateNotFound / AgentNotFound / TaskNotFound,
  revoked-key → InvalidAPIKey).
• Response parsers were aligned to the real backend wire shapes
  (bare-array list endpoints, id → template_id/agent_id, nested
  {agent, api_key} create payload, flat-spread template overrides).

[gemini-code-assist]

Code Review

This pull request updates the Python SDK to version 0.2.0, introducing breaking changes that split the legacy XAgentClient into two isolated clients: UserClient for workspace management (templates, agents, and user identity) and AgentClient for runtime chat tasks. It also adds support for template management, agent creation, and API key rotation. The review feedback focuses on enhancing the robustness of the SDK's response parsing helpers in types.py (_parse_user_principal, _parse_template_detail, _parse_agent_create, and _parse_rotate_key) by defensively validating that the backend responses are dictionaries and raising a clean MalformedResponse exception rather than letting raw Pydantic validation or type errors propagate.

[gemini-code-assist]

The _parse_user_principal function expects data to be a dictionary. If the backend returns a non-dictionary response, this will raise a raw Pydantic ValidationError. To align with the SDK's error handling strategy of raising MalformedResponse for response contract violations, we should defensively check that data is a dictionary.

def _parse_user_principal(data: Any) -> UserPrincipal:
    if not isinstance(data, dict):
        raise MalformedResponse(
            "malformed_response",
            "Expected a dictionary response for user principal",
            http_status=None,
        )
    return _USER_PRINCIPAL_ADAPTER.validate_python(data)

[gemini-code-assist]

The _parse_template_detail function expects data to be a dictionary and passes it directly to _template_dict, which performs attribute accesses. If the backend returns a non-dictionary response, this will raise an unhandled AttributeError or TypeError. We should defensively check that data is a dictionary and raise a MalformedResponse if it is not.

def _parse_template_detail(data: Any) -> TemplateDetail:
    if not isinstance(data, dict):
        raise MalformedResponse(
            "malformed_response",
            "Expected a dictionary response for template detail",
            http_status=None,
        )
    return _TEMPLATE_DETAIL_ADAPTER.validate_python(_template_dict(data))

[gemini-code-assist]

The _parse_agent_create function performs dictionary lookups and attribute accesses on data and api_key without verifying their types first. If the backend returns a non-dictionary response or a non-dictionary api_key block, this will raise an unhandled AttributeError or TypeError instead of a clean MalformedResponse. We should defensively check that data is a dictionary and that api_key is a dictionary before performing lookups.

def _parse_agent_create(data: Any) -> AgentCreateResult:
    """Parse the nested ``{"agent": {...}, "api_key": {...}}`` payload.

    Backend returns the new agent row and (when ``generate_runtime_key``
    is true) the one-time runtime key as two siblings under separate
    keys; SDK flattens them into ``AgentCreateResult`` so callers see one
    record. When ``generate_runtime_key=False`` the ``api_key`` block is
    absent and the runtime fields stay ``None`` -- caller is expected to
    materialize a key via ``rotate_key()`` later.

    Raises ``MalformedResponse`` if the ``agent`` block is missing or
    lacks ``id``/``name`` -- pydantic's raw ``ValidationError`` on
    ``agent_id`` would say "Input should be a valid integer,
    input_value=None" which does not point at the real cause (backend
    response shape violation).
    """
    if not isinstance(data, dict):
        raise MalformedResponse(
            "malformed_response",
            "Expected a dictionary response for agent creation",
            http_status=None,
        )
    agent = data.get("agent")
    if (
        not isinstance(agent, dict)
        or agent.get("id") is None
        or agent.get("name") is None
    ):
        raise MalformedResponse(
            "malformed_response",
            "agent-create response missing required 'agent' block "
            "(expected {'agent': {'id': int, 'name': str, ...}, 'api_key'?: {...}})",
            http_status=None,
        )
    api_key = data.get("api_key")
    if not isinstance(api_key, dict):
        api_key = {}
    flat = {
        "agent_id": agent.get("id"),
        "name": agent.get("name"),
        "runtime_full_key": api_key.get("full_key"),
        "runtime_key_prefix": api_key.get("key_prefix"),
    }
    return _AGENT_CREATE_ADAPTER.validate_python(flat)

[gemini-code-assist]

The _parse_rotate_key function expects data to be a dictionary. If the backend returns a non-dictionary response, this will raise a raw Pydantic ValidationError. To align with the SDK's error handling strategy of raising MalformedResponse for response contract violations, we should defensively check that data is a dictionary.

Suggested change

	def _parse_rotate_key(data: dict[str, Any]) -> RotateKeyResult:
	return _ROTATE_KEY_ADAPTER.validate_python(data)
	def _parse_rotate_key(data: Any) -> RotateKeyResult:
	if not isinstance(data, dict):
	raise MalformedResponse(
	"malformed_response",
	"Expected a dictionary response for key rotation",
	http_status=None,
	)
	return _ROTATE_KEY_ADAPTER.validate_python(data)

[AlexLiu190625]

Thanks — applied in 3bc7692. Rather than guarding the four flagged parsers individually, I extracted a shared _require_mapping(data, what) helper and routed every single-object parser through it (_parse_user_principal, _parse_template_detail, _parse_agent_create, _parse_rotate_key, plus the three runtime parsers _parse_create_task / _parse_append / _parse_task_info), so the whole parser layer now raises MalformedResponse uniformly on a non-object body. _parse_agent_create also coerces a non-dict api_key block to {} as suggested.

Covered by a parametrized matrix (7 parsers × 5 non-dict bodies) plus the api_key coercion case; full suite is 167 green.

[rogercloud]

Two follow-up findings from review.

[rogercloud]

create() defaults generate_runtime_key to True, so a successful default create response is expected to include the one-time runtime key. If the backend response omits api_key or sends a non-object value here, _parse_agent_create() currently returns runtime_full_key=None; constructing an AgentClient(api_key=result.runtime_full_key) can then fall back to XAGENT_API_KEY and silently use the wrong credential. Please make the default-key path fail closed, for example by requiring api_key.full_key when generate_runtime_key=True (and applying the same check to create_from_template()).

[rogercloud]

The shared fixture docs describe GET /v1/templates and GET /v1/agents as wrapper objects ({templates: [...]} / {agents: [...]}), but the fixtures, SDK parsers, and backend management endpoints use bare JSON arrays. The wire objects also use id; template_id / agent_id are SDK-level names. Please update these rows so other SDKs or backend tests do not implement the wrapper shape by mistake.

[rogercloud]

Follow-up on the runtime-key fail-closed check.

[rogercloud]

This now fails closed for a missing runtime key, but it still lets an empty full_key through. AgentClient(api_key="") is also dangerous because _BaseClient resolves keys with api_key or os.environ.get(...), so an empty string falls back to XAGENT_API_KEY and can silently authenticate as a different agent. Please reject all empty runtime keys here, for example if generate_runtime_key and not result.runtime_full_key:, and cover the empty-string case for both create() and create_from_template().

[rogercloud]

Approved after rechecking latest head f395f80. Local validation and GitHub CI are passing.