How to run a first LangChain agent

The LangChain Python quickstart shows how to create a fully functional AI agent in just a few minutes. You install the package, define one function, and hand create_agent a model string, a tools list, and a system prompt. The agents guide calls create_agent a highly configurable harness. An agent is a model calling tools in a loop until a given task is complete. A harness is everything around that loop: the prompt, the tools, and any middleware that shapes the model's behavior. The job of a harness is to get the model the right context at the right time for the given task.

Use create_agent when you need to configure the harness yourself. Deep Agents builds on create_agent and comes with commonly useful capabilities already assembled, such as planning, file system tools, subagents, and memory. This article stays on the first quickstart agent. It does not walk through middleware or the page's later research agent.

Install dependencies

The uv path pins Python 3.11, creates a project, adds LangChain, and syncs:

uv python pin 3.11
uv init
uv add langchain
uv sync

The pip alternative says to install Python 3.11+ separately if needed:

# Install Python 3.11+ separately if needed.
pip install -U langchain

The venv alternative on the same page is:

# Install Python 3.11+ separately if needed.
python3.11 -m venv .venv
source .venv/bin/activate
# Windows: .venv\Scripts\activate
pip install -U langchain

Set up API keys

Get an API key from any supported model provider. The quickstart names Google Gemini and OpenAI as examples, and the same section has shell and .env snippets for other providers. For the OpenAI tab, export:

export OPENAI_API_KEY="your-api-key"

or put this in a .env file:

OPENAI_API_KEY=your-api-key

The Google Gemini shell export is export GOOGLE_API_KEY="your-api-key". The Claude tab uses export ANTHROPIC_API_KEY="your-api-key". Use the variable from the tab that matches the model you will pass. To load a .env file, the quickstart says to use python-dotenv and load_dotenv(). It does not show an import, so the shell export is the setup the page spells out completely.

You can use any supported model by changing the model name and setting up the appropriate API key.

Build a basic agent

The basic agent can answer questions and call tools. It uses the chosen language model, a basic weather function, and a simple prompt. The OpenAI tab is this script:

from langchain.agents import create_agent

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

agent = create_agent(
    model="openai:gpt-5.5",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "What's the weather in San Francisco?"}]}
)
print(result["messages"][-1].content_blocks)

get_weather is a plain Python function, passed in tools with no decorator. The agents guide says to pass any Python callable, a LangChain tool, or a tool dict. Later on the quickstart, the docs say a tool's name, description, and argument names become part of the model's prompt.

Configure the basics with model=, tools=, and system_prompt=.

Pass a model identifier string ("provider:model") or an initialized model instance. The OpenAI script uses the string form. Other tabs change the model name and expect the matching key. The Azure tab is a different shape: it builds a model with init_chat_model and passes that instance into create_agent.
tools holds the callables the model may use. This list contains only get_weather.
system_prompt shapes how the agent approaches tasks. It accepts a string or a SystemMessage. The OpenAI script sets that parameter to the short assistant string already shown in the call above.

The agents page also shows a shorter call with only model and tools. The quickstart version, which includes the system prompt, is the one to run first. In the page's later research-agent section, the docs say the system prompt defines the agent's role and behavior and should be kept specific and actionable. You do not need that longer prompt yet.

What the first invoke does

agent.invoke takes a dictionary with a messages list. The user entry has role set to user and content set to the San Francisco weather question. The agents guide says invoking with a message passes an update to the agent's state, and that all agents include a sequence of messages in that state. The built-in messages field is the full conversation history for the current thread. It is append-only: new messages are added, never replaced.

The script's last line prints the content blocks on the final message. The quickstart does not show a sample printout for this weather run. What the page does state is the tool decision: when you run the code and prompt the agent about the weather in San Francisco, the agent uses that input and its available context. It understands that you are asking about the weather for the city San Francisco and therefore calls the weather tool with the provided city name.

invoke returns the final response at the end of a run. The weather script does not pass a thread_id. Persisting conversation history with thread_id requires a checkpointer. On a LangSmith deployment, a checkpointer is provisioned automatically. Locally, pass one explicitly, for example create_agent(..., checkpointer=InMemorySaver()), and reuse the same thread_id on a later invoke. thread_id scopes the conversation (message history and checkpoints). Per-run data for tools and middleware, such as a user ID, is a separate context argument. The first script uses neither.

After the first run

Middleware extends the harness after this first call. The agents page groups that work as execution environment, context management, planning and delegation, fault tolerance, guardrails, and steering. The quickstart's next example is a research agent that also runs create_deep_agent beside create_agent. Use deep agents when you want maximum capability with minimal setup, and LangChain agents when you need fine-grained control.

To inspect the loop, sign up for a LangSmith account and set:

export LANGSMITH_TRACING="true"
export LANGSMITH_API_KEY="..."

Run the script again and inspect the agent calls. The quickstart also recommends LangSmith Engine, which monitors traces, detects issues, and proposes fixes.

Try this next

Run the OpenAI script, or the quickstart provider tab that matches your key, and ask the documented San Francisco weather question. Then read the agents guide on model, tools, and system prompt before you add a checkpointer or continue into the quickstart's research-agent example.