Skip to content

AgentCore Support (2/3) - Add Python and TypeScript SDK guides - #26

Open
justinschoeff wants to merge 170 commits into
agentcore/referencesfrom
agentcore/sdk-guides
Open

justinschoeff wants to merge 170 commits into
agentcore/referencesfrom
agentcore/sdk-guides

Conversation

@justinschoeff

@justinschoeff justinschoeff commented Oct 7, 2026 •

Copy link
Copy Markdown

AgentCore Support (2/3). Stacked on #25 (agentcore/references), which is based on main after #31 and #30. (3/3) is #27. This PR adds the per-SDK entry-point guides that setup.md Step 2 points to.

What changed in this update

  • One squashed commit, rebased with the stack onto current main. No conflicts in this PR's files.
  • Review fixes folded in: guide rules stated directly; the Python handler assembly and packaging clarified; the TypeScript handler verified end to end and its scaffold gaps fixed; TypeScript AgentCore support stated as confirmed; Region-scoped commands; Bedrock model access noted for the sample.

Changes

  • references/aws-agentcore/sdk-python.md: built on the AWS bedrock-agentcore package (BedrockAgentCoreApp serves /invocations and /ping). It covers:
    • the CodeZip layout and dependencies, and the versioned Worker;
    • the async-task handler and the ActivityTracker idle and drain policy;
    • the API key read from Secrets Manager (the hand-off in setup.md), Heartbeats and log signatures.
    • It links to the strands_agent sample and notes that the sample needs Bedrock model access.
  • references/aws-agentcore/sdk-typescript.md: the same plan, built on the bedrock-agentcore npm package. It uses the CLI's Container build, because the Node CodeZip packager (esbuild on main.ts, no node_modules) can't bundle @temporalio/worker. Its Dockerfile is based on the CLI's own template:
    • It compiles with tsc and runs dist/main.js, so workflowsPath resolves.
    • It installs ca-certificates, which fixes the NativeCertsNotFound TLS failure.
    • It has no sample link, because no TypeScript sample exists.
  • Both guides link to the durable-agent-on-AgentCore guide instead of reproducing it.

Validation

…io/skill-temporal-serverless into cloud-run-sdk-guides
…-temporal-serverless into cloud-run-sdk-guides
…ill-temporal-serverless into cloud-run-skill-support
…-temporal-serverless into cloud-run-sdk-guides
…-temporal-serverless into cloud-run-sdk-guides
…ill-temporal-serverless into cloud-run-skill-support
harish-narayanappa-10 and others added 18 commits October 5, 2026 16:40
The provider is now settled in step 1 by deriving it from the
Namespace or asking, and the agent states it to the user. Move the
tcld sign-in rule ahead of the Namespace discovery calls it governs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Give the registration-race check a stopping point that leads to the
provisioning diagnosis, say to wait a few minutes before the single
IAM-propagation retry, and take only the Collector configuration from
the samples-go Cloud Run sample, whose Worker Pool manifest is
unversioned.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The OpenTelemetry path deploys a multi-container manifest with
gcloud run worker-pools replace, so the variable belongs in the Worker
container's env rather than a deploy flag.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
With two providers and the Cloud Run API-key requirement, a Namespace
can be ineligible because its cloud is unsupported, because it accepts
only mTLS, or because it does not match the requested provider.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e pool

Step 8 now starts whatever Workflow type and input the deployed Worker
registers, with the SDK guide samples as defaults, and notes that
interrupting workflow execute leaves the Workflow running. The pool
log queries and the UpdateWorkerPool audit query are scoped to the
pool's name and region; both labels are present on container output
and on the resize audit entries.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A healthy Java Worker can complete Workflows and Activities without
per-task SDK log lines. Confirm execution from the Workflow history,
and use SLF4J's no-provider warning, not the stdout startup line, to
tell whether logging is bound.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Ask the user to run tcld login in their own terminal without naming a
client. Offer every eligible Namespace as an option when they fit in a
structured question; otherwise print the complete numbered list and
let the user reply with a number, never offering only a subset.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Temporal assumes an IAM role to get and invoke a named AgentCore
Runtime endpoint. Ship both variants next to the Lambda templates so
the references can point at local, reviewable copies: the Cloud
template byte-identical to Temporal's S3 copy, and the self-hosted
template from the docs, which trusts a TemporalIamRoleArn principal.
Document AgentCore Runtime's execution model for Serverless Workers:
the 8-hour microVM lifetime, the two independent stop controls
(Worker idle policy vs AgentCore lifecycle settings), and why each
Worker Deployment Version must map to its own named endpoint rather
than the moving DEFAULT endpoint. Every claim cites its source.
AgentCore has no Temporal troubleshooting page, so diagnostics is
limited to documented gotchas (endpoint vs Runtime ARN, missing ARN
wildcard, name mismatches, DEFAULT drift, sessions stuck HealthyBusy)
plus the shared WCI inspection flow. Waits are gated on observable
registration state, not test-run durations.
Cover the AgentCore CLI + CodeZip deploy path (no Docker or ECR), the
three identities involved (operator, Runtime execution role, Temporal
invocation role) and a complete self-hosted Temporal Service guide,
since AgentCore supports self-hosting from v1.32.0. Namespace
selection lists every AWS-hosted Namespace and confirms Pre-release
access before deploying.
Give the skill the language-specific half of setup.md Step 2 for
Python: bedrock-agentcore's BedrockAgentCoreApp serves /invocations and
/ping, the handler starts a versioned Worker as an AgentCore async task,
and an Activity-tracking idle policy drains it so the session does not
stay HealthyBusy until maxLifetime. Code and settings follow the
samples-python strands_agent sample, which the guide links to.

@starfleeth starfleeth left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please replace the narrative about unsourced TypeScript details and a future end-to-end run with an explicit support status and known limitations. The validation section can also report outcomes directly without git diff commands or the history of which branch introduced the validator error. If the base error still matters, link its tracking issue.

app.run()
```

The sample falls back to defaults when these variables are unset; this version reads `os.environ[...]` so a missing setting fails at startup instead of polling the wrong Namespace or Task Queue. If an Activity is a synchronous function, pass an `activity_executor` such as a `ThreadPoolExecutor` to `Worker()`, as the sample does for `execute_code`. <!-- samples-python/bedrock_agentcore/strands_agent/agentcore_worker.py:48-50; docs/develop/python/workers/serverless-workers/agentcore.mdx:95-102 -->

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

“This version reads…” narrates how this example was authored relative to the upstream sample. Could you state the behavior directly instead? For example: “Read these values with os.environ[...] so a missing setting fails at startup instead of silently selecting the wrong Namespace or Task Queue.”

Mirror the Python guide's structure for TypeScript using the AWS
bedrock-agentcore npm package and the standard Temporal TypeScript SDK.
Temporal publishes no TypeScript AgentCore code or sample, so the guide
marks every unpublished detail (esbuild and workflowsPath, core-bridge
arm64 packaging, SIGTERM on compute end) as not covered by the docs so
the consuming agent verifies it instead of asserting it.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants