<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Ravindifernando on Medium]]></title>
        <description><![CDATA[Stories by Ravindifernando on Medium]]></description>
        <link>https://medium.com/@ravindifernando3?source=rss-b63e5c3581dd------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*6cO0H8UOWNVkRzwA</url>
            <title>Stories by Ravindifernando on Medium</title>
            <link>https://medium.com/@ravindifernando3?source=rss-b63e5c3581dd------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Wed, 18 Nov 2026 11:50:22 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@ravindifernando3/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Why Authenticated SSE Streaming Is Harder Than It Looks]]></title>
            <link>https://medium.com/@ravindifernando3/why-authenticated-sse-streaming-is-harder-than-it-looks-717f72f512dc?source=rss-b63e5c3581dd------2</link>
            <guid isPermaLink="false">https://medium.com/p/717f72f512dc</guid>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[server-sent-events]]></category>
            <category><![CDATA[fetch-adapter]]></category>
            <category><![CDATA[axios]]></category>
            <category><![CDATA[streaming]]></category>
            <dc:creator><![CDATA[Ravindifernando]]></dc:creator>
            <pubDate>Tue, 19 May 2026 18:36:29 GMT</pubDate>
            <atom:updated>2026-05-22T08:27:29.046Z</atom:updated>
            <content:encoded><![CDATA[<p>Server-Sent Events (SSE) feel simple in isolation. The server pushes data, the client reads it. But the moment you try to add SSE to a real production application with authentication, an existing HTTP client, and a Web Worker in the picture, the simple examples stop being useful and the real problems begin.</p><p>This is not a tutorial. It is a collection of the specific things that break when you add authenticated streaming to a real system, why they break, and what actually fixes them.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JFMajH5MjRW4dlP6O6KW_g.png" /></figure><h3>EventSource Cannot Do Authenticated Requests</h3><p>Most SSE tutorials start with EventSource. It is the browser’s built in API for consuming SSE, it handles reconnection automatically, and it has excellent browser support.</p><p>It also only supports GET requests and does not allow arbitrary custom headers.</p><p>If your streaming endpoint requires an Authorization header, which most production APIs do, EventSource becomes limiting immediately. Some developers work around this by passing tokens as URL query parameters such as ?token=xyz. Avoid this entirely. Tokens in URLs can end up in server logs, cloud load balancers, browser history, analytics systems, and Referer headers. This is a genuine security issue, not just a stylistic concern.</p><p>The practical alternative is using the native Fetch API with a ReadableStream. This gives you full control over headers, supports POST requests, and works naturally with authenticated APIs.</p><pre>const response = await fetch(&quot;/api/stream&quot;, {<br>  method: &quot;POST&quot;,<br>  headers: {<br>    &quot;Authorization&quot;: `Bearer ${token}`,<br>    &quot;Accept&quot;: &quot;text/event-stream&quot;,<br>    &quot;Content-Type&quot;: &quot;application/json&quot;<br>  },<br>  body: JSON.stringify(payload)<br>});<br><br>// Consume incrementally<br>const reader = response.body.getReader();</pre><p>Instead of waiting for the full response, the body is consumed incrementally through the stream reader. This becomes the foundation for everything else.</p><h3>When Your HTTP Client Sits Behind an Auth Layer</h3><p>The raw fetch approach works perfectly when you control requests directly. In many real applications, you do not. The HTTP layer is usually abstracted behind an SDK or client that handles token injection, refresh logic, retries, and credential storage automatically.</p><p>Those abstractions are commonly built on Axios.</p><p>This is where a subtle limitation appears. Browser side Axios traditionally buffered responses instead of exposing true streaming primitives. Historically, the default browser adapter based on XMLHttpRequest downloaded the entire payload into memory before handing it to your application. That defeats the entire purpose of streaming.</p><p>Axios v1.7.0 stabilized a fetch adapter that enables proper browser streaming support.</p><pre>const response = await axios.post(&quot;/api/stream&quot;, requestBody, {<br>  adapter: &quot;fetch&quot;,<br>  responseType: &quot;stream&quot;,<br>  headers: {<br>    &quot;Authorization&quot;: `Bearer ${token}`,<br>    &quot;Accept&quot;: &quot;text/event-stream&quot;<br>  }<br>});<br><br>const reader = response.data.getReader();</pre><p>A few details matter here:</p><ul><li>adapter: &quot;fetch&quot; enables Fetch based streaming behavior</li><li>responseType: &quot;stream&quot; prevents Axios from treating the response as a single buffered payload</li><li>Without the fetch adapter, browser streaming support becomes inconsistent</li></ul><p>This is easy to miss because the API shape still looks correct even when buffering is happening underneath.</p><p><em>Note: Axios interceptors are fundamentally designed around single-resolution promises. If SSE is the only place in your app where you need streaming, it is often cleaner to bypass Axios entirely for this specific endpoint and use native fetch, allowing you to keep active streams isolated from your global error handlers</em></p><h3>The Web Worker Problem</h3><p>The fetch adapter solves the buffering issue. It does not solve what happens when your authentication layer itself runs inside a Web Worker.</p><p>Some authentication SDKs isolate tokens inside a Web Worker instead of storing them in localStorage or directly exposing them to application code. This reduces XSS exposure and is generally a strong security design.</p><p>The complication appears when streaming enters the picture. The SDK’s HTTP client often resolves requests into ordinary Promise responses rather than exposing a streaming interface across the worker boundary.</p><p>At that point, developers usually face two options:</p><ul><li>bypass the SDK completely and weaken the security model</li><li>extend the SDK with explicit streaming support</li></ul><p>The second approach is the correct one.</p><p>The clean architecture looks like this:</p><ol><li>Keep token retrieval and refresh inside the existing auth layer</li><li>Expose a dedicated streaming method</li><li>Internally use native fetch</li><li>Return response.body directly as a stream</li></ol><p>This keeps authentication concerns and streaming concerns properly separated.</p><h3>Safari and ReadableStream Across Boundaries</h3><p>If your architecture passes a ReadableStream across a postMessage boundary, such as from a Web Worker to the main thread or through a Service Worker, Safari introduces another major problem.</p><p>Chrome supports transferable streams in many cases. Safari’s support remains inconsistent even after introducing partial support in newer versions.</p><p>Attempting to transfer a stream in Safari can throw a DataCloneError.</p><p>The failure mode is particularly frustrating. The HTTP request succeeds, the server sends data, but nothing arrives on the receiving side.</p><p>The reliable cross browser solution is to avoid transferring the stream itself. Instead, transfer chunks and reconstruct the stream manually.</p><pre>// Sender side<br>async function forwardStream(responseBody) {<br>  const reader = responseBody.getReader();<br><br>  while (true) {<br>      const { done, value } = await reader.read();<br>  <br>      if (done) {<br>          self.postMessage({ type: &quot;STREAM_END&quot; });<br>          break;<br>      }<br><br>      self.postMessage(<br>          { type: &quot;STREAM_CHUNK&quot;, buffer: value.buffer },<br>          [value.buffer]<br>      );<br>  }<br>}</pre><pre>// Receiver side<br>function reconstructStream(messageSource) {<br>  let controller;<br><br>const stream = new ReadableStream({<br>    start(c) {<br>      controller = c;<br>    }<br>  });<br><br>messageSource.onmessage = ({ data }) =&gt; {<br>    if (data.type === &quot;STREAM_CHUNK&quot;) {<br>      controller.enqueue(new Uint8Array(data.buffer));<br>    }<br><br>    if (data.type === &quot;STREAM_END&quot;) {<br>      controller.close();<br>    }<br>  };<br><br>return stream;<br>}</pre><p>Passing [value.buffer] as the second argument to postMessage transfers ownership of the memory instead of copying it. This keeps the solution efficient even for high frequency streams and works reliably across modern browsers.</p><h3>Upgrading Axios Brings Its Own Problems</h3><p>If you upgrade from Axios 0.x to Axios 1.x to get fetch adapter support, there are a few behavioral changes worth knowing.</p><h4>AxiosError.toJSON() strips response data</h4><p>Axios 1.x includes a toJSON() implementation on the error prototype. If an Axios error crosses a serialization boundary such as Redux persistence, structured logging, or postMessage, nested fields like error.response.data may disappear unexpectedly.</p><p>The safest approach is to construct serializable error objects explicitly.</p><pre>const serializableError = {<br>  message: error.message,<br>  status: error.response?.status,<br>  data: error.response?.data,<br>  code: error.code<br>};</pre><h4>CancelToken is deprecated</h4><p>CancelToken is deprecated in Axios 1.x. Streaming cleanup logic should migrate to the native AbortController API instead.</p><h3>Four Silent SSE Parsing Problems</h3><p>Before deploying, validate your implementation against these realities of TCP streaming.</p><h4>SSE chunks do not align with events</h4><p>A single reader.read() may contain half an event, multiple events, or because TCP chunking is arbitrary. Furthermore, a chunk might split a multi-byte Unicode character directly down the middle. If you convert the raw Uint8Array to a string prematurely, you will corrupt that character data.</p><p>Always pipe the stream through the browser’s native TextDecoderStream first. Then, buffer the decoded text and split by \n\n(or \r\n\r\n, which the spec also allows). Never assume one chunk equals one complete message.</p><h4>Ignore keep alive pings</h4><p>Lines beginning with : are SSE comments used as keep alive signals. They prevent proxies and load balancers from closing idle connections.</p><p>These are not malformed messages and should be ignored silently.</p><h4>Refresh tokens before opening the stream</h4><p>Recovering from an access token expiring mid stream is far more complicated than refreshing beforehand.</p><p>Validate or refresh tokens proactively before starting the connection whenever possible.</p><h4>Cleanup is mandatory</h4><p>Browsers enforce strict limits on concurrent HTTP connections per domain, commonly around six connections. If a user navigates away and you do not cancel the active stream with AbortController, that connection remains open. Repeat this a few times and the browser may stop allowing new requests entirely.</p><p><em>Note: Upgrading your infrastructure to HTTP/2 introduces request multiplexing, which solves this 6-connection bottleneck natively</em></p><p>In React, wire controller.abort() into the useEffect cleanup function.</p><h3>The Short Version</h3><ul><li>EventSource does not support arbitrary auth headers. Use fetch with ReadableStream</li><li>Browser side Axios streaming requires adapter: &quot;fetch&quot;</li><li>Axios 1.x changes error serialization behavior, so map errors manually</li><li>Safari still struggles with transferring streams across worker boundaries</li><li>Use a chunk and reconstruct pattern with ArrayBuffer</li><li>Buffer SSE data and split by \n\n or \r\n\r\n</li><li>Always clean up streams with AbortController</li><li>HTTP/2 multiplexing fixes the 6-connection limit natively</li></ul><p>None of these problems show up in the introductory tutorials.</p><p>Most of them appear only after deployment.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=717f72f512dc" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[From Chains to Agents: When Your AI Feature Needs to Think, Not Just Execute]]></title>
            <link>https://medium.com/@ravindifernando3/from-chains-to-agents-when-your-ai-feature-needs-to-think-not-just-execute-b16c631d559b?source=rss-b63e5c3581dd------2</link>
            <guid isPermaLink="false">https://medium.com/p/b16c631d559b</guid>
            <category><![CDATA[langchain]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[large-language-models]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[ai-engineering]]></category>
            <dc:creator><![CDATA[Ravindifernando]]></dc:creator>
            <pubDate>Tue, 05 May 2026 14:36:59 GMT</pubDate>
            <atom:updated>2026-05-05T14:36:59.088Z</atom:updated>
            <content:encoded><![CDATA[<p>There is a moment in every AI feature’s life where you realise the chain is lying to you.</p><p>Everything looks fine in development. The inputs go in, the outputs come out, and the demo works beautifully. Then a user asks something slightly outside the expected pattern and the system quietly falls apart. It does not fail with an error. It fails with a confident, well-formatted wrong answer that sounds exactly right.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*E8aofsfwRlUn9wawotix-Q.png" /></figure><p>That is the moment you realise a chain, no matter how many branches you add to it, was never the right tool for the job. This is about that transition: why chains fail in production, and how moving to an agentic architecture fundamentally changes the way your AI thinks.</p><h4>What a Chain Actually Is</h4><p>A chain in LangChain is exactly what it sounds like: a predetermined sequence of steps defined at design time. Input goes in at one end, output comes out at the other.</p><pre>chain = prompt | llm | output_parser<br>result = chain.invoke({&quot;query&quot;: &quot;your input here&quot;})</pre><p>For simple, well-defined tasks this works well. The behaviour is predictable, execution is fast, and debugging is straightforward. If you know exactly what the user will ask and exactly what steps are needed to answer it, a chain is the right choice. The problem is that most real-world tasks are not that simple.</p><h4>Where Chains Break Down</h4><p>The fundamental limitation of a chain is that it cannot adapt. The chain executes its predefined steps regardless of what the model finds along the way. This manifests in three specific ways.</p><ul><li><strong>The context gap:</strong> A chain cannot say “I need more information before I can answer this”. It either has what it needs baked into the prompt, or it does not. The typical workaround is to stuff the prompt with just-in-case context upfront, which dilutes the model’s focus and burns tokens on information that may not be relevant to this particular query.</li><li><strong>Uncertainty failure:</strong> When a chain is unsure, it has no recovery mechanism. It cannot pause, recognise its own ignorance, and go resolve it. It either hallucinates an answer or produces something generic.</li><li><strong>Compounded complexity:</strong> You can add conditional branches and retry loops, but at a certain point you are not building a chain anymore. You are building a fragile, hardcoded approximation of an agent using chain primitives. The code becomes increasingly difficult to maintain, and it still fails on the edge cases you did not anticipate.</li></ul><h4>What an Agent Does Differently</h4><p>An agent built on the ReAct (Reasoning and Acting) pattern approaches a task completely differently. Rather than following a sequence, it reasons about what to do next, acts on that reasoning, observes the result, and repeats until it has enough evidence to produce a final answer.</p><p>The reasoning loop looks like this:</p><ol><li><strong>Think:</strong> What do I know? What do I need to find out?</li><li><strong>Act:</strong> Invoke the most relevant tool (Search, Database, Calculator).</li><li><strong>Observe:</strong> What did the tool return? How does this change my plan?</li><li><strong>Repeat:</strong> Iterate until the answer is grounded in facts.</li></ol><p>The execution path emerges at runtime. Because the agent reasons about the input rather than following a template, it can handle queries you never specifically planned for.</p><h4>Your Role Shifts: From Orchestrator to Toolsmith</h4><p>With a chain, your job is to orchestrate: to design the sequence and control the flow. With an agent, your job is to build good tools and get out of the way.</p><ul><li><strong>Tool descriptions are code:</strong> The agent chooses a tool based on its docstring. A vague description produces poor tool selection. Specificity is functional; if you tell the agent exactly when to use a tool and what it returns, it will use it correctly. Treat tool descriptions with the same care you give system prompts.</li><li><strong>Agentic RAG is multi-hop:</strong> In a chain, retrieval happens once, upfront. In an agent, retrieval happens on demand. An agent can search for one piece of information, analyse what it finds, and then issue a second targeted search based on that analysis. The result is more relevant context, lower token usage, and better grounded responses.</li></ul><pre>from langchain.tools import tool<br><br>@tool<br>def search_documentation(query: str) -&gt; str:<br>    &quot;&quot;&quot;<br>    Retrieves technical documentation relevant to the given query.<br>    Use this when you need accurate, specific information such as API syntax<br>    or configuration options. Do not use for general knowledge questions.<br>    Returns the most semantically relevant documentation chunks.<br>    &quot;&quot;&quot;<br>    return vector_store.similarity_search(query, k=3)</pre><h4>The Cost of Autonomy</h4><p>Moving to an agent is not a free upgrade. It comes with real engineering tradeoffs worth being honest about before you commit.</p><ol><li><strong>Latency:</strong> The “Think-Act-Observe” loop takes time. Each tool invocation is an additional LLM call or retrieval operation. Managing this requires aggressive caching, parallelising independent tool calls where possible, and being deliberate about how many tools the agent has access to.</li><li><strong>Observability:</strong> A chain has a fixed execution path you can trace in logs. An agent’s path is dynamic and different on every run. Tracing tools like LangSmith become mandatory to see the agent’s internal reasoning and understand why it made a specific choice.</li><li><strong>Non-Determinism:</strong> Agents can occasionally get stuck in reasoning loops, choose the wrong tool, or over-invoke tools. Maximum iteration limits and guardrails are not optional. They are essential safety nets for production deployments.</li></ol><h3>Conclusion: When to Stay with a Chain</h3><p>Agents are not always the answer. Chains remain the right choice for tasks where the steps are known upfront: classification, summarisation, translation, or simple extraction. The overhead of the reasoning loop adds latency and cost without adding capability when the sequence of steps is not going to change.</p><blockquote><strong><em>The Heuristic:</em></strong><em> If you can write down the exact steps the system needs to take before you see the input, use a </em><strong><em>Chain</em></strong><em>. If the right steps depend on what the system finds along the way, use an </em><strong><em>Agent</em></strong><em>.</em></blockquote><p>The clearest signal is when your chain starts to feel like a workaround. When you are adding conditional branches and retry loops to handle edge cases that keep multiplying, stop telling the AI how to execute and start asking it to reason. Once you have built a feature that genuinely thinks rather than just executes, going back to a chain feels like what it always was: a workaround for a problem that needed a different solution entirely.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b16c631d559b" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Swap Models, Not Codebases: Building Model-Agnostic AI Agents with LangChain]]></title>
            <link>https://medium.com/@ravindifernando3/building-model-agnostic-ai-agents-with-langchain-stop-locking-yourself-in-382cdc506d30?source=rss-b63e5c3581dd------2</link>
            <guid isPermaLink="false">https://medium.com/p/382cdc506d30</guid>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[langchain-agents]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[model-agnostic]]></category>
            <dc:creator><![CDATA[Ravindifernando]]></dc:creator>
            <pubDate>Tue, 05 May 2026 09:06:59 GMT</pubDate>
            <atom:updated>2026-05-05T12:55:59.494Z</atom:updated>
            <content:encoded><![CDATA[<p>The AI landscape moves fast. Models that are state-of-the-art today get replaced in months. New providers emerge, pricing changes, and models get deprecated without warning. If you are building agents with LangChain and your system is tightly coupled to one model, every change becomes a refactor instead of a configuration update. Model-agnostic design is not a nice-to-have. It is something you will wish you had done from the start the first time you need to swap a model.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*VZiWcgbSy-aix-ouMIidBw.png" /></figure><p>This blog covers what model-agnostic agent design looks like in practice, what breaks when you are not doing it, and how to structure your agents so that switching models is a configuration change rather than a refactoring exercise.</p><h3>The Problem with Tight Coupling</h3><p>When you first start building with LangChain, it is tempting to wire everything together quickly and get something working. Here is a typical starting point that most developers write:</p><pre>from langchain_openai import AzureChatOpenAI<br>from langchain.agents import create_openai_tools_agent<br><br>llm = AzureChatOpenAI(<br>    azure_deployment=&quot;gpt-4o&quot;,<br>    azure_endpoint=&quot;https://your-resource.openai.azure.com/&quot;,<br>    api_version=&quot;2024-02-15-preview&quot;,<br>    temperature=0<br>)<br><br>agent = create_openai_tools_agent(llm, tools, prompt)</pre><p>This works fine until you need to switch providers, upgrade to a newer model, use different models for different parts of your application, run tests against a cheaper faster model, or respond to a model deprecation notice.</p><p>At that point, the model is not just a configuration value. It is baked into your imports, your agent construction, and potentially your prompt design. Every change touches more of the codebase than it should.</p><h3>What Actually Breaks During Upgrades</h3><p>LangChain has evolved rapidly alongside the models it supports, and this means that abstractions which worked for one model version do not always carry forward cleanly to the next.</p><p>Some common things that break during model upgrades:</p><h4><strong>Import paths:</strong></h4><p>LangChain has reorganised its package structure multiple times. An import that worked in one version, such as importing a model class from langchain.chat_models, may have moved to langchain_openai or a provider-specific package in a newer version. These changes produce deprecation warnings that eventually become hard errors, and when they coincide with a model upgrade, the resulting failures are confusing because two things changed at once. You spend time debugging the wrong problem.</p><h4><strong>Agent constructors become model-specific liabilities:</strong></h4><p>Functions like create_openai_tools_agent are model-specific. They make assumptions about how tool calling works that are baked into OpenAI’s API conventions. Newer models may handle tool calling differently, requiring a different agent constructor or a different way of binding tools to the model.</p><h4><strong>The ecosystem itself moves:</strong></h4><p>With LangChain 1.0 released in October 2025, create_react_agent from langgraph.prebuilt was deprecated in favour of create_agent from langchain.agents. Most tutorials online still use the old import. Following them now means starting with already-deprecated patterns.</p><h3><strong>Designing for Model Agnosticism</strong></h3><p>The goal of model-agnostic design is simple. Your agent logic should not care which LLM it is talking to. Here is how to achieve that in practice.</p><h4><strong>1. Externalise model configuration</strong></h4><p>This one sounds obvious but is the most commonly skipped. Model names, API versions, endpoints, and even temperature values get hardcoded during development and then forgotten. When you later need to swap models, you have to hunt them down across the codebase. When you later upgrade models, these hardcoded values can silently break things in ways that are not immediately obvious.</p><p>A real example: code that ran fine on GPT-4o will fail on GPT-5. If you are passing max_tokens , GPT-5 replaced it with max_completion_tokens and rejects the old parameter outright with an unsupported parameter error. Upgrade to GPT-5.1-chat for its reasoning capabilities and temperature=0 , something commonly set throughout agent code is no longer supported and will cause an error. Neither of these are edge cases. They are the kind of thing you discover at the worst possible moment: when you are trying to cut costs, respond to a deprecation, or take advantage of a significantly better model.</p><p>Pulling all configuration into environment variables does not eliminate these migration costs, but it does mean they are in one place rather than scattered everywhere.</p><pre>import os<br>from langchain_openai import AzureChatOpenAI<br><br>def create_llm():<br>    model_name = os.getenv(&quot;AZURE_OPENAI_DEPLOYMENT&quot;)<br>    # Instead of hardcoding &quot;gpt-5.1&quot;, use a capability flag<br>    supports_temp = os.getenv(&quot;MODEL_SUPPORTS_TEMPERATURE&quot;, &quot;true&quot;).lower() == &quot;true&quot;<br>    <br>    llm_params = {<br>        &quot;azure_deployment&quot;: model_name,<br>        &quot;azure_endpoint&quot;: os.getenv(&quot;AZURE_OPENAI_ENDPOINT&quot;),<br>        &quot;api_version&quot;: os.getenv(&quot;AZURE_OPENAI_API_VERSION&quot;),<br>    }<br>    <br>    if supports_temp:<br>        llm_params[&quot;temperature&quot;] = 0<br>        <br>    return AzureChatOpenAI(**llm_params)</pre><h4><strong>2. Type against the base interface, not the implementation</strong></h4><p>LangChain provides a base interface, BaseChatModel, that all chat model implementations conform to. If you type your agent functions against a specific model class like AzureChatOpenAI, you have created a hidden coupling. The function now only works with that provider. Type against BaseChatModel<em> </em>instead and the function works with any LangChain-compatible model.</p><pre>from langchain_core.language_models import BaseChatModel<br><br>def build_agent(llm: BaseChatModel, tools: list):<br>    return create_agent(llm, tools)</pre><p>This is a small discipline that pays dividends. When you later want to test with a local model via Ollama, or swap to Anthropic, or run a cheaper model for certain tasks, no function signatures need to change.</p><h4><strong>3. Use the current model-neutral constructor</strong></h4><p>This is where many developers get caught out when upgrading models or switching providers.</p><p>Some agent constructors are tightly coupled to a specific provider’s tool calling conventions. create_openai_tools_agent, for example, makes assumptions about how tools are described and how the model signals a tool call that are baked into OpenAI&#39;s API. When you try to switch providers, or when a model update changes how tool calling works, these assumptions can stop holding, sometimes with clear errors, sometimes with silent failures where the agent stops using tools correctly without throwing any exception. The silent kind is the hardest to debug.</p><p>A simple rule of thumb: if a constructor name contains a provider name, it is a model-specific implementation. Think carefully before committing to it.</p><p>create_agent from langchain.agents is the current idiomatic choice. Introduced in LangChain 1.0, it is built on LangGraph under the hood, provider-agnostic by design, and supports model identifier strings that make switching providers straightforward:</p><pre>from langchain.agents import create_agent<br><br>agent = create_agent(&quot;openai:gpt-4o&quot;, tools=tools)<br>agent = create_agent(&quot;anthropic:claude-3-5-sonnet&quot;, tools=tools)<br>agent = create_agent(&quot;google_genai:gemini-2.0-flash&quot;, tools=tools)</pre><p>It delegates tool calling mechanics to the model’s own implementation via LangChain’s abstraction layer rather than hardcoding provider assumptions. When the model changes, the model class handles the translation. Your agent constructor does not need to change. It is a small decision that has an outsized impact on how much work you will need to do the next time a model changes.</p><h4><strong>4. Centralize the LLM behind a factory function</strong></h4><p>Rather than instantiating the LLM inline wherever you need it, use a factory function that returns the configured model. This gives you a single place to change when you need to swap models, and makes it easy to return different models for different purposes, such as a fast cheap model for low-stakes tasks and a more capable model for complex reasoning.</p><p>In LangChain 1.0, you no longer need to import provider-specific classes like AzureChatOpenAI to do this. Instead, use the built-in init_chat_model utility. It allows you to switch between providers using simple string identifiers (e.g., openai:gpt-4o or anthropic:claude-3-5-sonnet) without changing your imports.</p><pre>import os<br>from langchain.chat_models import init_chat_model<br>from langchain_core.language_models import BaseChatModel<br><br>def get_llm(purpose: str = &quot;default&quot;) -&gt; BaseChatModel:<br>    model_id = os.getenv(&quot;FAST_MODEL&quot;) if purpose == &quot;summarisation&quot; else os.getenv(&quot;PRIMARY_MODEL&quot;)<br>    <br>    # Note: configurable_fields=&quot;any&quot; is convenient for development but allows <br>    # runtime callers to alter sensitive fields like api_key. In production, <br>    # enumerate only the fields you want to expose explicitly: <br>    # e.g., configurable_fields=(&quot;model&quot;, &quot;temperature&quot;, &quot;max_tokens&quot;)<br>    return init_chat_model(model_id, configurable_fields=&quot;any&quot;)</pre><p>This pattern also makes cost optimisation much easier. Once you have a factory function routing calls to different models by purpose, experimenting with different models per task becomes a configuration exercise rather than a refactoring one.</p><h4><strong>5. Use bind_tools instead of constructor-level tool binding</strong></h4><p>bind_tools is part of the BaseChatModel interface and is implemented consistently across providers. When you bind tools this way, the model class handles the provider-specific details of how tools are described and invoked. Your agent logic just works with the bound model regardless of which provider is underneath.</p><pre>llm_with_tools = llm.bind_tools(tools)</pre><p>This is especially important as tool calling conventions continue to evolve across providers. Keeping that translation logic inside the model class rather than your agent means future provider updates are handled transparently.</p><h4><strong>6. Isolate prompt differences</strong></h4><p>This is the one area where full model-agnosticism is genuinely difficult. A system prompt carefully tuned for GPT-5 may produce noticeably worse results with Claude or Gemini. Different models respond differently to instruction styles, formatting preferences, and few-shot examples.</p><p>However, you can minimize structural friction by using <strong>LangChain Standard Content Blocks</strong> (introduced in 1.0). Previously, passing images or tool results required specific dictionaries for each provider. Standard Content Blocks normalize how text, images, and tool responses are structured before they reach the model.</p><pre>from langchain_core.messages import HumanMessage<br><br># Standard Content Blocks handle the heavy lifting of <br># translating this structure for OpenAI, Anthropic, or Gemini.<br>message = HumanMessage(<br>    content=[<br>        {&quot;type&quot;: &quot;text&quot;, &quot;text&quot;: &quot;What is in this image?&quot;},<br>        {&quot;type&quot;: &quot;image_url&quot;, &quot;image_url&quot;: {&quot;url&quot;: &quot;https://example.com/image.png&quot;}},<br>    ]<br>)</pre><p>The key is to contain the remaining “instruction” logic. Keep your prompts in a dedicated module and select them based on the model identifier. This way, model-specific nuances are managed in one place, not scattered across your agent’s logic.</p><pre>def get_system_prompt(model_id: str) -&gt; str:<br>    if &quot;claude&quot; in model_id.lower():<br>        return CLAUDE_SYSTEM_PROMPT  # Tailored for XML-style instructions<br>    if &quot;gemini&quot; in model_id.lower():<br>        return GEMINI_SYSTEM_PROMPT  # Tailored for long-context nuances<br>    return DEFAULT_SYSTEM_PROMPT</pre><h4><strong>7. Pin your package versions and upgrade deliberately</strong></h4><p>LangChain moves fast. An unpinned dependency can silently pull in a version that renames imports, deprecates constructors, or changes behaviour in subtle ways. Pin your versions explicitly and upgrade as a deliberate decision with time to test, not as an incidental side effect of an unrelated dependency update.</p><pre>langchain==1.x.x<br>langchain-core==1.x.x<br>langchain-openai==0.x.x<br>langgraph==1.x.x</pre><h4><strong>8. Test against more than one model</strong></h4><p>If model-agnosticism matters to you, prove it. Add a test that runs your agent against at least two providers or model versions. This does not have to be comprehensive, even a simple smoke test that confirms the agent invokes correctly and uses tools as expected is enough to catch most coupling issues before they become production problems. It also makes model migrations a routine task rather than a risk.</p><h3>When You Still Need Model-Specific Code</h3><p>Model-agnostic design does not mean pretending all models are identical. They are not. Some things are legitimately model-specific.</p><p>Tool calling support varies significantly across providers, and some models do not support it at all. Context window sizes differ, affecting memory and summarisation strategies. Output format reliability is inconsistent, with some models following structured output instructions more faithfully than others.</p><p>The key is to <strong>isolate these differences behind your configuration layer</strong> rather than letting them spread throughout the codebase. Your factory function from Point 4 is already the right place for this. Use it to route to a model with a larger context window when needed, or to skip tool binding for models that do not support it.</p><p>Keeping that logic centralized in your factory ensures your agent code stays clean, predictable, and most importantly, easy to debug when a model upgrade changes its underlying capabilities.</p><h3>The Bottom Line</h3><p>The LLM landscape will keep changing. Models will be deprecated, better ones will arrive, and the right choice today may not be the right choice in six months. Building model-agnostic agents is not extra work. It is the work that saves you from a painful migration later.</p><p>Follow these principles from the start and swapping models becomes a five-minute task, not a two-day refactor.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=382cdc506d30" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>