TypeScript AI Agents: Library Approach vs. Raw APIs

Posted on Oct 24 • Originally published at forgeworkflows.com

In 2026, the question is no longer whether to build AI agents. It is how. According to McKinsey's State of AI 2024 report, 72% of organizations now use AI in at least one business function, up from 50% in previous years. That adoption curve means TypeScript teams are being handed agent mandates without the runway to become ML specialists first. The tooling choice they make at the start of a project shapes everything that follows: testability, failure modes, and how long it takes to go from a working prototype to something that survives real traffic.

Two paths dominate right now. The first is calling LLM APIs directly, wiring your own orchestration, and owning every prompt template and context window decision yourself. The second is adopting a purpose-built TypeScript library that abstracts those patterns and ships with opinionated defaults for specific models. Neither is universally correct. I have built agents both ways, and the choice depends on factors most tutorials skip entirely. This article covers those factors honestly, including where each approach breaks down.

Raw API calls give you complete control. You write the system prompt, you decide how tool results get formatted, you manage conversation history yourself. For a single-purpose agent with a narrow task, this is often the right call. The surface area is small, the behavior is predictable, and there is nothing between your code and the model's response.

The problems surface when the agent needs to do more than one thing. Context management becomes a manual accounting problem. You track token counts, decide what to truncate, and write your own retry logic for rate limits. When you add a second agent that needs to hand data to the first, you invent a schema on the spot. That schema lives in a comment somewhere, or in your head.

I made this mistake building our first Autonomous SDR. We used a flat 3-agent architecture: research, scoring, and writing all reported to a single orchestrator. It worked on 5 leads. At 50, the scorer sat idle waiting on research that had nothing to do with scoring. The agents shared state through implicit conventions rather than typed contracts, so debugging a failure meant reading logs across three processes and guessing which assumption had broken. Splitting into discrete agents with explicit handoff schemas between them cut processing time and made each component independently testable. That experience is why every pipeline we build now uses typed inter-agent contracts. Implicit data passing does not hold up once volume increases.

Raw API development also means you own the testing surface entirely. There is no framework to mock. You test against live endpoints or you build your own harness. For teams moving fast, that cost is real.

A library designed specifically for agent orchestration trades flexibility for speed and correctness. The best ones ship with opinionated context management, typed tool definitions, and built-in patterns for multi-agent handoffs. For TypeScript teams, the appeal is obvious: you write interfaces and the library enforces them at the boundary between agents.

Libraries built specifically for particular LLM APIs, rather than generic wrappers, tend to handle model-specific quirks well. Prompt formatting, tool call parsing, and retry behavior are tuned for the target API rather than abstracted into a lowest-common-denominator interface. That specificity matters in production. A generic abstraction that works across five different models often works optimally for none of them.

The tradeoff is real, though. You inherit the library's opinions about how agents should communicate. If your use case does not fit those opinions, you spend time working around the framework rather than building your feature. Libraries also add a dependency you do not control. When the underlying model API changes its tool call format, you wait for the library maintainer to ship a fix rather than patching it yourself in an afternoon.

For teams without deep experience building multi-agent systems, the library path is usually faster to a working system. The scaffolding handles the parts that are easy to get subtly wrong: context window management, tool result injection, and agent state persistence. Getting those wrong with raw APIs produces bugs that are hard to reproduce and harder to explain to a stakeholder.

We cover the production failure modes in more detail in why AI coding agents break on production pipelines, which is worth reading before you commit to either approach.

Choose raw API calls when your agent does one thing, the task is well-defined, and you need to minimize dependencies. A single-purpose summarization agent or a classification step inside a larger n8n automation pipeline does not need a framework. The overhead is not justified.

Choose a purpose-built library when you are building a multi-agent system where agents hand state to each other, when your team has more TypeScript experience than LLM API experience, or when you need the system to be independently testable at each stage. The library's typed contracts do the work that would otherwise live in documentation nobody reads.

One practical signal: if you find yourself writing the same context-trimming logic in more than one place, you have already crossed the threshold where a library pays for itself. That duplication is the raw API approach telling you it has reached its natural limit for your use case.

A note on team context. Startup CTOs evaluating frameworks often underweight the maintenance cost of raw API orchestration. The initial build is fast. The third month, when the model API ships a breaking change and you have custom parsing logic in six files, is where the cost appears. Libraries centralize that risk. They do not eliminate it, but they make it someone else's first problem.

For teams building automation infrastructure on top of n8n, the library versus raw API decision also affects how cleanly your agent logic integrates with the surrounding workflow. A well-typed agent with explicit input and output schemas connects to an n8n HTTP node without ambiguity. An agent that passes state through implicit conventions requires a translation layer that becomes a maintenance burden. The how engineers actually build AI stacks post covers how this plays out in practice across different team configurations.

Define inter-agent schemas before writing any agent logic. We built the Autonomous SDR with implicit data passing and paid for it in debugging time. The schema is the contract. Write it first, in TypeScript interfaces, and let the compiler enforce it. This applies whether you use a library or raw APIs.

Do not adopt a library to avoid understanding the underlying API. The library abstracts complexity, but when something breaks in production, you need to read the raw request and response. Teams that skip learning the API surface end up helpless when the abstraction leaks. Spend a day building a minimal raw API agent before adopting any framework. You will debug faster for it.

Test each agent in isolation before testing the system. This is the architectural lesson that took us the longest to internalize. A multi-agent system that only gets tested as a whole is a system where failures are impossible to localize. Explicit handoff schemas make isolation testing possible. Without them, you are always testing everything at once, and that is not testing, it is hoping.