ChatPromptTemplate is missing the variable agent_scratchpad
Input to ChatPromptTemplate is missing variables {'agent_scratchpad'}Short answer
A tool-calling agent keeps its tool calls and tool results in a prompt slot named agent_scratchpad. If your ChatPromptTemplate has no such placeholder, or you call the prompt by hand without it, LangChain reports missing variables. Add a placeholder for agent_scratchpad, or move to create_agent, which needs no scratchpad in the prompt.
Fix it fast
1Find out which cause you have
Print the variables your prompt expects, then compare them with the keys you pass. agent_scratchpad should come from the agent, never from your own dictionary.
python -c "from my_agent import prompt; print(prompt.input_variables, prompt.optional_variables)"2Match what you see, then jump to its fix
What does the error look like?
Input to ChatPromptTemplate is missing variables {'agent_scratchpad'}Expected: ['agent_scratchpad', 'input']
Cause 1 of 2
The prompt has no placeholder for the scratchpad
1Check
The reference for create_tool_calling_agent says the prompt must include an agent_scratchpad key and that it must be a MessagesPlaceholder. Intermediate actions and tool output are passed through it.
grep -n "agent_scratchpad" *.py2Fix
Add the placeholder as the last message, after the human input.
from langchain_core.prompts import ChatPromptTemplate
prompt = ChatPromptTemplate.from_messages([
("system", "You are a helpful assistant"),
("human", "{input}"),
("placeholder", "{agent_scratchpad}"),
])3Verify
Run the agent through an executor. The executor fills the scratchpad on every step.
from langchain_classic.agents import AgentExecutor, create_tool_calling_agent
agent = create_tool_calling_agent(llm, tools, prompt)
print(AgentExecutor(agent=agent, tools=tools).invoke({"input": "hello"}))Confirmed by reference.langchain.com
Cause 2 of 2
Using the old agent builders on LangChain 1.x
1Check
The v1 migration guide says create_react_agent is replaced by create_agent, and that the prompt= argument is renamed system_prompt=.
python -m pip list | grep -i langchain2Fix
Use create_agent with a plain system prompt. You pass messages instead of an input key, so no prompt template and no scratchpad variable exist.
from langchain.agents import create_agent
agent = create_agent(
model=llm,
tools=tools,
system_prompt="You are a helpful assistant.",
)
result = agent.invoke({"messages": [{"role": "user", "content": "hello"}]})3Verify
The last message in the result holds the answer.
print(result['messages'][-1].content)Confirmed by docs.langchain.com
How do I stop it coming back?
- Keep the scratchpad placeholder as the last item of any prompt used by a tool-calling agent.
- Never put agent_scratchpad in the dictionary you pass to invoke; the executor supplies it.
- For new projects start with create_agent, since the older agent builders now live in langchain-classic.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
- MenuloA restaurant discovery platform in Germany, kept current by a Python ingestion pipeline.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
AI
LangChain no longer exports AgentExecutor from langchain.agents
ImportError: cannot import name 'AgentExecutor' from 'langchain.agents'
LangChain v1 moved legacy classes into a separate package called langchain-classic, and AgentExecutor lives there now.
2 causes, each with a fixAI
Azure OpenAI says the API deployment for this resource does not exist
The API deployment for this resource does not exist
Azure OpenAI does not take a model name in the model field.
2 causes, each with a fixAI
Azure OpenAI fails with an SSL certificate verification error
httpx.ConnectError: [SSL: CERTIFICATE_VERIFY_FAILED]
The client checks the endpoint's certificate against its CA bundle, which is certifi by default.
2 causes, each with a fixAI
LangChain says it could not import the chromadb package
ImportError: Could not import chromadb python package. Please install it with `pip install chromadb`.
The message comes from LangChain's old Chroma class, which cannot import chromadb in the Python that runs your code.
2 causes, each with a fixAI
Gemini API returns 429 RESOURCE_EXHAUSTED on the free tier
429 RESOURCE_EXHAUSTED
Gemini limits are applied per Google Cloud project, not per API key, so a new key in the same project does not reset anything.
3 causes, each with a fixAI
ConversationalRetrievalChain cannot be imported from langchain.chains
Importing ConversationalRetrievalChain from langchain.chains isn't working
In LangChain v1 the legacy chains moved out of the langchain package into langchain-classic, so langchain.chains no longer has ConversationalRetrievalChain.
2 causes, each with a fix