Setting the file. One moment.
Subchapter 14.4
references/local-vs-deployed.mdMarkdown4 KBView on GitHub
AgentCore has a local dev server (agentcore dev) and a deployed runtime. They don’t have feature parity. This reference tells you what works where so generated code and troubleshooting handle both environments correctly.
Scripts
Process Payment Tool| Feature | agentcore dev (local) | Deployed runtime |
|---|---|---|
| Agent invocation | ✅ via curl on localhost:8080 | ✅ via invoke_agent_runtime or HTTPS |
| Framework model calls | ✅ if Bedrock creds are available | ✅ |
| Python/JS function tools (framework-native) | ✅ | ✅ |
Credentials (@requires_api_key, @requires_access_token) | ✅ from agentcore/.env.local | ✅ from Secrets Manager |
| Memory | ❌ env var not set locally | ✅ MEMORY_<NAME>_ID injected |
| Gateway | ❌ env var not set locally | ✅ AGENTCORE_GATEWAY_<NAME>_URL injected |
| Cedar policy evaluation | ❌ policies only enforced at gateway | ✅ |
| Traces (X-Ray) | ✅ agentcore dev emits OTEL to CloudWatch by default; disable with --no-traces | ✅ auto-enabled |
| CloudWatch logs | ✅ via ADOT / OTEL wiring (same path as traces) | ✅ if using logging module + OTEL |
Evaluator definition (agentcore add evaluator, writing the instructions/code) | ✅ — writes to agentcore.json; custom code is unit-testable locally | ✅ |
agentcore run eval (on-demand eval over traces) | ✅ — operates on CloudWatch spans; local-dev spans land there if OTEL is on (default) | ✅ |
Evaluate API with hand-constructed spans (boto3) | ✅ — no runtime needed at all; submit SessionSpans directly | ✅ |
Dataset runner (OnDemandEvaluationDatasetRunner) | ❌ invokes an AgentCore Runtime agent in its pipeline | ✅ |
Online eval monitoring (agentcore add online-eval) | ❌ ingests traces continuously from deployed runtime | ✅ |
| Observability dashboards | ✅ once Transaction Search is on and local spans are flowing | ✅ in CloudWatch console |
| VPC networking | ❌ local always has internet | ✅ subject to networkMode: VPC |
| Inbound auth (AWS_IAM, CUSTOM_JWT) | ❌ no auth required locally | ✅ enforced on every request |
Always guard features that aren’t available locally:
# Memory pattern
MEMORY_ID = os.getenv("MEMORY_MYMEMORY_ID")
if MEMORY_ID:
# deployed — wire up memory
session_manager = AgentCoreMemorySessionManager(...)
else:
# local — agent runs without memory
session_manager = None# Gateway pattern
GATEWAY_URL = os.getenv("AGENTCORE_GATEWAY_WEATHER_URL")
if GATEWAY_URL:
# deployed — use gateway tools
tools = get_gateway_tools(GATEWAY_URL)
else:
# local — agent runs without external tools or with local stubs
tools = []Credentials work in both, but read from different sources. The @requires_api_key decorator handles this automatically — don’t try to read env vars directly.
Because memory, gateway, and policies don’t work locally, the realistic test loop is:
agentcore dev to verify the agent’s code structure, framework wiring, system prompt, and any in-code logicagentcore deploy --target staging to test with real memory, gateway, and policiesDon’t expect agentcore dev to reproduce a production failure involving memory recall, gateway tool calls, or policy denials — those require a deployed environment.
MEMORY_<NAME>_ID guard — code crashes because the env var is unexpectedly presentAGENTCORE_GATEWAY_<NAME>_URLaws configure (used locally) and aws-targets.json (used in deploy)