agentcore-cli 0.31.1__py3-none-any.whl

agentcore/aws/agui_types.py

@@ -0,0 +1,342 @@
+"""AG-UI protocol event types and parser (port of ``agui-types.ts``).
+
+AG-UI events are streamed as SSE with the type embedded in the JSON payload::
+
+    data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"msg-1","delta":"Hello"}
+
+Events are plain dicts keyed exactly as on the wire (camelCase); the TypedDicts below document
+their shapes. See https://docs.ag-ui.com/concepts/events.
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from enum import StrEnum
+from typing import Any, Literal, NotRequired, TypedDict
+
+
+class AguiEventType(StrEnum):
+    # Lifecycle
+    RUN_STARTED = "RUN_STARTED"
+    RUN_FINISHED = "RUN_FINISHED"
+    RUN_ERROR = "RUN_ERROR"
+    STEP_STARTED = "STEP_STARTED"
+    STEP_FINISHED = "STEP_FINISHED"
+    # Text message (streaming triplet)
+    TEXT_MESSAGE_START = "TEXT_MESSAGE_START"
+    TEXT_MESSAGE_CONTENT = "TEXT_MESSAGE_CONTENT"
+    TEXT_MESSAGE_END = "TEXT_MESSAGE_END"
+    TEXT_MESSAGE_CHUNK = "TEXT_MESSAGE_CHUNK"
+    # Tool call
+    TOOL_CALL_START = "TOOL_CALL_START"
+    TOOL_CALL_ARGS = "TOOL_CALL_ARGS"
+    TOOL_CALL_END = "TOOL_CALL_END"
+    TOOL_CALL_RESULT = "TOOL_CALL_RESULT"
+    TOOL_CALL_CHUNK = "TOOL_CALL_CHUNK"
+    # State management
+    STATE_SNAPSHOT = "STATE_SNAPSHOT"
+    STATE_DELTA = "STATE_DELTA"
+    MESSAGES_SNAPSHOT = "MESSAGES_SNAPSHOT"
+    # Activity
+    ACTIVITY_SNAPSHOT = "ACTIVITY_SNAPSHOT"
+    ACTIVITY_DELTA = "ACTIVITY_DELTA"
+    # Reasoning
+    REASONING_START = "REASONING_START"
+    REASONING_MESSAGE_START = "REASONING_MESSAGE_START"
+    REASONING_MESSAGE_CONTENT = "REASONING_MESSAGE_CONTENT"
+    REASONING_MESSAGE_END = "REASONING_MESSAGE_END"
+    REASONING_END = "REASONING_END"
+    REASONING_ENCRYPTED_VALUE = "REASONING_ENCRYPTED_VALUE"
+    # Special
+    RAW = "RAW"
+    CUSTOM = "CUSTOM"
+    META_EVENT = "META_EVENT"
+
+
+class AguiErrorCode(StrEnum):
+    AGENT_ERROR = "AGENT_ERROR"
+    UNAUTHORIZED = "UNAUTHORIZED"
+    ACCESS_DENIED = "ACCESS_DENIED"
+    VALIDATION_ERROR = "VALIDATION_ERROR"
+    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED"
+
+
+_KNOWN_EVENT_TYPES = frozenset(t.value for t in AguiEventType)
+
+
+class AguiBaseEvent(TypedDict):
+    type: str
+    timestamp: NotRequired[float]
+    rawEvent: NotRequired[Any]
+
+
+# --- Lifecycle ---
+
+
+class AguiRunStarted(AguiBaseEvent):
+    threadId: str
+    runId: str
+    parentRunId: NotRequired[str]
+
+
+class AguiRunFinished(AguiBaseEvent):
+    threadId: str
+    runId: str
+    result: NotRequired[Any]
+
+
+class AguiRunError(AguiBaseEvent):
+    message: str
+    code: NotRequired[str]
+
+
+class AguiStepStarted(AguiBaseEvent):
+    stepName: str
+
+
+class AguiStepFinished(AguiBaseEvent):
+    stepName: str
+
+
+# --- Text messages ---
+
+
+class AguiTextMessageStart(AguiBaseEvent):
+    messageId: str
+    role: str
+
+
+class AguiTextMessageContent(AguiBaseEvent):
+    messageId: str
+    delta: str
+
+
+class AguiTextMessageEnd(AguiBaseEvent):
+    messageId: str
+
+
+class AguiTextMessageChunk(AguiBaseEvent):
+    messageId: str
+    role: NotRequired[str]
+    delta: NotRequired[str]
+    content: NotRequired[str]
+
+
+# --- Tool calls ---
+
+
+class AguiToolCallStart(AguiBaseEvent):
+    toolCallId: str
+    toolCallName: str
+    parentMessageId: NotRequired[str]
+
+
+class AguiToolCallArgs(AguiBaseEvent):
+    toolCallId: str
+    delta: str
+
+
+class AguiToolCallEnd(AguiBaseEvent):
+    toolCallId: str
+
+
+class AguiToolCallResult(AguiBaseEvent):
+    messageId: str
+    toolCallId: str
+    content: Any
+    role: NotRequired[str]
+
+
+class AguiToolCallChunk(AguiBaseEvent):
+    toolCallId: str
+    delta: NotRequired[str]
+
+
+# --- State management ---
+
+
+class JsonPatchOperation(TypedDict):
+    op: str
+    path: str
+    value: NotRequired[Any]
+
+
+class AguiStateSnapshot(AguiBaseEvent):
+    snapshot: dict[str, Any]
+
+
+class AguiStateDelta(AguiBaseEvent):
+    delta: list[JsonPatchOperation]
+
+
+class AguiMessagesSnapshot(AguiBaseEvent):
+    messages: list[Any]
+
+
+# --- Activity ---
+
+
+class AguiActivitySnapshot(AguiBaseEvent):
+    messageId: str
+    activityType: str
+    content: dict[str, Any]
+    replace: NotRequired[bool]
+
+
+class AguiActivityDelta(AguiBaseEvent):
+    messageId: str
+    activityType: str
+    patch: list[JsonPatchOperation]
+
+
+# --- Reasoning ---
+
+
+class AguiReasoningStart(AguiBaseEvent):
+    messageId: str
+
+
+class AguiReasoningMessageStart(AguiBaseEvent):
+    messageId: str
+    role: str
+
+
+class AguiReasoningMessageContent(AguiBaseEvent):
+    messageId: str
+    delta: str
+
+
+class AguiReasoningMessageEnd(AguiBaseEvent):
+    messageId: str
+
+
+class AguiReasoningEnd(AguiBaseEvent):
+    messageId: str
+
+
+class AguiReasoningEncryptedValue(AguiBaseEvent):
+    messageId: str
+    data: str
+
+
+# --- Special ---
+
+
+class AguiRawEvent(AguiBaseEvent):
+    event: Any
+    source: NotRequired[str]
+
+
+class AguiCustomEvent(AguiBaseEvent):
+    name: str
+    value: Any
+
+
+class AguiMetaEvent(AguiBaseEvent):
+    name: str
+    value: Any
+
+
+AguiEvent = (
+    AguiRunStarted
+    | AguiRunFinished
+    | AguiRunError
+    | AguiStepStarted
+    | AguiStepFinished
+    | AguiTextMessageStart
+    | AguiTextMessageContent
+    | AguiTextMessageEnd
+    | AguiTextMessageChunk
+    | AguiToolCallStart
+    | AguiToolCallArgs
+    | AguiToolCallEnd
+    | AguiToolCallResult
+    | AguiToolCallChunk
+    | AguiStateSnapshot
+    | AguiStateDelta
+    | AguiMessagesSnapshot
+    | AguiActivitySnapshot
+    | AguiActivityDelta
+    | AguiReasoningStart
+    | AguiReasoningMessageStart
+    | AguiReasoningMessageContent
+    | AguiReasoningMessageEnd
+    | AguiReasoningEnd
+    | AguiReasoningEncryptedValue
+    | AguiRawEvent
+    | AguiCustomEvent
+    | AguiMetaEvent
+)
+
+
+# --- RunAgentInput (request body) ---
+
+
+class AguiMessage(TypedDict):
+    id: str
+    role: str
+    content: str | list[Any]
+    name: NotRequired[str]
+    toolCallId: NotRequired[str]
+
+
+class AguiTool(TypedDict):
+    name: str
+    description: str
+    parameters: dict[str, Any]
+
+
+class AguiContext(TypedDict):
+    description: str
+    value: str
+
+
+class AguiRunInput(TypedDict):
+    threadId: str
+    runId: str
+    messages: list[AguiMessage]
+    tools: NotRequired[list[AguiTool]]
+    context: NotRequired[list[AguiContext]]
+    state: NotRequired[dict[str, Any]]
+    forwardedProps: NotRequired[dict[str, Any]]
+
+
+AguiRole = Literal["user", "assistant", "system", "tool", "developer"]
+
+
+def is_known_event_type(event_type: str) -> bool:
+    return event_type in _KNOWN_EVENT_TYPES
+
+
+def parse_agui_event(line: str) -> AguiEvent | None:
+    """Parse one SSE ``data:`` line into an AG-UI event dict.
+
+    Returns ``None`` for non-data lines, empty payloads, malformed JSON, or objects without a
+    ``type``. Unknown types are returned as-is for forward compatibility.
+    """
+    if not line.startswith("data: "):
+        return None
+    json_str = line[6:].strip()
+    if not json_str:
+        return None
+    try:
+        parsed = json.loads(json_str)
+    except ValueError:
+        return None
+    if not isinstance(parsed, dict) or "type" not in parsed:
+        return None
+    return parsed  # type: ignore[return-value]
+
+
+def build_agui_run_input(prompt: str, thread_id: str | None = None, run_id: str | None = None) -> AguiRunInput:
+    """Minimal single-turn ``RunAgentInput`` for ``prompt`` with fresh thread/run IDs."""
+    return {
+        "threadId": thread_id if thread_id is not None else str(uuid.uuid4()),
+        "runId": run_id if run_id is not None else str(uuid.uuid4()),
+        "messages": [{"id": str(uuid.uuid4()), "role": "user", "content": prompt}],
+        "tools": [],
+        "context": [],
+        "state": {},
+        "forwardedProps": {},
+    }

agentcore/aws/api_client.py

@@ -0,0 +1,87 @@
+"""Shared SigV4-signed HTTP client for AgentCore control/data plane APIs (port of ``api-client.ts``).
+
+Used for APIs that upstream calls outside the AWS SDK. When the SDK (botocore) models are
+authoritative for an API, callers can migrate to the boto3 clients.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Literal
+from urllib.parse import urlencode, urlsplit
+
+from agentcore.aws._http import HttpResponse, signed_request
+from agentcore.aws.stage_endpoint import control_plane_endpoint, data_plane_endpoint
+from agentcore.lib.utils.json_format import to_json_string
+
+SERVICE = "bedrock-agentcore"
+
+ApiPlane = Literal["control", "data"]
+
+
+class AgentCoreApiError(Exception):
+    def __init__(self, status_code: int, error_body: str, request_id: str | None = None):
+        suffix = f" [requestId: {request_id}]" if request_id else ""
+        super().__init__(f"AgentCore API error ({status_code}): {error_body}{suffix}")
+        self.status_code = status_code
+        self.request_id = request_id
+        self.error_body = error_body
+
+    @property
+    def message(self) -> str:
+        return str(self)
+
+    @property
+    def name(self) -> str:
+        return "AgentCoreApiError"
+
+
+def resolve_endpoint(region: str, plane: ApiPlane) -> str:
+    return control_plane_endpoint(region) if plane == "control" else data_plane_endpoint(region)
+
+
+def build_url(endpoint: str, path: str, query: Mapping[str, str] | None = None) -> str:
+    """``endpoint + path`` with ``query`` merged into any query string already on ``path``."""
+    if not query:
+        return f"{endpoint}{path}"
+    parts = urlsplit(path)
+    existing = parts.query
+    extra = urlencode(dict(query))
+    qs = f"{existing}&{extra}" if existing else extra
+    return f"{endpoint}{parts.path}?{qs}"
+
+
+class AgentCoreApiClient:
+    def __init__(self, *, region: str, plane: ApiPlane):
+        self.region = region
+        self.endpoint = resolve_endpoint(region, plane)
+
+    def request(
+        self,
+        *,
+        method: str,
+        path: str,
+        body: Any = None,
+        query: Mapping[str, str] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Any:
+        response = self.request_raw(method=method, path=path, body=body, query=query, headers=headers, stream=False)
+        if not response.ok:
+            raise AgentCoreApiError(response.status, response.text(), response.header("x-amzn-requestid"))
+        if response.status == 204:
+            return {}
+        return response.json()
+
+    def request_raw(
+        self,
+        *,
+        method: str,
+        path: str,
+        body: Any = None,
+        query: Mapping[str, str] | None = None,
+        headers: Mapping[str, str] | None = None,
+        stream: bool = True,
+    ) -> HttpResponse:
+        serialized = to_json_string(body, indent=None) if body is not None else None
+        url = build_url(self.endpoint, path, query)
+        return signed_request(method, url, region=self.region, body=serialized, headers=headers, stream=stream)

agentcore/aws/arn.py

@@ -0,0 +1,18 @@
+"""ARN parsing helpers (port of ``arn.ts``).
+
+Kept separate from ``region``: that module *detects* the ambient region, while these are pure
+string functions over an ARN the caller already holds.
+"""
+
+from __future__ import annotations
+
+
+def region_from_arn(arn: str) -> str | None:
+    """Region field (index 3) of ``arn:{partition}:{service}:{region}:{account}:{resource}``.
+
+    Splitting on ':' rather than matching a partition keeps this correct for GovCloud and China
+    ARNs. Returns ``None`` for a malformed or region-less ARN so callers can fall back.
+    """
+    parts = arn.split(":")
+    region = parts[3] if len(parts) > 3 else ""
+    return region or None

agentcore/aws/aws_context.py

@@ -0,0 +1,23 @@
+"""Detected AWS account/region context (port of ``aws-context.ts``)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from agentcore.aws import account as _account
+from agentcore.aws import region as _region
+from agentcore.schema.schemas.aws_targets import AgentCoreRegion
+
+
+@dataclass(frozen=True, slots=True)
+class AwsContext:
+    account_id: str | None
+    region: AgentCoreRegion
+    region_source: _region.RegionSource
+
+
+def detect_aws_context() -> AwsContext:
+    """Detect account ID and region from the environment / shared config."""
+    account_id = _account.detect_account()
+    detected = _region.detect_region()
+    return AwsContext(account_id=account_id, region=detected.region, region_source=detected.source)

agentcore/aws/bedrock.py

@@ -0,0 +1,44 @@
+"""Synchronous Bedrock model invocation (port of ``bedrock.ts``)."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from agentcore.aws.account import create_aws_client
+from agentcore.lib.utils.json_format import to_json_string
+
+CLAUDE_MODEL_ID = "global.anthropic.claude-opus-4-5-20251101-v1:0"
+CLAUDE_ANTHROPIC_VERSION = "bedrock-2023-05-31"
+
+
+@dataclass(frozen=True, slots=True)
+class ClaudeResponse:
+    content: str
+
+
+def invoke_bedrock_sync(*, region: str, model_id: str, body: dict[str, Any]) -> dict[str, Any]:
+    """Invoke a Bedrock model and return the parsed JSON response body."""
+    client = create_aws_client("bedrock-runtime", region)
+    response = client.invoke_model(
+        modelId=model_id,
+        contentType="application/json",
+        accept="application/json",
+        body=to_json_string(body, indent=None).encode("utf-8"),
+    )
+    return json.loads(response["body"].read().decode("utf-8"))
+
+
+def invoke_claude(*, region: str, prompt: str, max_tokens: int | None = None) -> ClaudeResponse:
+    """Invoke Claude on Bedrock with a single user prompt and return the first text block."""
+    body = {
+        "anthropic_version": CLAUDE_ANTHROPIC_VERSION,
+        "max_tokens": max_tokens if max_tokens is not None else 8192,
+        "messages": [{"role": "user", "content": prompt}],
+    }
+    response = invoke_bedrock_sync(region=region, model_id=CLAUDE_MODEL_ID, body=body)
+    content = response.get("content") or []
+    if not content:
+        raise RuntimeError("No content returned from Bedrock")
+    return ClaudeResponse(content=content[0].get("text"))

agentcore/aws/bedrock_agent.py

@@ -0,0 +1,129 @@
+"""Bedrock Knowledge Base / data source / ingestion helpers (port of ``bedrock-agent.ts``).
+
+Results are the boto3 response structures (camelCase keys, ``datetime`` timestamps), mirroring the
+SDK v3 objects upstream returns.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from botocore.client import BaseClient
+
+from agentcore.aws._aws_errors import is_not_found_error
+from agentcore.aws.account import create_aws_client
+
+KnowledgeBase = dict[str, Any]
+DataSource = dict[str, Any]
+DataSourceSummary = dict[str, Any]
+IngestionJob = dict[str, Any]
+IngestionJobSummary = dict[str, Any]
+
+
+def _make_client(region: str) -> BaseClient:
+    # One-shot CLI process: a fresh client per call, as upstream.
+    return create_aws_client("bedrock-agent", region)
+
+
+def get_knowledge_base(*, region: str, knowledge_base_id: str) -> KnowledgeBase | None:
+    """Knowledge base by ID; ``None`` if it doesn't exist (other errors propagate)."""
+    try:
+        return _make_client(region).get_knowledge_base(knowledgeBaseId=knowledge_base_id).get("knowledgeBase")
+    except Exception as exc:
+        if is_not_found_error(exc):
+            return None
+        raise
+
+
+def get_data_source(*, region: str, knowledge_base_id: str, data_source_id: str) -> DataSource | None:
+    try:
+        response = _make_client(region).get_data_source(knowledgeBaseId=knowledge_base_id, dataSourceId=data_source_id)
+        return response.get("dataSource")
+    except Exception as exc:
+        if is_not_found_error(exc):
+            return None
+        raise
+
+
+def list_ingestion_jobs(
+    *, region: str, knowledge_base_id: str, data_source_id: str, client: BaseClient | None = None
+) -> list[IngestionJobSummary]:
+    """Every ingestion job summary for a (KB, DS) pair across all pages; ``[]`` if the pair doesn't exist."""
+    client = client or _make_client(region)
+    summaries: list[IngestionJobSummary] = []
+    next_token: str | None = None
+    try:
+        while True:
+            params: dict[str, Any] = {"knowledgeBaseId": knowledge_base_id, "dataSourceId": data_source_id}
+            if next_token:
+                params["nextToken"] = next_token
+            response = client.list_ingestion_jobs(**params)
+            summaries.extend(response.get("ingestionJobSummaries") or [])
+            next_token = response.get("nextToken")
+            if not next_token:
+                return summaries
+    except Exception as exc:
+        if is_not_found_error(exc):
+            return []
+        raise
+
+
+def list_data_sources(*, region: str, knowledge_base_id: str) -> list[DataSourceSummary]:
+    """Every data source of a KB across all pages; ``[]`` if the KB doesn't exist.
+
+    Used post-deploy to resolve data-source IDs (the L3 emits per-KB outputs but not per-DS ones).
+    """
+    client = _make_client(region)
+    summaries: list[DataSourceSummary] = []
+    next_token: str | None = None
+    try:
+        while True:
+            params: dict[str, Any] = {"knowledgeBaseId": knowledge_base_id}
+            if next_token:
+                params["nextToken"] = next_token
+            response = client.list_data_sources(**params)
+            summaries.extend(response.get("dataSourceSummaries") or [])
+            next_token = response.get("nextToken")
+            if not next_token:
+                return summaries
+    except Exception as exc:
+        if is_not_found_error(exc):
+            return []
+        raise
+
+
+def start_ingestion_job(*, region: str, knowledge_base_id: str, data_source_id: str) -> IngestionJob:
+    """Start an ingestion job; service errors propagate verbatim."""
+    response = _make_client(region).start_ingestion_job(knowledgeBaseId=knowledge_base_id, dataSourceId=data_source_id)
+    job = response.get("ingestionJob")
+    if not job:
+        raise RuntimeError("StartIngestionJob succeeded but returned no ingestion job in the response")
+    return job
+
+
+def _started_ms(summary: IngestionJobSummary) -> float:
+    started = summary.get("startedAt")
+    return started.timestamp() * 1000 if isinstance(started, datetime) else 0
+
+
+def get_latest_ingestion_job(*, region: str, knowledge_base_id: str, data_source_id: str) -> IngestionJob | None:
+    """Full details of the most recently started ingestion job, or ``None`` if none ever ran."""
+    client = _make_client(region)
+    summaries = list_ingestion_jobs(
+        region=region, knowledge_base_id=knowledge_base_id, data_source_id=data_source_id, client=client
+    )
+    if not summaries:
+        return None
+
+    latest = summaries[0]
+    for current in summaries[1:]:
+        if _started_ms(current) > _started_ms(latest):
+            latest = current
+    if not latest.get("ingestionJobId"):
+        return None
+
+    response = client.get_ingestion_job(
+        knowledgeBaseId=knowledge_base_id, dataSourceId=data_source_id, ingestionJobId=latest["ingestionJobId"]
+    )
+    return response.get("ingestionJob")