Sub-Skill: LangChain / Agent Framework Conventions

Purpose: Prevent common LangChain mistakes — deprecated chain classes, missing retry/timeout guards, unsafe prompt handling, and unobservable pipelines.

Rules

Chain Construction

1. Use LCEL pipe syntax. Always use the LCEL pipe operator (|) to compose runnables instead of deprecated constructor-based chain classes (LLMChain, SequentialChain, TransformChain). Reference: ERR-2026-026
2. Avoid legacy chain imports. Never import from langchain.chains.llm or langchain.chains.sequential; use langchain_core.runnables and langchain_core.prompts instead.
3. Prefer RunnablePassthrough for identity steps. Use RunnablePassthrough to thread context through a chain without mutation rather than writing a lambda that returns its input unchanged.
4. Use RunnableParallel for fan-out. Prefer RunnableParallel over manually calling multiple chains and merging dicts; it expresses intent and enables parallel execution.

Prompts & Output Parsers

1. Use typed output parsers. Always attach an output parser (PydanticOutputParser, JsonOutputParser, StrOutputParser) to chains that produce structured data; never parse raw LLM strings manually downstream.
2. Inject format instructions via partial. Use prompt.partial(format_instructions=parser.get_format_instructions()) to bind parser instructions into the prompt template rather than hard-coding them in the template string.
3. Separate system and human messages. Use ChatPromptTemplate.from_messages([("system", ...), ("human", ...)]) instead of a single PromptTemplate for chat models; mixing roles in one string breaks structured output.

Chat Models vs LLMs

1. Prefer ChatModel over LLM. Always use ChatOpenAI, ChatAnthropic, or equivalent chat-model classes for new code; the base OpenAI LLM class is deprecated for most use cases and lacks tool-calling support.
2. Pin model name explicitly. Never rely on the default model name in a chat model constructor; always pass model="gpt-4o" (or equivalent) so upgrades are intentional.

Memory & State

1. Use RunnableWithMessageHistory for stateful chains. Prefer RunnableWithMessageHistory over manual history management or deprecated ConversationChain; it integrates cleanly with LCEL and supports async.
2. Scope memory by session ID. Always pass a session_id key when constructing RunnableWithMessageHistory to prevent cross-user memory leakage in multi-tenant services.

Tools & Agents

1. Define tools with @tool decorator. Use the @tool decorator (or StructuredTool.from_function) with a typed signature and docstring; never pass raw callables to an agent without a schema.
2. Use create_tool_calling_agent for modern agents. Prefer create_tool_calling_agent + AgentExecutor over deprecated initialize_agent; it uses native tool-calling APIs and avoids ReAct string parsing.
3. Cap agent iterations. Always set max_iterations and max_execution_time on AgentExecutor to prevent runaway loops; default is unbounded.

Retrieval & Vector Stores

1. Use retrieval chains via LCEL. Build RAG pipelines with retriever | format_docs | prompt | llm | parser rather than RetrievalQA.from_chain_type; the latter is deprecated and hides the retrieval step.
2. Ensure document loaders are lazy. Prefer .lazy_load() over .load() for large corpora to avoid loading all documents into memory at once.

Reliability & Observability

1. Wrap LLM calls with retry. Use .with_retry(stop_after_attempt=3, wait_exponential_jitter=True) on any runnable that calls an external API; never let transient rate-limit errors propagate uncaught.
2. Set request timeout. Always pass request_timeout (or timeout) to chat model constructors; omitting it allows indefinitely hanging requests.
3. Attach callbacks for observability. Use callbacks=[LangSmithTracer()] or equivalent on chains in production; never ship a pipeline with no tracing so failures are diagnosable.
4. Count tokens before sending. Before sending large contexts, use llm.get_num_tokens(text) or a tiktoken counter to verify the payload fits within the model's context window.

Security

1. Sanitize user input before prompt injection. Never interpolate raw user strings directly into system prompts; use a dedicated input variable in the prompt template and validate/strip control characters before binding.
2. Disable dangerous tools in untrusted contexts. Avoid giving agents tools with filesystem or shell access when processing untrusted input; scope tool permissions to the minimum required.

Caching & Cost

1. Enable semantic caching in dev. Use set_llm_cache(InMemoryCache()) during development and SQLiteCache in staging to avoid redundant API calls and reduce cost during iteration.

See also

• skills/python/SKILL.md
• skills/error-log/SKILL.md