Agents

import AgentInvocationThreadAndContextJs from '/snippets/code-samples/agent-invocation-thread-and-context-js.mdx'; import AgentInvocationThreadAndContextPy from '/snippets/code-samples/agent-invocation-thread-and-context-py.mdx'; import AgentInvocationThreadIdJs from '/snippets/code-samples/agent-invocation-thread-id-js.mdx'; import AgentInvocationThreadIdPy from '/snippets/code-samples/agent-invocation-thread-id-py.mdx'; import AgentsAgentStateJs from '/snippets/code-samples/agents-agent-state-js.mdx'; import AgentsAgentStatePy from '/snippets/code-samples/agents-agent-state-py.mdx'; import AgentsContextManagementJs from '/snippets/code-samples/agents-context-management-js.mdx'; import AgentsContextManagementPy from '/snippets/code-samples/agents-context-management-py.mdx'; import AgentsExecutionEnvironmentJs from '/snippets/code-samples/agents-execution-environment-js.mdx'; import AgentsExecutionEnvironmentPy from '/snippets/code-samples/agents-execution-environment-py.mdx'; import AgentsFaultToleranceJs from '/snippets/code-samples/agents-fault-tolerance-js.mdx'; import AgentsFaultTolerancePy from '/snippets/code-samples/agents-fault-tolerance-py.mdx'; import AgentsGuardrailsJs from '/snippets/code-samples/agents-guardrails-js.mdx'; import AgentsGuardrailsPy from '/snippets/code-samples/agents-guardrails-py.mdx'; import AgentsIntroJs from '/snippets/code-samples/agents-intro-js.mdx'; import AgentsIntroPy from '/snippets/code-samples/agents-intro-py.mdx'; import AgentsModelJs from '/snippets/code-samples/agents-model-js.mdx'; import AgentsModelPy from '/snippets/code-samples/agents-model-py.mdx'; import AgentsNameJs from '/snippets/code-samples/agents-name-js.mdx'; import AgentsNamePy from '/snippets/code-samples/agents-name-py.mdx'; import AgentsPlanningDelegationJs from '/snippets/code-samples/agents-planning-delegation-js.mdx'; import AgentsPlanningDelegationPy from '/snippets/code-samples/agents-planning-delegation-py.mdx'; import AgentsSteeringJs from '/snippets/code-samples/agents-steering-js.mdx'; import AgentsSteeringPy from '/snippets/code-samples/agents-steering-py.mdx'; import AgentsStreamingProgressJs from '/snippets/code-samples/agents-streaming-progress-js.mdx'; import AgentsStreamingProgressPy from '/snippets/code-samples/agents-streaming-progress-py.mdx'; import AgentsStructuredOutputJs from '/snippets/code-samples/agents-structured-output-js.mdx'; import AgentsStructuredOutputPy from '/snippets/code-samples/agents-structured-output-py.mdx'; import AgentsSystemPromptJs from '/snippets/code-samples/agents-system-prompt-js.mdx'; import AgentsSystemPromptPy from '/snippets/code-samples/agents-system-prompt-py.mdx'; import AgentsToolsJs from '/snippets/code-samples/agents-tools-js.mdx'; import AgentsToolsPy from '/snippets/code-samples/agents-tools-py.mdx';

An agent is a model calling tools in a loop until a given task is complete.

src="/oss/images/core_agent_loop.svg"
alt="Core agent loop diagram"
style={{height: "300px", width: "auto", justifyContent: "center"}}
className="rounded-lg block mx-auto"

/>

A harness is everything around that loop: the prompt, the tools, and any middleware that shapes the model's behavior.

Agent = Model + Harness

The job of a harness: get the model the right context at the right time for the given task.

@[create_agent] is a highly configurable harness. At its simplest, you can create one with:

Building on that, you can configure the basics directly with the model=, tools=, and system_prompt= parameters. For more advanced capabilities, extend the harness with middleware.

Deep Agents (opens in a new tab) builds on create_agent and comes with commonly useful capabilities already assembled, such as planning, file system tools, subagents, and memory. Use create_agent when you need to configure the harness yourself.

Core components

src="/oss/images/agent_model_harness.svg"
alt="Agent model and harness components diagram"
style={{height: "280px", width: "auto", justifyContent: "center"}}
className="rounded-lg block mx-auto"

/>

Model

Pass a model identifier string ("provider:model") or an initialized model instance to select the model for your agent. See Models (opens in a new tab) for parameters, provider setup, and dynamic model selection.

Tools

To provide the agent with tools, pass any Python callable, LangChain tool, or tool dict. See Tools (opens in a new tab) for tool definition, context access, and dynamic tool selection.

System prompt

Shape how the agent approaches tasks. The system prompt parameter accepts a string or SystemMessage. For dynamic prompts at runtime, use middleware (opens in a new tab).

Structured output

Return a validated schema from the agent using response_format=. See Structured output (opens in a new tab) for strategies and examples.

Agent state

Every agent manages its execution context through @[AgentState], a typed dictionary that holds the current conversation history and any custom fields your tools and middleware need.

The built-in field is:

AgentState is also the type signature for every node-style middleware hook (before_model, after_model, and similar). Hooks receive the current state and can return a dict of updates to merge back into it.

To add custom fields (for example, a user_id or a counter), subclass AgentState and pass the subclass to create_agent via state_schema=:

