Phase 3: AgentKeys Python SDK

[hanwencheng]

Context

Not every AgentKeys consumer speaks MCP. Custom GPTs, Claude Code skills, raw Python scripts, internal vendor tooling — these need an SDK that wraps the broker / signer / worker APIs without requiring MCP-protocol literacy.

The Python SDK is the first SDK (TypeScript is #120). Python wins as the first choice because:

• Most agentic frameworks (LangChain, LlamaIndex, etc.) are Python-first
• Anthropic's MCP reference implementation is Python
• Vendor data-science teams write Python for prototype integrations

Per milestones-roadmap.md §4, SDKs are M3 deliverables — they widen the integration surface beyond MCP hosts.

Scope (M3)

SDK design

• Async-first client built on httpx or aiohttp — modern Python (3.10+); typed with pydantic v2
• Tool surface = MCP server's tool surface — same 7 active tools from Phase 1: AgentKeys MCP server — 7 active tools + 3 schema-only #107:
  • client.identity.whoami(actor)
  • client.memory.get(actor, namespace) / client.memory.put(...)
  • client.permission.check(actor, scope, params)
  • client.cap.mint(...) / client.cap.revoke(cap_id)
  • client.audit.append(...)
• Plus context manager for session lifetime + automatic cap-token refresh
• Type-annotated end-to-end (mypy strict)

Packaging

• Publish to PyPI as agentkeys
• Semver from day one; v0.1.0 is the M3 release
• Wheels for Linux / macOS / Windows (pure Python, so no platform-specific builds needed; just sdist + universal wheel)

Examples

• README quickstart: install → mint cap-token → read memory → audit
• Example notebook: "Integrate AgentKeys into a custom Claude Code skill" — full walkthrough since this is one of the primary M3 use cases
• Example script: AgentKeys as a credential broker for a Python script that hits a 3rd-party API

Out of scope (defer)

• Synchronous (blocking) API surface — async-only for M3; sync wrapper if user demand surfaces in M4
• Plugin system for custom auth providers (M4)
• CLI binary (M4 — pip install is enough for the SDK; CLI is a separate concern)
• Auto-generated stubs from an OpenAPI spec (M4 — hand-written types in M3 for clarity)

Acceptance criteria

• pip install agentkeys succeeds on Python 3.10, 3.11, 3.12
• A Python script using the SDK can: mint a cap-token, write to memory, read it back filtered by namespace, append an audit row — full happy path in ≤30 lines
• Type checking passes mypy strict mode
• PyPI package metadata is correct (license, project URL, author, README badge)
• README quickstart works for a new user copy-pasting the code
• Notebook example successfully integrates AgentKeys into a working Claude Code skill end-to-end
• Test suite covers each tool method + at least 1 error path per method
• CI publishes to PyPI on tag; automated changelog generation

Risks

Risk	Mitigation
API drift between SDK + MCP server	Both versions derive from a single OpenAPI spec; SDK CI tests against the live MCP server's schema
Authentication shape diverges from MCP server's per-vendor Bearer pattern	SDK requires same Bearer + actor header — code re-use via shared auth module if MCP server moves to Python wholesale
pip install user expects synchronous API and gets async surprise	README quickstart shows async clearly; client_sync wrapper documented as roadmap if demand exists

References

• docs/spec/plans/milestones-roadmap.md §4 (M3 scope — SDKs for non-MCP paths)
• docs/research/agent-iam-strategy.md §5 Phase 3 (runtime neutrality)
• Phase 1: AgentKeys MCP server — 7 active tools + 3 schema-only #107 (MCP server — same tool surface)
• Phase 3: AgentKeys TypeScript SDK #120 (TypeScript SDK — sister deliverable; same shape)

Effort

~1 week. Sequencing:

1. (Days 1-2) Skeleton + async HTTP client + auth + type definitions
2. (Days 2-4) All 7 tool methods + error envelope
3. (Days 4-5) Tests + mypy strict pass
4. (Days 5-7) Docs + notebook + PyPI publish CI

Pickup notes for the next agent / developer

• Async-only. If you build a sync surface in M3, you'll regret it during M4 streaming work.
• The 7-tool surface MUST match Phase 1: AgentKeys MCP server — 7 active tools + 3 schema-only #107's MCP server tools verbatim — same parameter names, same JSON shapes. Generate from a shared schema if possible.
• For HTTP client: prefer httpx over aiohttp — better Python typing + simpler tracing hooks
• For type checking: aim for mypy --strict from day one; will save grief later
• For PyPI publish: use trusted publishing via GitHub Actions — no PyPI API tokens in repo secrets
• Watch for: SDK error messages should match the MCP server's exact wording so vendor support can grep one error message across all client integrations
• Use the /agentkeys-issue-create skill for follow-up issues (e.g., sync wrapper, CLI, examples gallery)

[jshaofa-ui]

Solution: AgentKeys Python SDK

I've developed a comprehensive solution for the Python SDK that mirrors the MCP server's tool surface as native Python async methods.

Key Design Decisions

1. Namespaced API — client.memory.get(), client.cap.mint(), etc., matching the MCP tool naming
2. Dual transport — HTTP (direct broker) and stdio (local daemon) with automatic fallback
3. Type-safe — Full Pydantic models, type annotations, compatible with strict mypy
4. Minimal deps — Only httpx + pydantic + anyio

Package Structure

• src/agentkeys/ — 10 modules covering client, transport, models, 5 sub-clients, errors
• tests/ — Full test suite targeting 90%+ coverage
• examples/ — Quickstart, Claude Code skill, Jupyter notebook

Acceptance Criteria Coverage

• ✅ pip install agentkeys works (hatchling build)
• ✅ Read memory, mint cap-token, write audit row (all sub-clients implemented)
• ✅ Documented quickstart in README

Estimated Effort: ~1 week

Full solution document available. Happy to discuss any adjustments to the API surface.