Skip to main content

Quick Start: Conversational Agent

Who this is for

Developers ready to build a code-first conversational agent from a maintained sample. If you'd rather declare the agent as configuration without writing Runtime code, use the Harness Quick Start. Still deciding whether conversational is the right workload? Start with the Conversational overview.

Find the right conversational sample for your use case, understand the risks, and get to working code fast.

Choose this workload when

  • A human is the primary trigger — they type a message and expect a real-time response
  • Multi-turn conversation state matters — the agent should remember what was said
  • You need identity-scoped memory so each user has their own conversation context
  • The agent acts on behalf of a specific user with their permissions (OAuth bearer tokens)
  • The primary output is natural language directed at a human, optionally with tool results

Start with the canonical tutorial

Conversational Agent Catalog

Browse maintained conversational agent samples with identity, memory, and streaming built in. Each sample includes deployment instructions, configuration, and test scripts maintained by the AgentCore team.

Why it fits

The conversational catalog provides ready-to-deploy samples that handle the hardest parts of conversational AI: identity propagation, session memory, streaming responses, and tool orchestration. Start here and customize rather than building from scratch.

Choose an alternative when

Safety and production boundary

Action risk: Read-only by default

The default catalog samples read data and return responses without mutating external state. Tool-calling alternatives (Customer Support, Incident Response, Market Trends) may invoke external APIs, execute lookups against live systems, or perform browser actions — review each sample's README for its specific action scope and any policy guards.

This sample creates a working prototype. It is not production-ready. Before routing real users or production data, complete the Production Readiness checklist.

Central next steps

Identity Management​

  • Every conversational agent must propagate end-user identity. Use OAuth bearer tokens from your IdP (Entra ID, Okta, Cognito) so the agent acts as the user, not as a shared service account. See Understanding workload identities for how this fits AgentCore's identity model.
  • Memory is namespaced by actor_id — never share one actor ID across multiple users, or their conversations will bleed together. See Per-user memory scoping with actor ID.
  • Validate caller-supplied identity headers against a verified source (JWT claims from AgentCore Identity or your own auth layer) before production use. The JWT-based identification pattern is recommended for production; the JWT inbound + OAuth outbound sample shows the full end-to-end flow.

Session Continuity​

  • Configure both short-term (in-session) and long-term (cross-session) memory strategies so the agent remembers context within a conversation and user preferences across sessions.
  • Use unique session IDs per conversation. Reuse a session ID only when you want to resume the same conversation thread. See Memory organization for how strategy/actor/session namespaces work.
  • Plan context window strategies (summarization, truncation) for long conversations that approach model limits. AgentCore Memory supports namespace-scoped long-term storage to retain summaries across sessions without exhausting the context window.

Safe First-Deployment Patterns​

  • Deploy with scale-to-zero to avoid charges when idle, but remember that Memory records and CloudWatch logs still accrue cost. Review the Runtime lifecycle settings for idle timeout defaults and configurable values.
  • Start with the default model and tools; add capabilities incrementally after validating each works correctly.
  • Use agentcore dev for local iteration before deploying to AWS — local testing verifies agent logic without incurring cloud costs.
  • Review the Production Readiness checklist before routing real users. Note that CLI-generated IAM policies are not suitable for production — create scoped custom policies before serving real traffic.

Resource and Cost Awareness​

Cost DriverWhat Generates ItHow to Manage
Model inference tokensEvery invocation calls the configured LLM; multi-turn conversations multiply token usageChoose model size for your task; monitor token usage; use summarization strategies to avoid replaying full history
Memory — short-term$0.25 per 1,000 new events ingestedSet eventExpiryDuration; clean up test data
Memory — long-term storage$0.75 per 1,000 records stored/month (built-in strategies)Scope retention policies; delete prototype memory resources
Memory — long-term retrieval$0.50 per 1,000 retrievalsRetrieve only when needed; avoid unnecessary recall on every turn
Gateway invocationsEach tool call via Gateway is $0.005 per 1,000 invocationsBatch tool calls where possible; cache results for repeated lookups
Policy authorization$0.000025 per request + $0.13 per 1,000 input tokens processedNegligible at tutorial volume; monitor at scale
Runtime execution (CPU + memory)$0.0895/vCPU-hour + $0.00945/GB-hour while the session is activeScale-to-zero; set idle session timeouts; avoid long-lived idle sessions
Identity token requests$0.010 per 1,000 token requests (free when used through Runtime or Gateway)Typically no cost for standard conversational flows
Log ingestionCloudWatch charges per GB for spans, logs, and metricsSet retention policies; filter verbose output

Scale-to-zero does not mean zero cost. Memory records and log retention continue to accrue charges even with no active traffic. Remove prototype resources when done experimenting. See AgentCore pricing for current rates.

warning

Everything produced by the samples on this page is a prototype until you have applied the controls in Preparing for production. Do not use a prototype endpoint to serve real user traffic.