flyteplugins-agents-claude 2.5.9__py3-none-any.whl

flyteplugins/agents/claude/__init__.py

@@ -0,0 +1,18 @@
+"""Claude Agent SDK adapter for Flyte.
+
+Bring your own ``claude-agent-sdk`` agent and run it durably on Flyte. Tools you
+expose are Flyte tasks (so each tool call is a durable child action with its own
+container/resources, retries and caching); the agent loop itself runs in the
+Claude Code runtime, and its timeline is rendered into the Flyte task report.
+
+- :func:`tool` — turn an ``@env.task`` into a Claude in-process MCP tool.
+- :func:`run_agent` — run the agent loop inside your task and return the answer.
+
+The ``claude-agent-sdk`` wheel bundles the native ``claude`` CLI (no separate Node.js
+install needed); set an Anthropic API key in the environment.
+"""
+
+from ._run import run_agent
+from ._tools import tool
+
+__all__ = ["run_agent", "tool"]

flyteplugins/agents/claude/_durable.py

@@ -0,0 +1,164 @@
+"""Durable Claude sessions — make ``durable=True`` real via the SDK's session store.
+
+The Claude Agent SDK runs the model loop inside the Claude Code CLI subprocess, so
+there is no in-process model-call seam to wrap in ``flyte.trace`` for per-turn replay.
+Instead we use the SDK's own session mirror + resume: the CLI mirrors the running
+transcript to a ``SessionStore`` we provide, and on a retry it resumes from that store
+rather than starting over.
+
+We back that store with :class:`flyte.Checkpoint` — the native, retry-surviving
+durable prefix the runtime hands each task (``save`` writes this attempt's blob,
+``load`` restores the previous attempt's). So a crashed attempt's conversation is
+restored on the next attempt instead of replayed from scratch, without us owning
+the loop.
+
+Mapping to Flyte primitives:
+- session id is derived deterministically from the task's ``ActionID``, so every
+  retry of the same action targets the same session;
+- persistence is ``flyte.Checkpoint`` — durable across container restarts.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import pathlib
+import typing
+import uuid
+
+from flyte._logging import logger
+
+# Fixed namespace so derived session ids are stable across processes and retries.
+_SESSION_NS = uuid.UUID("4e1b8a2c-6c2e-5f7a-9b3d-2a1f0c7d4e55")
+_PAYLOAD = "payload"
+
+
+def deterministic_session_id(task_context: typing.Any) -> str:
+    """A stable, valid-UUID session id for the current action (same across retries).
+
+    Uses ``task_action`` when present (it stays pinned to the real running task even
+    inside a ``@trace`` pseudo-action), falling back to ``action``.
+    """
+    action = getattr(task_context, "task_action", None) or task_context.action
+    seed = f"{action.run_name}/{action.name}"
+    return str(uuid.uuid5(_SESSION_NS, seed))
+
+
+def _skey(key: typing.Mapping[str, typing.Any]) -> str:
+    """Flatten a Claude ``SessionKey`` to a single storage key.
+
+    Keyed by ``session_id`` (+ optional subagent ``subpath``); ``project_key`` is
+    intentionally ignored — our session ids are already globally unique per action.
+    """
+    return f"{key['session_id']}::{key.get('subpath') or ''}"
+
+
+def _read_payload(local: typing.Any) -> dict | None:
+    """Parse the checkpoint blob written by a previous attempt, or ``None``.
+
+    Kept sync (local, already-downloaded file IO) so the async store stays free of
+    blocking ``pathlib`` calls.
+    """
+    payload = pathlib.Path(local)
+    if payload.is_dir():
+        payload = payload / _PAYLOAD
+    if not payload.is_file():
+        return None
+    try:
+        return json.loads(payload.read_text())
+    except (ValueError, OSError):
+        return None
+
+
+class CheckpointSessionStore:
+    """A duck-typed Claude ``SessionStore`` persisted via :class:`flyte.Checkpoint`.
+
+    The SDK requires only ``append`` and ``load`` and probes for the optional methods
+    (``list_sessions``/``delete``/...), so we deliberately omit them. The whole store —
+    every session/subagent transcript seen this run — is serialized to a single
+    checkpoint blob; the SDK materializes it back into the CLI on resume.
+    """
+
+    def __init__(self, checkpoint: typing.Any) -> None:
+        self._ckpt = checkpoint
+        self._state: dict[str, list[dict]] = {}
+        self._seen: dict[str, set[str]] = {}
+        self._lock = asyncio.Lock()
+
+    async def seed_from_prev(self) -> bool:
+        """Restore the previous attempt's checkpoint into memory.
+
+        Returns ``True`` if a prior attempt's session existed (i.e. this is a retry
+        with state to resume), ``False`` otherwise.
+        """
+        local = await self._ckpt.load()
+        if local is None:
+            return False
+        data = _read_payload(local)
+        if not data:
+            return False
+        self._state = {k: list(v) for k, v in data.items()}
+        self._seen = {k: {e["uuid"] for e in v if "uuid" in e} for k, v in self._state.items()}
+        return bool(self._state)
+
+    async def _persist(self) -> None:
+        await self._ckpt.save(json.dumps(self._state).encode("utf-8"))
+
+    async def append(self, key: typing.Mapping[str, typing.Any], entries: list[dict]) -> None:
+        """Mirror a batch of transcript entries, then persist to the checkpoint."""
+        skey = _skey(key)
+        async with self._lock:
+            buf = self._state.setdefault(skey, [])
+            seen = self._seen.setdefault(skey, set())
+            changed = False
+            for entry in entries:
+                uid = entry.get("uuid")
+                if uid is not None and uid in seen:
+                    continue  # idempotent: the mirror may re-send entries on retry
+                buf.append(entry)
+                changed = True
+                if uid is not None:
+                    seen.add(uid)
+            if changed:
+                await self._persist()
+
+    async def load(self, key: typing.Mapping[str, typing.Any]) -> list[dict] | None:
+        """Return the full transcript for ``key`` (for resume), or ``None`` if unseen."""
+        async with self._lock:
+            buf = self._state.get(_skey(key))
+            return list(buf) if buf else None
+
+
+async def wire_durable_session(options: typing.Any, *, durable: bool) -> CheckpointSessionStore | None:
+    """Attach a resume-backed session store to ``options`` when durable and able.
+
+    First attempt pins a deterministic ``session_id``; a retry (whose previous
+    checkpoint exists) sets ``resume`` to that same id and seeds the store from the
+    prior attempt — so completed turns and tool results are restored from the
+    checkpoint instead of recomputed. Returns the store (or ``None`` when durability
+    is off / unavailable). Never raises: durability is best-effort and must not break
+    a run.
+    """
+    if not durable:
+        return None
+    try:
+        import flyte
+
+        task_context = flyte.ctx()
+        if task_context is None:
+            return None
+        checkpoint = task_context.checkpoint
+        if checkpoint is None:
+            return None
+        store = CheckpointSessionStore(checkpoint)
+        had_prior = await store.seed_from_prev()
+        session_id = deterministic_session_id(task_context)
+        if had_prior:
+            options.resume = session_id
+        else:
+            options.session_id = session_id
+        options.session_store = store
+        return store
+    except Exception:  # pragma: no cover - durability must never break the run
+        logger.warning("Could not wire a durable Claude session; continuing without resume.")
+        return None

flyteplugins/agents/claude/_memory.py

@@ -0,0 +1,123 @@
+"""Cross-run Claude memory — a ``SessionStore`` backed by a keyed ``MemoryStore``.
+
+Claude's session resume materializes a ``SessionStore``'s transcript into the
+CLI. The per-run crash-resume store (see :mod:`._durable`) is keyed by the action
+and backed by a ``flyte.Checkpoint`` (ephemeral, per-run). This store is keyed by a
+stable ``memory_key`` (a user/thread id) and backed by a durable, cross-run
+``MemoryStore`` — so a later run with the same key resumes the prior
+conversation.
+
+Because the memory store survives retries too, it subsumes crash-resume: when a
+``memory_key`` is given, the adapter uses this store instead of the checkpoint one.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import typing
+import uuid
+
+from flyte._logging import logger
+from flyteplugins.agents.core import resolve_memory
+
+from ._durable import _skey
+
+# Fixed namespace so a memory key maps to a stable Claude session id across runs.
+_SESSION_NS = uuid.UUID("9a7c1e30-2b44-5d96-8a1f-3c6b2e0d7f44")
+
+# Path-addressed slot holding the thread's Claude transcript inside the MemoryStore.
+_TRANSCRIPT_PATH = "claude/transcript.json"
+
+
+def memory_session_id(memory_key: str) -> str:
+    """A stable, valid-UUID Claude session id for a memory key (same across runs)."""
+    return str(uuid.uuid5(_SESSION_NS, memory_key))
+
+
+class MemorySessionStore:
+    """Duck-typed Claude ``SessionStore`` persisted in a keyed ``MemoryStore``.
+
+    Only ``append``/``load`` are required by the SDK. The whole transcript (keyed by
+    the SDK's session/subagent key) is stored as one path-addressed JSON entry; the
+    SDK materializes it back into the CLI on resume.
+    """
+
+    def __init__(self, store: typing.Any) -> None:
+        self._store = store
+        self._state: dict[str, list[dict]] = {}
+        self._seen: dict[str, set[str]] = {}
+        self._lock = asyncio.Lock()
+
+    async def seed(self) -> bool:
+        """Load the thread's prior transcript into memory; returns whether any existed."""
+        data = await self._store.read_json.aio(_TRANSCRIPT_PATH)
+        if not data:
+            return False
+        self._state = {k: list(v) for k, v in data.items()}
+        self._seen = {k: {e["uuid"] for e in v if "uuid" in e} for k, v in self._state.items()}
+        return bool(self._state)
+
+    async def _persist(self) -> None:
+        await self._store.write_json.aio(_TRANSCRIPT_PATH, self._state, actor="claude-agent")
+        await self._store.save.aio()
+
+    async def append(self, key: typing.Mapping[str, typing.Any], entries: list[dict]) -> None:
+        skey = _skey(key)
+        async with self._lock:
+            buf = self._state.setdefault(skey, [])
+            seen = self._seen.setdefault(skey, set())
+            changed = False
+            for entry in entries:
+                uid = entry.get("uuid")
+                if uid is not None and uid in seen:
+                    continue  # idempotent: the mirror may re-send entries
+                buf.append(entry)
+                changed = True
+                if uid is not None:
+                    seen.add(uid)
+            if changed:
+                await self._persist()
+
+    async def load(self, key: typing.Mapping[str, typing.Any]) -> list[dict] | None:
+        async with self._lock:
+            buf = self._state.get(_skey(key))
+            return list(buf) if buf else None
+
+    async def list_subkeys(self, key: typing.Mapping[str, typing.Any]) -> list[str]:
+        """List the subagent subpaths under a session so resume restores them too.
+
+        Without this the SDK only materializes the main transcript on resume; with it,
+        subagent transcripts (mirrored under ``subpath`` keys) come back as well.
+        Scoped to ``session_id``; the main transcript (empty subpath) is excluded.
+        """
+        prefix = f"{key['session_id']}::"
+        async with self._lock:
+            return [skey[len(prefix) :] for skey in self._state if skey.startswith(prefix) and skey != prefix]
+
+
+async def wire_memory_session(options: typing.Any, *, memory_key: str | None) -> MemorySessionStore | None:
+    """Attach a cross-run, memory-backed resume to ``options`` for ``memory_key``.
+
+    First run for the key pins a deterministic ``session_id``; a later run (whose
+    transcript already exists) sets ``resume`` and seeds from the store — so the
+    conversation continues. Returns the store, or ``None`` when memory is off /
+    unavailable. Never raises.
+    """
+    if not memory_key:
+        return None
+    try:
+        store = await resolve_memory(memory_key)
+        if store is None:
+            return None
+        session = MemorySessionStore(store)
+        had_prior = await session.seed()
+        session_id = memory_session_id(memory_key)
+        if had_prior:
+            options.resume = session_id
+        else:
+            options.session_id = session_id
+        options.session_store = session
+        return session
+    except Exception:  # pragma: no cover - memory is best-effort, never fatal
+        logger.warning("Could not wire Claude cross-run memory for key %r; continuing without it.", memory_key)
+        return None

