agentcore-cli 0.31.1__py3-none-any.whl

agentcore/assets/typescript/http/vercelai/base/model/load.ts

@@ -0,0 +1,121 @@
+{{#if (eq modelProvider "Bedrock")}}
+import { createAmazonBedrock } from '@ai-sdk/amazon-bedrock';
+import { fromNodeProviderChain } from '@aws-sdk/credential-providers';
+
+const provider = fromNodeProviderChain();
+
+const bedrock = createAmazonBedrock({
+  region: process.env.AWS_REGION ?? 'us-east-1',
+  credentialProvider: async () => {
+    const creds = await provider();
+    return {
+      accessKeyId: creds.accessKeyId,
+      secretAccessKey: creds.secretAccessKey,
+      sessionToken: creds.sessionToken,
+    };
+  },
+});
+
+export function loadModel() {
+  return bedrock('us.anthropic.claude-sonnet-4-5-20250929-v1:0');
+}
+{{/if}}
+{{#if (eq modelProvider "Anthropic")}}
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { withApiKey } from 'bedrock-agentcore/identity';
+
+const IDENTITY_PROVIDER_NAME = '{{identityProviders.[0].name}}';
+const IDENTITY_ENV_VAR = '{{identityProviders.[0].envVarName}}';
+
+async function getApiKey(): Promise<string> {
+  if (process.env.LOCAL_DEV === '1') {
+    const apiKey = process.env[IDENTITY_ENV_VAR] ?? process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+      throw new Error(`${IDENTITY_ENV_VAR} or ANTHROPIC_API_KEY not found. Add your key to agentcore/.env.local`);
+    }
+    return apiKey;
+  }
+  return withApiKey({ providerName: IDENTITY_PROVIDER_NAME })(async (apiKey: string) => apiKey)();
+}
+
+let _anthropic: ReturnType<typeof createAnthropic> | undefined;
+
+async function getProvider() {
+  if (!_anthropic) {
+    const apiKey = await getApiKey();
+    _anthropic = createAnthropic({ apiKey });
+  }
+  return _anthropic;
+}
+
+export async function loadModel() {
+  const anthropic = await getProvider();
+  return anthropic('claude-sonnet-4-5-20250929');
+}
+{{/if}}
+{{#if (eq modelProvider "OpenAI")}}
+import { createOpenAI } from '@ai-sdk/openai';
+import { withApiKey } from 'bedrock-agentcore/identity';
+
+const IDENTITY_PROVIDER_NAME = '{{identityProviders.[0].name}}';
+const IDENTITY_ENV_VAR = '{{identityProviders.[0].envVarName}}';
+
+async function getApiKey(): Promise<string> {
+  if (process.env.LOCAL_DEV === '1') {
+    const apiKey = process.env[IDENTITY_ENV_VAR] ?? process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+      throw new Error(`${IDENTITY_ENV_VAR} or OPENAI_API_KEY not found. Add your key to agentcore/.env.local`);
+    }
+    return apiKey;
+  }
+  return withApiKey({ providerName: IDENTITY_PROVIDER_NAME })(async (apiKey: string) => apiKey)();
+}
+
+let _openai: ReturnType<typeof createOpenAI> | undefined;
+
+async function getProvider() {
+  if (!_openai) {
+    const apiKey = await getApiKey();
+    _openai = createOpenAI({ apiKey });
+  }
+  return _openai;
+}
+
+export async function loadModel() {
+  const openai = await getProvider();
+  return openai('gpt-4.1');
+}
+{{/if}}
+{{#if (eq modelProvider "Gemini")}}
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+import { withApiKey } from 'bedrock-agentcore/identity';
+
+const IDENTITY_PROVIDER_NAME = '{{identityProviders.[0].name}}';
+const IDENTITY_ENV_VAR = '{{identityProviders.[0].envVarName}}';
+
+async function getApiKey(): Promise<string> {
+  if (process.env.LOCAL_DEV === '1') {
+    const apiKey = process.env[IDENTITY_ENV_VAR] ?? process.env.GEMINI_API_KEY;
+    if (!apiKey) {
+      throw new Error(`${IDENTITY_ENV_VAR} or GEMINI_API_KEY not found. Add your key to agentcore/.env.local`);
+    }
+    return apiKey;
+  }
+  return withApiKey({ providerName: IDENTITY_PROVIDER_NAME })(async (apiKey: string) => apiKey)();
+}
+
+let _google: ReturnType<typeof createGoogleGenerativeAI> | undefined;
+
+async function getProvider() {
+  if (!_google) {
+    const apiKey = await getApiKey();
+    _google = createGoogleGenerativeAI({ apiKey });
+  }
+  return _google;
+}
+
+export async function loadModel() {
+  const google = await getProvider();
+  return google('gemini-2.5-flash');
+}
+{{/if}}

agentcore/assets/typescript/http/vercelai/base/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "description": "AgentCore Runtime Application using Vercel AI SDK",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/main.js",
+    "dev": "tsx watch main.ts"
+  },
+  "dependencies": {
+    "ai": "^6.0.0",
+    {{#if (eq modelProvider "Bedrock")}}
+    "@ai-sdk/amazon-bedrock": "^4.0.0",
+    "@aws-sdk/credential-providers": "^3.0.0",
+    {{/if}}
+    {{#if (eq modelProvider "Anthropic")}}
+    "@ai-sdk/anthropic": "^3.0.0",
+    {{/if}}
+    {{#if (eq modelProvider "OpenAI")}}
+    "@ai-sdk/openai": "^3.0.0",
+    {{/if}}
+    {{#if (eq modelProvider "Gemini")}}
+    "@ai-sdk/google": "^3.0.0",
+    {{/if}}
+    "bedrock-agentcore": "^0.2.4",
+    "tsx": "^4.19.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}

agentcore/assets/typescript/http/vercelai/base/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": false,
+    "sourceMap": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "types": ["node"]
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

agentcore/aws/__init__.py

@@ -0,0 +1,263 @@
+"""AWS client layer (port of upstream ``src/cli/aws``).
+
+Conventions:
+
+* Functions take keyword arguments in snake_case in place of upstream's single ``options`` object.
+  Option bags that upstream threads through several helpers (runtime invocation, MCP, A2A, AG-UI,
+  exec, payment credential providers, shell reconnect) are dataclasses.
+* Records mirroring service/upstream JSON are TypedDicts keyed exactly like upstream (camelCase);
+  optional (``?:``) fields left ``undefined`` upstream are omitted. Handles wrapping streams or
+  connections are dataclasses with snake_case fields.
+* Every boto3 client is created through :func:`agentcore.aws.account.create_aws_client` (default
+  credential chain honouring ``AWS_PROFILE``, SDK-v3-style "standard" retries). APIs upstream calls
+  with raw SigV4 ``fetch`` go through :mod:`agentcore.aws._http`.
+* ``AGENTCORE_STAGE=beta|gamma`` redirects data/control plane endpoints (:mod:`.stage_endpoint`).
+
+This package re-exports the same names as upstream's ``index.ts``.
+"""
+
+from agentcore.aws.account import detect_account, get_credential_provider
+from agentcore.aws.agentcore import (
+    DEFAULT_RUNTIME_USER_ID,
+    AguiInvokeOptions,
+    AguiStreamingInvokeResult,
+    ExecuteBashOptions,
+    ExecuteBashResult,
+    ExecuteBashStreamEvent,
+    InvokeAgentRuntimeOptions,
+    InvokeAgentRuntimeResult,
+    McpInvokeOptions,
+    McpListToolsResult,
+    McpToolDef,
+    StopRuntimeSessionResult,
+    StreamingInvokeResult,
+    execute_bash_command,
+    extract_result,
+    invoke_a2a_runtime,
+    invoke_agent_runtime,
+    invoke_agent_runtime_streaming,
+    invoke_agui_runtime,
+    mcp_call_tool,
+    mcp_init_session,
+    mcp_list_tools,
+    parse_sse,
+    stop_runtime_session,
+)
+from agentcore.aws.agentcore_control import (
+    AgentRuntimeStatusResult,
+    create_control_client,
+    get_agent_runtime_status,
+)
+from agentcore.aws.agentcore_harness import (
+    DeleteHarnessResult,
+    GetHarnessResult,
+    Harness,
+    HarnessStatus,
+    HarnessStopReason,
+    HarnessStreamEvent,
+    StreamMetrics,
+    TokenUsage,
+    delete_harness,
+    get_harness,
+    invoke_harness,
+)
+from agentcore.aws.agentcore_payments import (
+    create_payment_credential_provider,
+    delete_payment_credential_provider,
+    get_or_create_payment_session,
+    get_payment_credential_provider,
+    get_payment_manager,
+    update_payment_credential_provider,
+)
+from agentcore.aws.agentcore_recommendation import (
+    DeleteRecommendationResult,
+    GetRecommendationResult,
+    ListRecommendationsResult,
+    RecommendationConfig,
+    RecommendationResult,
+    RecommendationSummary,
+    RecommendationType,
+    StartRecommendationResult,
+    delete_recommendation,
+    get_recommendation,
+    list_recommendations,
+    start_recommendation,
+)
+from agentcore.aws.agui_types import (
+    AguiActivityDelta,
+    AguiActivitySnapshot,
+    AguiBaseEvent,
+    AguiContext,
+    AguiCustomEvent,
+    AguiErrorCode,
+    AguiEvent,
+    AguiEventType,
+    AguiMessage,
+    AguiMessagesSnapshot,
+    AguiMetaEvent,
+    AguiRawEvent,
+    AguiReasoningEncryptedValue,
+    AguiReasoningEnd,
+    AguiReasoningMessageContent,
+    AguiReasoningMessageEnd,
+    AguiReasoningMessageStart,
+    AguiReasoningStart,
+    AguiRunError,
+    AguiRunFinished,
+    AguiRunInput,
+    AguiRunStarted,
+    AguiStateDelta,
+    AguiStateSnapshot,
+    AguiStepFinished,
+    AguiStepStarted,
+    AguiTextMessageChunk,
+    AguiTextMessageContent,
+    AguiTextMessageEnd,
+    AguiTextMessageStart,
+    AguiTool,
+    AguiToolCallArgs,
+    AguiToolCallChunk,
+    AguiToolCallEnd,
+    AguiToolCallResult,
+    AguiToolCallStart,
+    build_agui_run_input,
+    parse_agui_event,
+)
+from agentcore.aws.api_client import AgentCoreApiClient, AgentCoreApiError, ApiPlane
+from agentcore.aws.aws_context import AwsContext, detect_aws_context
+from agentcore.aws.bedrock import ClaudeResponse, invoke_bedrock_sync, invoke_claude
+from agentcore.aws.cloudwatch import LogEvent, search_logs, stream_logs
+from agentcore.aws.partition import arn_prefix, console_domain, dns_suffix, get_partition, service_endpoint
+from agentcore.aws.policy_generation import (
+    GetPolicyGenerationResult,
+    StartPolicyGenerationResult,
+    get_policy_generation,
+    start_policy_generation,
+)
+from agentcore.aws.region import RegionDetectionResult, detect_region
+from agentcore.aws.target_region import apply_target_region_to_env, with_target_region
+from agentcore.aws.transaction_search import enable_transaction_search
+
+__all__ = [
+    "DEFAULT_RUNTIME_USER_ID",
+    "AgentCoreApiClient",
+    "AgentCoreApiError",
+    "AgentRuntimeStatusResult",
+    "AguiActivityDelta",
+    "AguiActivitySnapshot",
+    "AguiBaseEvent",
+    "AguiContext",
+    "AguiCustomEvent",
+    "AguiErrorCode",
+    "AguiEvent",
+    "AguiEventType",
+    "AguiInvokeOptions",
+    "AguiMessage",
+    "AguiMessagesSnapshot",
+    "AguiMetaEvent",
+    "AguiRawEvent",
+    "AguiReasoningEncryptedValue",
+    "AguiReasoningEnd",
+    "AguiReasoningMessageContent",
+    "AguiReasoningMessageEnd",
+    "AguiReasoningMessageStart",
+    "AguiReasoningStart",
+    "AguiRunError",
+    "AguiRunFinished",
+    "AguiRunInput",
+    "AguiRunStarted",
+    "AguiStateDelta",
+    "AguiStateSnapshot",
+    "AguiStepFinished",
+    "AguiStepStarted",
+    "AguiStreamingInvokeResult",
+    "AguiTextMessageChunk",
+    "AguiTextMessageContent",
+    "AguiTextMessageEnd",
+    "AguiTextMessageStart",
+    "AguiTool",
+    "AguiToolCallArgs",
+    "AguiToolCallChunk",
+    "AguiToolCallEnd",
+    "AguiToolCallResult",
+    "AguiToolCallStart",
+    "ApiPlane",
+    "AwsContext",
+    "ClaudeResponse",
+    "DeleteHarnessResult",
+    "DeleteRecommendationResult",
+    "ExecuteBashOptions",
+    "ExecuteBashResult",
+    "ExecuteBashStreamEvent",
+    "GetHarnessResult",
+    "GetPolicyGenerationResult",
+    "GetRecommendationResult",
+    "Harness",
+    "HarnessStatus",
+    "HarnessStopReason",
+    "HarnessStreamEvent",
+    "InvokeAgentRuntimeOptions",
+    "InvokeAgentRuntimeResult",
+    "ListRecommendationsResult",
+    "LogEvent",
+    "McpInvokeOptions",
+    "McpListToolsResult",
+    "McpToolDef",
+    "RecommendationConfig",
+    "RecommendationResult",
+    "RecommendationSummary",
+    "RecommendationType",
+    "RegionDetectionResult",
+    "StartPolicyGenerationResult",
+    "StartRecommendationResult",
+    "StopRuntimeSessionResult",
+    "StreamMetrics",
+    "StreamingInvokeResult",
+    "TokenUsage",
+    "apply_target_region_to_env",
+    "arn_prefix",
+    "build_agui_run_input",
+    "console_domain",
+    "create_control_client",
+    "create_payment_credential_provider",
+    "delete_harness",
+    "delete_payment_credential_provider",
+    "delete_recommendation",
+    "detect_account",
+    "detect_aws_context",
+    "detect_region",
+    "dns_suffix",
+    "enable_transaction_search",
+    "execute_bash_command",
+    "extract_result",
+    "get_agent_runtime_status",
+    "get_credential_provider",
+    "get_harness",
+    "get_or_create_payment_session",
+    "get_partition",
+    "get_payment_credential_provider",
+    "get_payment_manager",
+    "get_policy_generation",
+    "get_recommendation",
+    "invoke_a2a_runtime",
+    "invoke_agent_runtime",
+    "invoke_agent_runtime_streaming",
+    "invoke_agui_runtime",
+    "invoke_bedrock_sync",
+    "invoke_claude",
+    "invoke_harness",
+    "list_recommendations",
+    "mcp_call_tool",
+    "mcp_init_session",
+    "mcp_list_tools",
+    "parse_agui_event",
+    "parse_sse",
+    "search_logs",
+    "service_endpoint",
+    "start_policy_generation",
+    "start_recommendation",
+    "stop_runtime_session",
+    "stream_logs",
+    "update_payment_credential_provider",
+    "with_target_region",
+]

agentcore/aws/_aws_errors.py

@@ -0,0 +1,72 @@
+"""Uniform access to AWS error metadata across botocore and the CLI's own HTTP errors.
+
+Upstream inspects SDK v3 exceptions via ``err.name`` / ``err.message`` /
+``err.$metadata.httpStatusCode``. botocore's ``ClientError`` carries the same data in
+``err.response``; these helpers hide the difference.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def aws_error_name(err: object) -> str | None:
+    """Service error code (``ClientError`` ``Error.Code``), else ``err.name`` / ``err.code``."""
+    if err is None:
+        return None
+    response = getattr(err, "response", None)
+    if isinstance(response, dict):
+        code = response.get("Error", {}).get("Code")
+        if code:
+            return str(code)
+    for attr in ("name", "code"):
+        value = getattr(err, attr, None)
+        if isinstance(value, str) and value:
+            return value
+    if isinstance(err, dict):
+        value = err.get("name") or err.get("code") or err.get("Code")
+        return value if isinstance(value, str) else None
+    return type(err).__name__ if isinstance(err, BaseException) else None
+
+
+def aws_http_status(err: object) -> int | None:
+    response = getattr(err, "response", None)
+    if isinstance(response, dict):
+        status = response.get("ResponseMetadata", {}).get("HTTPStatusCode")
+        if isinstance(status, int):
+            return status
+    for attr in ("status_code", "statusCode"):
+        value = getattr(err, attr, None)
+        if isinstance(value, int):
+            return value
+    if isinstance(err, dict):
+        value: Any = err.get("statusCode")
+        if not isinstance(value, int):
+            value = (err.get("$metadata") or {}).get("httpStatusCode")
+        return value if isinstance(value, int) else None
+    return None
+
+
+def get_error_message(err: object) -> str:
+    """Equivalent of ``err instanceof Error ? err.message : String(err)``.
+
+    For a botocore ``ClientError`` this is the service's own message (as SDK v3's ``err.message``),
+    not botocore's "An error occurred (X) when calling Y" wrapper.
+    """
+    response = getattr(err, "response", None)
+    if isinstance(response, dict):
+        message = response.get("Error", {}).get("Message")
+        if message:
+            return str(message)
+    message = getattr(err, "message", None)
+    if isinstance(message, str):
+        return message
+    return str(err)
+
+
+def is_access_denied_error(err: object) -> bool:
+    return aws_error_name(err) in ("AccessDeniedException", "AccessDenied")
+
+
+def is_not_found_error(err: object) -> bool:
+    return aws_error_name(err) in ("ResourceNotFoundException", "NotFoundException")

agentcore/aws/_http.py

@@ -0,0 +1,176 @@
+"""Minimal HTTP + SigV4 layer for AgentCore APIs that upstream calls with ``fetch``.
+
+Upstream signs requests with ``@smithy/signature-v4`` and sends them with ``fetch``. Here botocore's
+``SigV4Auth`` signs an ``AWSRequest`` and urllib3 (bundled with botocore) sends it. Retries are
+disabled to mirror ``fetch``; callers that retry do so explicitly.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Iterator, Mapping
+from functools import lru_cache
+from typing import Any
+from urllib.parse import quote, urlencode
+
+import urllib3
+from botocore.auth import SigV4Auth
+from botocore.awsrequest import AWSRequest
+from botocore.exceptions import NoCredentialsError
+from botocore.httpsession import get_cert_path
+
+from agentcore.aws.account import get_credential_provider
+
+DEFAULT_SERVICE = "bedrock-agentcore"
+_READ_CHUNK = 65536
+
+
+def encode_uri_component(value: str) -> str:
+    """JavaScript ``encodeURIComponent``."""
+    return quote(value, safe="!~*'()")
+
+
+def query_string(params: Mapping[str, Any]) -> str:
+    """``?k=v&...`` for truthy values (as ``URLSearchParams`` populated with ``if (x) params.set(...)``)."""
+    pairs = {k: str(v) for k, v in params.items() if v}
+    return f"?{urlencode(pairs)}" if pairs else ""
+
+
+@lru_cache(maxsize=1)
+def _pool() -> urllib3.PoolManager:
+    return urllib3.PoolManager(ca_certs=os.environ.get("AWS_CA_BUNDLE") or get_cert_path(True))
+
+
+class HttpResponse:
+    """Thin wrapper over a urllib3 response exposing the ``fetch`` ``Response`` surface we use."""
+
+    def __init__(self, raw: urllib3.BaseHTTPResponse):
+        self._raw = raw
+        self._body: bytes | None = None
+
+    @property
+    def status(self) -> int:
+        return self._raw.status
+
+    @property
+    def ok(self) -> bool:
+        return 200 <= self._raw.status < 300
+
+    @property
+    def reason(self) -> str:
+        return self._raw.reason or ""
+
+    @property
+    def headers(self) -> Mapping[str, str]:
+        """Case-insensitive response headers."""
+        return self._raw.headers
+
+    def header(self, name: str) -> str | None:
+        return self._raw.headers.get(name)
+
+    def read(self) -> bytes:
+        if self._body is None:
+            self._body = self._raw.data or b""
+            self._raw.release_conn()
+        return self._body
+
+    def text(self) -> str:
+        return self.read().decode("utf-8", errors="replace")
+
+    def json(self) -> Any:
+        return json.loads(self.read())
+
+    def iter_bytes(self) -> Iterator[bytes]:
+        """Yield body chunks as they arrive (for SSE / event-stream responses)."""
+        if self._body is not None:
+            if self._body:
+                yield self._body
+            return
+        try:
+            yield from iter_stream_chunks(self._raw)
+        finally:
+            self._raw.release_conn()
+
+    def close(self) -> None:
+        self._raw.release_conn()
+
+
+def iter_stream_chunks(stream: Any) -> Iterator[bytes]:
+    """Yield chunks from a urllib3 response or botocore ``StreamingBody`` without waiting for full buffers.
+
+    ``read(n)`` blocks until ``n`` bytes arrive, which would stall incremental SSE output, so prefer
+    chunked reads / ``read1``.
+    """
+    raw = getattr(stream, "_raw_stream", stream)
+    if isinstance(raw, urllib3.BaseHTTPResponse) and raw.chunked and raw.supports_chunked_reads():
+        for chunk in raw.read_chunked():
+            if chunk:
+                yield chunk
+        return
+    reader = getattr(raw, "read1", None) or raw.read
+    while True:
+        chunk = reader(_READ_CHUNK)
+        if not chunk:
+            return
+        yield chunk
+
+
+def http_request(
+    method: str,
+    url: str,
+    *,
+    headers: Mapping[str, str] | None = None,
+    body: bytes | str | None = None,
+    timeout: float | None = None,
+    stream: bool = False,
+) -> HttpResponse:
+    """Plain (unsigned) HTTP request; network errors propagate as urllib3 exceptions."""
+    data = body.encode("utf-8") if isinstance(body, str) else body
+    raw = _pool().request(
+        method,
+        url,
+        headers=dict(headers or {}),
+        body=data,
+        preload_content=not stream,
+        redirect=False,
+        retries=False,
+        timeout=urllib3.Timeout(total=timeout) if timeout is not None else urllib3.Timeout(connect=60, read=None),
+    )
+    return HttpResponse(raw)
+
+
+def sign_headers(
+    method: str,
+    url: str,
+    *,
+    region: str,
+    headers: Mapping[str, str] | None = None,
+    body: bytes | str | None = None,
+    service: str = DEFAULT_SERVICE,
+) -> dict[str, str]:
+    """SigV4-sign a request and return the full header set to send (including ``Authorization``)."""
+    credentials = get_credential_provider()()
+    if credentials is None:
+        raise NoCredentialsError()
+    data = body.encode("utf-8") if isinstance(body, str) else body
+    request = AWSRequest(method=method, url=url, headers=dict(headers or {}), data=data)
+    SigV4Auth(credentials, service, region).add_auth(request)
+    return {k: v for k, v in request.headers.items()}
+
+
+def signed_request(
+    method: str,
+    url: str,
+    *,
+    region: str,
+    body: str | None = None,
+    headers: Mapping[str, str] | None = None,
+    timeout: float | None = None,
+    stream: bool = False,
+) -> HttpResponse:
+    """SigV4-signed JSON request (``Content-Type: application/json``), as upstream's ``signedRequest`` helpers."""
+    request_headers = {"Content-Type": "application/json", **(headers or {})}
+    payload = body if body else None
+    signed = sign_headers(method, url, region=region, headers=request_headers, body=payload)
+    return http_request(method, url, headers=signed, body=payload, timeout=timeout, stream=stream)