Choose an agent integration

Choose the agent flow from the task. Then choose its tools, memory, and observability. These choices are independent. For example, both a native create_agent graph and a Deep Agent can use MCP tools.

Start with the least complex flow that meets the requirement. Add delegation or file-based context when a measured task needs it.

Agent patterns

Pattern	Use it for	Main tradeoff
chatbot	Conversation, rewriting, classification, or a response that needs no external tool.	A small execution path. Add explicit retrieval or tools when the model needs current or private information.
create_agent	Support agents that choose among a small set of business tools.	The model selects the tool order. Tool schemas and server permissions must enforce the business boundaries.
create_agent_structured	Extraction or decisions that another program consumes.	The response schema validates shape. The application must still validate business meaning, such as an allowed order status or account ID.
Custom StateGraph	A fixed validation, retrieval, approval, or transaction sequence.	You define state and transitions. This requires more code but makes required steps explicit.
knowledge_base_agent	Answers grounded in documents from Amazon Bedrock Knowledge Bases.	Configure the aws extra, AWS_KB_ID, and AWS access. Retrieval quality and document access control remain application concerns.
supervisor_agent	Routing to a known set of specialist agents with separate tools.	Delegation adds model calls and handoff state. The example has research and arithmetic specialists; adapt those roles to the actual task.
Deep Agents	Research, analysis, and document work that need intermediate files, several steps, or delegated subtasks.	More built-in behavior and context management. Measure latency, model calls, storage growth, and result quality on representative tasks.

The toolkit also retains its custom create_react_agent creator. Keep it when an existing agent depends on its hooks and routing. Prefer the native create_agent path for a new tool agent unless those custom features are required.

Deep Agents builds on create_agent and LangGraph. A custom graph can also become a Deep Agents subagent. See the official ecosystem overview and Deep Agents for the optional integration.

Concrete use cases

Customer support

Use create_agent with narrow tools such as order lookup and shipment status. Add create_agent_structured when the result feeds a ticket router. Pass the authenticated user’s scope to the tool implementation. Do not let a model-selected account ID grant access to another customer’s records.

Policy and product questions

Use a retrieval graph when every answer must consult an approved document collection. The existing knowledge-base blueprint retrieves documents before the model runs. Replace its retriever in a custom graph if your source is not Amazon Bedrock. Return source identifiers and test missing, stale, and contradictory documents.

An agent with a search tool can choose whether to search. A retrieval node in a fixed graph makes that step mandatory. Choose the latter when this is a business requirement.

Research and report preparation

Use Deep Agents when the task needs a working document, independent research tasks, and a final synthesis. Give search tools to a research subagent and writing tools to the agent that produces the report. Keep intermediate files in thread state unless they must be shared across conversations.

This pattern can keep large tool results out of the main prompt. It also adds delegation and summarization work. Compare it with a single create_agent on the same input set before selecting it for a latency-sensitive endpoint. See Deep Agents context management.

Approvals and updates to business systems

Use a custom graph or human-in-the-loop middleware when a person must approve an update. Place approval before the external write. Use an idempotency key in the target API when repeating a request could create another order, payment, or message. A checkpoint records graph progress; it does not make an external side effect atomic with the database.

MCP and direct tools

Use a direct LangChain tool when the application owns a small API client or a database operation. This keeps validation, authorization, and connection ownership in one service.

Use MCP when a service already exposes tools through that protocol, or when several applications need the same tool service. Configure MCP_SERVERS and assign servers with MCP_AGENT_SERVERS. The toolkit discovers tools at worker startup and injects them through each supported agent’s graph factory. See MCP tools for HTTP, stdio, credentials, allowlists, and elicitation.

MCP is a tool transport. It does not add task planning, document retrieval, or authorization by itself. The remote server must enforce access. Toolkit API credentials and MCP credentials serve different connections.

For a large assigned catalog, optional tool selection can reduce the tool definitions visible to each model call. Native agents and Deep Agents can use an LLM selector or supported provider tool search. Keep the default off mode for small catalogs unless a benchmark shows a benefit. Static MCP allowlists and server access checks still apply. See Optional tool selection for the shared configuration and API benchmark.

Memory and persistence

thread_id identifies short-term conversation state. Checkpoints can hold messages, pending interrupts, and Deep Agents state files. Use the configured SQLite or PostgreSQL checkpointer when this state must survive restart.

user_id identifies the scope for long-term user memory. A store or a custom memory service can share selected facts across that user’s threads. Passing user_id alone does not create a store or make a backend user-specific. Set the namespace explicitly and manage its connections in application startup and shutdown.

A thread lock protects one conversation update. It does not serialize writes to the same long-term record from different threads. Use atomic store operations or a separate concurrency rule for such records.

Clearing conversation history removes checkpoints for that conversation. Long-term memory and external files need their own retention and deletion rules. See Migrate to the current release and Deployment and Recovery for the service contract.

Choose an observability backend

Set OBSERVABILITY_BACKEND to select one backend for the service. Install its package extra in the application environment. This choice does not change the agent builder, tools, or checkpointer.

Observability choices

Backend	Choose it for	Toolkit contract and limits
langfuse	Existing Langfuse projects, prompt versions, and user feedback.	Per-run callbacks, remote prompts, and scores. Select an SDK for the server version. SDK v2 cannot delete prompts through the toolkit. See Langfuse compatibility.
phoenix	OpenInference traces in Phoenix, with self-hosted or remote storage.	Per-run callbacks, remote prompt versions, and trace annotations. Prompt creation needs model metadata. Prompt formats and version selectors differ from Langfuse. See Phoenix observability.
langsmith	LangSmith tracing and its prompt repository.	SDK tracing configured through LANGSMITH_*, prompt operations, and feedback. The adapter uses the LangSmith SDK tracing lifecycle.
empty or unset	Local development that needs no remote trace service.	In-process prompts. No remote traces or feedback storage.

The common interface does not provide every feature of each platform. For example, Phoenix datasets and experiments use its native client. Switching OBSERVABILITY_BACKEND does not move existing traces, prompts, or feedback to another service. Create prompts in the selected service and check their formats before changing a deployment.

Observe and test the selected combination

Record tool failures, model-call counts, elapsed time, and successful task outcomes. Check whether delegated runs preserve the parent trace and user scope. Use the configured observability backend. See Langfuse compatibility and Phoenix observability for their tested SDK and server boundaries.

Test the whole combination that you deploy: agent builder, model, tools, database, and observability SDK. The deterministic examples verify execution and state behavior. They do not establish the quality or cost of a real model. Use a small representative evaluation set before changing an existing service to a more complex agent flow. See Testing for the test layers.