For full details, examples, and middleware-level state schemas, see Short-term memory (opens in a new tab) and Custom middleware (opens in a new tab).

Invocation

Trace each step of this loop, debug tool calls, and evaluate agent outputs with LangSmith (opens in a new tab). Follow the tracing quickstart to get set up. We recommend you also set up LangSmith Engine which monitors your traces, detects issues, and proposes fixes.

You can invoke an agent with a message. Behind the scenes that passes an update to the agent's State (opens in a new tab). All agents include a sequence of messages (opens in a new tab) in their state; to invoke the agent, pass a new message along with a thread_id so the agent can persist and resume conversation history:

Persisting conversation history with thread_id requires the agent to be configured with a checkpointer (opens in a new tab). When deployed on LangSmith, a checkpointer is provisioned automatically. Locally, pass one explicitly, for example create_agent(..., checkpointer=InMemorySaver()).

If you also need to pass per-run configuration (such as a user ID, API keys, or feature flags) to tools and middleware, pass it as context alongside config. Define the shape of that data with context_schema and access it through runtime.context:

thread_id scopes the conversation (message history, checkpoints), while context carries per-run data your tools and middleware read at invocation time. Both are commonly passed together. See tool context (opens in a new tab) and Runtime (opens in a new tab) for more.

Streaming

invoke returns the final response at the end of a run. If an agent executes multiple tool calls, users often need progress updates before completion. Use streaming to surface intermediate messages and tool activity as they happen.

For streaming modes, event types, and UI patterns, see Streaming (opens in a new tab).

Configure the harness

create_agent is highly extensible. Middleware is the primitive for customization: each piece handles one concern, hooks into the agent loop at the right moment, and composes freely with any other. Take exactly what your use case needs and skip the rest.

Common patterns are prebuilt as first-class middleware. You can build anything else as custom middleware (opens in a new tab).

src="/oss/images/agent_harness_capabilities.svg"
alt="Agent harness capabilities by category"
style={{height: "300px", width: "auto", justifyContent: "center"}}
className="rounded-lg block mx-auto"

/>

As agents take on complex work, they need support across a few key areas. The middleware ecosystem provides:

• Execution environment:Tools, filesystem, sandboxes, and code execution
• Context management:Summarization, memory, skills, and prompt caching
• Planning and delegation:Todo lists and subagents for parallel, isolated work
• Fault tolerance:Retries, fallbacks, and call limits
• Guardrails:PII detection and content controls
• Steering:Human-in-the-loop approval before high-impact actions

create_deep_agent pre-assembles this stack for long-running coding and research tasks (filesystem, summarization, subagents, and prompt caching included by default). See Deep Agents (opens in a new tab) for the full prebuilt harness.

Execution environment

Agents are especially useful when they can take action rather than just generate text. The execution environment gives the agent a workspace: tools it can call, a filesystem for reading and writing files across turns, and code execution for running scripts or shell commands.

See @[FilesystemMiddleware], Sandboxes (opens in a new tab), Interpreters (opens in a new tab).

This example imports from the deepagents package. Install it with:

pip install deepagents

uv add deepagents

Context management

Every model call has a fixed context window. As an agent runs, that window fills with accumulating history, tool results, and intermediate steps. Summarization compresses history before overflow hits; memory loads persistent instructions at startup so knowledge carries across sessions; skills surface domain knowledge on demand rather than loading everything upfront.

See @[SummarizationMiddleware], @[MemoryMiddleware], Skills (opens in a new tab), Context engineering (opens in a new tab).

This example imports from the deepagents package. Install it with:

pip install deepagents

uv add deepagents

Planning and delegation

Complex tasks often exceed what one context window can handle. Delegation lets the main agent break work into pieces, hand them to subagents that each run in their own isolated context, and stay focused on coordination rather than execution. Work can run in parallel; the main agent's context stays clean.

See Subagents (opens in a new tab).

This example imports from the deepagents package. Install it with:

pip install deepagents

uv add deepagents

Name your agent

Optionally use an identifier for the agent. This is especially useful when embedding the agent as a subgraph in multi-agent (opens in a new tab) systems.

Fault tolerance

Agents in production encounter failures that rarely appear in development: rate limits, model timeouts, transient API errors. Fault tolerance middleware handles these at the infrastructure level so your tools and business logic don't need try/catch around every call.

See @[ModelRetryMiddleware], @[ToolRetryMiddleware], Prebuilt middleware (opens in a new tab).

Guardrails

Some policies can't live in a prompt—they need to be enforced deterministically regardless of what the model does. Guardrails intercept data as it flows through the agent loop, applying compliance rules or content policies before tool results reach the model's context.

See @[PIIMiddleware], Prebuilt middleware (opens in a new tab).

Steering

Full autonomy isn't always appropriate. Steering lets you place humans at specific decision points—before destructive writes, expensive API calls, or anything requiring judgment—without restructuring your agent. The agent pauses and waits; a human approves, edits, or rejects; execution continues.

See @[HumanInTheLoopMiddleware], Human-in-the-loop (opens in a new tab).

Middleware resources

• Middleware overview (opens in a new tab):How the middleware stack works and when hooks fire
• Prebuilt middleware (opens in a new tab):Full reference with configuration examples
• Custom middleware (opens in a new tab):Write your own hooks for business logic, PII scrubbing, and more