flyteplugins/agents/claude/_run.py

@@ -0,0 +1,230 @@
+"""``run_agent`` — run a Claude Agent SDK agent on Flyte.
+
+The Claude Agent SDK owns the loop (it drives the model via the Claude Code
+runtime). ``run_agent`` runs that loop inside your ``@env.task``: it builds an
+in-process MCP server from the tools, points the SDK at it, streams the run, and
+renders the timeline into the Flyte report.
+
+Durability: tool calls are durable Flyte child actions (see
+:func:`flyteplugins.agents.claude.tool`). Per-turn model replay is not
+available here — the model loop runs in the Claude Code runtime (a subprocess
+Flyte doesn't intercept), so a model turn can't be a ``flyte.trace`` leaf the way
+it is for client-side SDKs. Instead, ``durable=True`` wires the SDK's own session
+mirror + resume onto a :class:`flyte.Checkpoint` (see :mod:`._durable`), so a
+crashed attempt's conversation is restored on retry rather than restarted. Tool
+durability, retries and caching apply regardless.
+
+Observability: beyond streaming the assistant turns, ``PostToolUse`` /
+``PostToolUseFailure`` hooks record each tool's outcome (result or error) into
+the report timeline.
+"""
+
+from __future__ import annotations
+
+import json
+import typing
+
+from claude_agent_sdk import (
+    AssistantMessage,
+    ClaudeAgentOptions,
+    HookMatcher,
+    ResultMessage,
+    SdkMcpTool,
+    TextBlock,
+    ToolUseBlock,
+    create_sdk_mcp_server,
+    query,
+)
+from flyte._task import TaskTemplate
+from flyteplugins.agents.core import ReportTimeline, abbrev, flush_report
+
+from ._durable import wire_durable_session
+from ._memory import wire_memory_session
+from ._tools import tool
+
+
+def _coerce_tool(t: typing.Any) -> SdkMcpTool:
+    if isinstance(t, SdkMcpTool):
+        return t
+    if isinstance(t, TaskTemplate):
+        return tool(t)
+    return t
+
+
+async def run_agent(
+    input: str,
+    *,
+    tools: typing.Sequence[typing.Any] = (),
+    model: str | None = "claude-sonnet-4-5",
+    instructions: str | None = None,
+    max_turns: int | None = None,
+    durable: bool = True,
+    observability: bool = True,
+    options: ClaudeAgentOptions | None = None,
+    server_name: str = "flyte_tools",
+    memory_key: str | None = None,
+) -> str:
+    """Run a Claude agent with the given tools and prompt; return the final text.
+
+    Call this from inside an ``@env.task`` — that task is the durable parent,
+    and each tool the agent calls runs as a durable Flyte child action. Pass a
+    fully-built ``ClaudeAgentOptions`` via ``options`` to keep SDK-native config
+    (subagents, permissions, hooks, session resume); ``tools``/``model``/
+    ``instructions``/``max_turns`` are layered on top.
+
+    With ``durable=True`` (and a checkpoint-capable task context) the SDK's session
+    mirror + resume is wired onto a ``flyte.Checkpoint``, so a retry resumes the
+    conversation instead of restarting it. With ``observability=True`` the run
+    timeline — assistant turns plus per-tool outcomes (via hooks) — is rendered into
+    the task report.
+
+    Set ``memory_key`` (a user/thread id) for cross-run memory: the transcript is
+    persisted to a durable, keyed ``MemoryStore`` and resumed on a later run with the
+    same key (this also covers crash-resume, so it takes precedence over the per-run
+    ``durable`` checkpoint).
+
+    The ``claude-agent-sdk`` wheel bundles the native ``claude`` CLI, so the runtime
+    image needs no separate Node.js install — just an Anthropic API key.
+    """
+    sdk_tools = [_coerce_tool(t) for t in tools]
+    opts = options or ClaudeAgentOptions()
+
+    if sdk_tools:
+        server = create_sdk_mcp_server(server_name, tools=sdk_tools)
+        opts.mcp_servers = {**(opts.mcp_servers or {}), server_name: server}
+        allowed = [f"mcp__{server_name}__{t.name}" for t in sdk_tools]
+        opts.allowed_tools = [*(opts.allowed_tools or []), *allowed]
+    if instructions is not None:
+        opts.system_prompt = instructions
+    if model is not None:
+        opts.model = model
+    if max_turns is not None:
+        opts.max_turns = max_turns
+
+    if memory_key:
+        await wire_memory_session(opts, memory_key=memory_key)
+    else:
+        await wire_durable_session(opts, durable=durable)
+
+    timeline = ReportTimeline() if observability else None
+    if timeline is not None:
+        timeline.heading("Claude agent")
+        _install_tool_hooks(opts, timeline)
+
+    final = ""
+    async for message in query(prompt=input, options=opts):
+        if isinstance(message, AssistantMessage):
+            if timeline is not None:
+                _render_assistant(timeline, message)
+        elif isinstance(message, ResultMessage):
+            final = message.result or final
+            if timeline is not None:
+                _render_result(timeline, message)
+
+    if observability:
+        await flush_report()
+    return final or ""
+
+
+def _render_assistant(timeline: ReportTimeline, message: AssistantMessage) -> None:
+    for block in message.content:
+        if isinstance(block, TextBlock):
+            if block.text.strip():
+                timeline.row(icon="💬", label="assistant", detail=abbrev(block.text, 200))
+        elif isinstance(block, ToolUseBlock):
+            timeline.row(icon="🛠️", label=block.name, meta="tool", detail=abbrev(block.input, 160))
+
+
+def _compact(n: int) -> str:
+    """Compact a token count, e.g. 5000 -> '5.0k'."""
+    return f"{n / 1000:.1f}k" if n >= 1000 else str(n)
+
+
+def _fmt_usage(usage: dict[str, typing.Any] | None) -> str:
+    """A compact, auditable token breakdown from the result's ``usage`` dict.
+
+    These are the counts that drive ``total_cost_usd`` (the SDK's cost estimate), so
+    surfacing them lets you sanity-check the dollar figure at a glance. Keys are passed
+    through from the Claude Code CLI, so both snake_case and camelCase are accepted.
+    """
+    if not usage:
+        return ""
+
+    def pick(*keys: str) -> int:
+        for key in keys:
+            value = usage.get(key)
+            if isinstance(value, (int, float)) and value:
+                return int(value)
+        return 0
+
+    fields = [
+        ("in", pick("input_tokens", "inputTokens")),
+        ("out", pick("output_tokens", "outputTokens")),
+        ("cache read", pick("cache_read_input_tokens", "cacheReadInputTokens")),
+        ("cache write", pick("cache_creation_input_tokens", "cacheCreationInputTokens")),
+    ]
+    return " · ".join(f"{label} {_compact(n)}" for label, n in fields if n)
+
+
+def _render_result(timeline: ReportTimeline, message: ResultMessage) -> None:
+    parts = []
+    if message.num_turns:
+        parts.append(f"{message.num_turns} turns")
+    if message.duration_ms:
+        parts.append(f"{message.duration_ms} ms")
+    if message.total_cost_usd:
+        parts.append(f"${message.total_cost_usd:.4f}")
+    timeline.row(
+        icon="✅",
+        label="result",
+        meta=" · ".join(parts),
+        detail=_fmt_usage(message.usage),
+        error="error" if message.is_error else None,
+    )
+
+
+def _stringify(value: typing.Any) -> str:
+    if isinstance(value, str):
+        return value
+    try:
+        return json.dumps(value, default=str)
+    except (TypeError, ValueError):
+        return str(value)
+
+
+def _install_tool_hooks(opts: ClaudeAgentOptions, timeline: ReportTimeline) -> None:
+    """Record each tool's outcome into the report via PostToolUse hooks.
+
+    The streamed assistant turns already show the tool request (``ToolUseBlock``);
+    these hooks add the result/error the message stream doesn't surface. They observe
+    only — each returns an empty decision — and are merged into any user-provided
+    ``opts.hooks`` rather than replacing them.
+    """
+
+    async def _post_tool(input_data: dict, tool_use_id: str | None, context: typing.Any) -> dict:
+        timeline.row(
+            icon="🔧",
+            label=input_data.get("tool_name", ""),
+            meta="tool result",
+            detail=abbrev(_stringify(input_data.get("tool_response", "")), 160),
+        )
+        return {}
+
+    async def _post_tool_failure(input_data: dict, tool_use_id: str | None, context: typing.Any) -> dict:
+        timeline.row(
+            icon="❌",
+            label=input_data.get("tool_name", ""),
+            meta="tool error",
+            detail=abbrev(_stringify(input_data.get("error", "")), 160),
+            error="error",
+        )
+        return {}
+
+    additions = {
+        "PostToolUse": [HookMatcher(hooks=[_post_tool])],
+        "PostToolUseFailure": [HookMatcher(hooks=[_post_tool_failure])],
+    }
+    merged = dict(opts.hooks or {})
+    for event, matchers in additions.items():
+        merged[event] = [*(merged.get(event) or []), *matchers]
+    opts.hooks = merged

