Getting an agent to answer was the easy part.
The architecture became difficult later. Model-specific types started crossing boundaries. Tool calls depended on one SDK. Chat state lived inside UI components. Memory, retrieval, traces, and tests all learned details about the same provider.
Nothing was obviously broken, but replacing one piece no longer meant replacing one piece.
That is the problem I have been trying to solve with AgentsKit. I did not want another framework that asked a team to move its application inside it. I wanted small parts that could enter an existing JavaScript codebase, solve one problem, and leave the rest of the architecture alone.
This decision eventually produced six public projects. They are related, but none of them requires adopting the other five.
Keep the provider at the edge
A provider SDK is useful. It just should not become the contract used by the rest of the application.
AgentsKit starts with six contracts: adapter, runtime, tool, memory, retriever, and skill. The core is about 5 KB, has no runtime dependencies, and contains the boundaries rather than every implementation.
Everything else is installed separately: provider adapters, runtimes, tools, memory, RAG, evaluation, observability, sandboxing, and UI bindings.
The practical benefit is not a longer feature list. It is being able to replace a model adapter without rewriting a tool, or replace a memory implementation without changing the runtime that uses it.
A team can start with:
npm install @agentskit/core @agentskit/runtime
Then add only the adapter and capabilities its application needs. OpenAI, Anthropic, Gemini, Ollama, or another provider remains an edge decision rather than an application-wide type system.
Keep conversation behavior out of UI components
An agent chat looks simple while it only appends text to a message.
It stops being simple when a user cancels a response, retries after an error, changes sessions, reconnects to a stream, or uses a different interface. If those behaviors live inside React components, every renderer becomes a new implementation of the conversation.
AgentsKit Chat keeps streaming, cancellation, session state, and errors in a headless interaction layer. The application still owns its components, styles, accessibility decisions, and design system.
That separation also makes the same behavior usable through React, React Native, Ink, Vue, Svelte, Solid, or Angular.
The quickest proof is a credential-free React example:
https://agentskit-chat-example.vercel.app/
Try starting and cancelling a response. The point of the demo is not the visual design; it is that the behavior does not depend on it.
Reuse an agent without renting a black box
Reusable agents often arrive in one of two forms: a code snippet with too little structure, or a hosted abstraction with too little control.
The AgentsKit Registry uses a source-copy model. Its CLI copies an agent into the application, where a developer can inspect it, change it, test it, and own the result.
npx agentskit add research
This is intentionally different from adding another opaque runtime dependency. The Registry is a starting point, not a new layer the application must trust forever.
Turn “production quality” into something a repository can check
Coding agents receive many instructions that sound useful and prove very little:
- follow best practices;
- respect the architecture;
- write production-quality code;
- run the right tests.
The problem is not that the agent refuses. The problem is that the repository has not made those statements concrete.
Agents Playbook turns engineering expectations into inspectable patterns and executable gates. A team can define package boundaries, required evidence, review rules, and checks that run without relying on a model to interpret them correctly.
The useful way to adopt it is not to copy an entire methodology. Start with one failure the team already sees—for example, a package boundary that is frequently crossed—and add one gate that makes the expectation testable.
Stop making coding agents guess where to work
Even a capable coding agent loses time when repository context is ambiguous:
- Which document is current?
- Which package owns this behavior?
- Which directories may be edited?
- Which checks are required?
- Where is the corresponding human documentation?
Doc Bridge turns repository documentation and ownership rules into a deterministic handoff:
{
"startHere": "docs/for-agents/packages/auth.md",
"editRoots": ["packages/auth"],
"checks": ["pnpm --filter @demo/auth test"],
"humanDoc": "/docs/guides/auth"
}
The same result is available through CLI, MCP, and CI. The core path does not need an LLM or an API key.
npx -y @agentskit/doc-bridge demo --text
The purpose is not to give an agent more prose. It is to remove decisions the repository already knows how to answer.
Do not answer review noise with more review noise
More agent-written code increases the amount of code a team can produce. It can also increase the amount of low-value review work.
An automated reviewer is not helpful if developers learn to ignore it.
AgentsKit Code Review runs locally or as a GitHub Action and can use an existing Codex or Claude CLI login, hosted providers, gateways, or a local Ollama model.
It generates candidate findings through separate review lenses, then verifies those findings before they reach the developer. The goal is not to maximize the number of comments. It is to make each comment more likely to deserve attention.
npx --yes github:AgentsKit-io/code-review-cli --provider codex-cli
Results can be returned as Markdown, GitHub review comments, or SARIF.
You should not need the whole ecosystem
These projects fit together, but the architecture only works if they remain useful separately.
- Use AgentsKit when provider or subsystem boundaries are becoming difficult to change.
- Use Chat when conversation behavior is becoming coupled to presentation.
- Use the Registry when source you can own is a better starting point than a hosted black box.
- Use the Playbook when engineering expectations are still too vague to verify.
- Use Doc Bridge when coding agents are guessing about ownership, documentation, or checks.
- Use Code Review when automated changes need verification without adding another provider dependency.
If none of those problems exists in a project, it does not need the corresponding tool.
That constraint matters to me. Open source is not useful merely because the source can be viewed. It becomes useful when a developer can understand the boundary, adopt the smallest relevant part, and leave without being trapped.
What would make this better
The most useful feedback is not “add more features.” It is evidence that a boundary does not compose cleanly:
- an adapter that leaks provider details;
- a renderer that cannot express a real interaction;
- a Registry agent that is difficult to own after copying;
- a Playbook rule that cannot be verified;
- a Doc Bridge handoff that still leaves an agent guessing;
- a review finding that wastes a developer's time.
Those are good issues. They can become tests, clearer contracts, examples, or focused pull requests.
If one of the problems in this article matches a system you are building, try the smallest relevant project and tell me where the boundary fails. If the approach is useful, starring that repository helps the next JavaScript developer find it—but understanding and testing it is more valuable than a number.
Top comments (0)