flyteplugins/agents/claude/_tools.py

@@ -0,0 +1,99 @@
+"""Turn Flyte tasks into Claude Agent SDK tools that execute as durable actions.
+
+The Claude Agent SDK exposes custom tools as in-process MCP tools (``@tool`` /
+``SdkMcpTool``). :func:`tool` wraps a Flyte ``@env.task`` as one whose
+handler dispatches to the task via ``task.aio()`` — so when Claude calls the
+tool, it runs as a durable Flyte child action (its own container/resources, with
+retries and caching) rather than inline in the agent process.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+import typing
+from functools import partial
+
+from claude_agent_sdk import SdkMcpTool
+from claude_agent_sdk import tool as claude_tool
+from flyte._task import AsyncFunctionTaskTemplate
+from flyte.models import NativeInterface
+from flyteplugins.agents.core import attach_tool_resolver, coerce_tool_args, task_json_schema
+
+
+def tool(
+    func: AsyncFunctionTaskTemplate | typing.Callable | None = None,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+) -> SdkMcpTool | typing.Callable:
+    """Convert a Flyte task (or plain callable) into a Claude Agent SDK tool.
+
+    - For an ``@env.task``: returns an ``SdkMcpTool`` whose handler runs the task
+      as a durable Flyte child action when Claude calls it. The input schema is
+      derived from the task via the Flyte type engine. The backing task is wired
+      to :class:`~flyteplugins.agents.core.ToolTaskResolver` and exposed via
+      ``__wrapped_task__`` so it resolves to itself on the worker (no recursion).
+    - For a plain (async) callable: returns an ``SdkMcpTool`` that runs it inline.
+
+    Usable bare, parametrized, or as a direct call::
+
+        @tool
+        @env.task
+        async def get_weather(city: str) -> str: ...
+    """
+    if func is None:
+        return partial(tool, name=name, description=description)
+    if isinstance(func, AsyncFunctionTaskTemplate):
+        return _task_to_tool(func, name=name, description=description)
+    return _callable_to_tool(func, name=name, description=description)
+
+
+def _task_to_tool(
+    task: AsyncFunctionTaskTemplate,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+) -> SdkMcpTool:
+    tool_name = name or task.func.__name__
+    desc = (description or task.func.__doc__ or f"Run {tool_name}").strip()
+
+    async def handler(args: dict[str, typing.Any]) -> dict[str, typing.Any]:
+        # In a Flyte task context this submits a durable child action; locally it
+        # runs inline. ``coerce_tool_args`` relaxes LLM int->float args so Flyte's
+        # type engine doesn't reject e.g. ``amount_usd=42`` for a ``float`` param.
+        result = await task.aio(**coerce_tool_args(task, args or {}))
+        return _as_content(result)
+
+    sdk_tool = claude_tool(tool_name, desc, task_json_schema(task))(handler)
+
+    # The tool shadows the task at module scope, so wire the shared resolver and
+    # expose the real task for it to recover on the worker.
+    attach_tool_resolver(task)
+    sdk_tool.__wrapped_task__ = task
+    sdk_tool.task = task
+    return sdk_tool
+
+
+def _callable_to_tool(
+    func: typing.Callable,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+) -> SdkMcpTool:
+    tool_name = name or getattr(func, "__name__", "tool")
+    desc = (description or func.__doc__ or f"Run {tool_name}").strip()
+    schema = NativeInterface.from_callable(func).json_schema
+
+    async def handler(args: dict[str, typing.Any]) -> dict[str, typing.Any]:
+        out = func(**(args or {}))
+        if inspect.isawaitable(out):
+            out = await out
+        return _as_content(out)
+
+    return claude_tool(tool_name, desc, schema)(handler)
+
+
+def _as_content(result: typing.Any) -> dict[str, typing.Any]:
+    text = result if isinstance(result, str) else json.dumps(result, default=str)
+    return {"content": [{"type": "text", "text": text}]}

flyteplugins_agents_claude-2.5.9.dist-info/METADATA

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: flyteplugins-agents-claude
+Version: 2.5.9
+Summary: Run Claude Agent SDK agents on Flyte.
+Author-email: Samhita Alla <samhita@union.ai>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: flyteplugins-agents-core
+Requires-Dist: claude-agent-sdk
+
+# flyteplugins-agents-claude
+
+Run [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk-python)
+agents on Flyte. You keep writing Claude agents; Flyte is the runtime underneath.
+
+```bash
+pip install flyteplugins-agents-claude
+```
+
+```python
+import flyte
+from flyteplugins.agents.claude import tool, run_agent
+
+env = flyte.TaskEnvironment(
+    "claude-agent",
+    secrets=[flyte.Secret(key="anthropic_api_key", as_env_var="ANTHROPIC_API_KEY")],
+)
+
+@tool
+@env.task(cache="auto", retries=3)
+async def get_weather(city: str) -> str:
+    """Get the current weather for a city."""
+    return f"The weather in {city} is sunny, 22°C."
+
+@env.task(report=True, retries=3)
+async def city_agent(question: str) -> str:
+    return await run_agent(question, tools=[get_weather], model="claude-sonnet-4-5")
+```
+
+## How it maps to Flyte
+
+- Tools are in-process MCP tools (the SDK's own `@tool`/`SdkMcpTool`); our `tool`
+  wraps an `@env.task` so that when Claude calls it, the task runs as a durable
+  Flyte child action (its own container/resources, retries, caching). The input
+  schema is derived via the Flyte type engine.
+- The loop runs in the Claude Code runtime. `run_agent` runs that loop inside
+  your `@env.task`, streams the messages, and renders the timeline (assistant
+  turns, tool calls, cost) into the task report.
+
+## Durability
+
+Two layers, both real:
+
+- Tool calls are durable Flyte child actions (own container/resources, retries,
+  caching) — always, regardless of `durable`.
+- The conversation survives a crash. With `durable=True`, `run_agent` wires the
+  Claude SDK's own session mirror + resume onto a `flyte.Checkpoint`: a
+  deterministic `session_id` (derived from the task's action, so it's stable across
+  retries) is pinned on the first attempt, and on a retry the prior attempt's
+  transcript is restored from the checkpoint and the run resumes instead of
+  restarting.
+
+We delegate to the SDK's resume because the model loop runs in the Claude Code
+runtime (a subprocess Flyte doesn't intercept), so a model turn can't be a
+`flyte.trace` leaf the way it is for other client-side SDKs. Session
+resume is the coarser-grained equivalent — whole-session, not per-turn — and it
+no-ops cleanly when there's no checkpoint context (e.g. local runs).
+
+## Observability
+
+`run_agent` renders a timeline into the task report (`report=True`): the assistant
+turns from the streamed messages, plus each tool's outcome — `PostToolUse` /
+`PostToolUseFailure` hooks record the result or error the message stream doesn't
+surface. If you pass your own `ClaudeAgentOptions(hooks=...)`, ours are merged in,
+not substituted.
+
+## Runtime
+
+The `claude-agent-sdk` wheel bundles the native `claude` CLI (a per-platform
+binary, ~250 MB — including the `manylinux` wheel), so `pip install
+flyteplugins-agents-claude` is all the runtime image needs.
+
+## Memory
+
+Pass `memory_key` (a user/thread id) for cross-run memory — the agent resumes the
+same conversation across separate runs:
+
+```python
+await run_agent(message, model="claude-sonnet-4-5", memory_key="user-alice")
+```
+
+The transcript is persisted to a durable, keyed `MemoryStore` and resumed via the
+SDK's session-mirror on the next run with the same key — which also covers
+crash-resume, so it supersedes the per-run `durable` checkpoint.
+
+## Examples
+
+See [`examples/`](examples/):
+
+- [`claude_durable_agent.py`](examples/claude_durable_agent.py) — a single durable
+  agent: tools as Flyte tasks, tool outcomes + assistant turns in the report.
+- [`claude_crash_resume.py`](examples/claude_crash_resume.py) — crash & resume:
+  the task crashes on its first attempt; on retry the conversation resumes from the
+  `flyte.Checkpoint`-backed session and completed tool calls are cache hits. Run on a
+  backend to see resume.
+- [`claude_multi_agent.py`](examples/claude_multi_agent.py) — multi-agent
+  orchestration: a planner agent decomposes a topic, researcher agents fan out in
+  parallel, an editor agent synthesizes — each agent its own durable action.
+- [`claude_hitl.py`](examples/claude_hitl.py) — human-in-the-loop: a sensitive
+  `issue_refund` tool pauses on a Flyte condition (`flyte.new_condition`) for a human
+  to approve before it runs — a durable gate the agent SDK has no equivalent for.
+- [`claude_memory.py`](examples/claude_memory.py) — cross-run memory: two
+  separate runs share a `memory_key`; the agent learns a fact in run 1 and recalls
+  it in run 2.
+- [`claude_handoffs.py`](examples/claude_handoffs.py) — native subagent delegation: a
+  triage prompt delegates to a billing or technical-support subagent, the whole run
+  durable on Flyte.
+
+## Conformance
+
+This adapter passes the shared `flyteplugins.agents.core.testing.assert_adapter_conforms`
+check — the same one every adapter runs — so it follows the common format
+(`tool` + `run_agent`, tool tasks wired to the resolver) despite a very
+different underlying SDK shape.

flyteplugins_agents_claude-2.5.9.dist-info/RECORD

@@ -0,0 +1,9 @@
+flyteplugins/agents/claude/__init__.py,sha256=G6lSAnXrFocmcDLZSTgnnkHVKIKFZVMcAx4WS_981QM,757
+flyteplugins/agents/claude/_durable.py,sha256=pUDjp6FTBUx-XRX6piF-nekzNqtpeGGQ7SFSj4PBCMk,6602
+flyteplugins/agents/claude/_memory.py,sha256=6sagwpl-G0oBQl74D_rl2Z-XCMGhtQk-p7rG1G1CJcU,5132
+flyteplugins/agents/claude/_run.py,sha256=ff1txOV06lPa4n5mrPt4OJq37KfeNYeHij6DQYVw0T8,8648
+flyteplugins/agents/claude/_tools.py,sha256=Sb_c_M3tW7VeQ0rFb3LFcnKKwdVkydVZwKmy6nQ15d8,3853
+flyteplugins_agents_claude-2.5.9.dist-info/METADATA,sha256=LVl7Wpl4Mfjpwx3k05fEWAn-p_E4neDl8_OnETMJpaY,5240
+flyteplugins_agents_claude-2.5.9.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+flyteplugins_agents_claude-2.5.9.dist-info/top_level.txt,sha256=cgd779rPu9EsvdtuYgUxNHHgElaQvPn74KhB5XSeMBE,13
+flyteplugins_agents_claude-2.5.9.dist-info/RECORD,,

flyteplugins_agents_claude-2.5.9.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

flyteplugins_agents_claude-2.5.9.dist-info/top_level.txt

@@ -0,0 +1 @@
+flyteplugins