Design Principles Behind the Agents SDK
The Agents SDK is designed to provide a flexible, scalable, and efficient framework for building, testing, and deploying LLM agents. This article discusses the key design principles and goals that guided the development of the SDK.
High-Level Goals
- Speed of Development — build agents faster with tools and abstractions that simplify the development process.
- Local Debugging — debug agents in a local environment, reducing the need for extensive logging in production code.
- External Developer Support — allow external developers to build agents that integrate into the Zeta Alpha platform.
- Unopinionated Interface — support various frameworks and styles.
- Automatic Dependency Injection — simplify development by automatically injecting dependencies and configurations.
- Seamless Transition to Production — the same codebase used locally can be transitioned to production, minimizing discrepancies.
Key Design Principles
1. Modularity
The SDK is modular, allowing developers to build agents using a combination of built-in and custom components:
- Interfaces — the SDK defines interfaces (
ChatAgent,StreamableChatAgent,AgentDependencyFactory) that developers implement to create custom agents and dependencies. - Dependency Injection — dependencies are automatically injected into agents at runtime, so developers can focus on core logic. This also facilitates testing by enabling easy swapping of dependencies.
2. Flexibility
The SDK provides a flexible interface that allows developers to build agents in any framework or style:
- Unopinionated Interface — developers can use any framework or coding style they prefer.
- Framework Support — built-in support for popular frameworks like LangChain makes it easy to integrate existing solutions.
3. Reusability
The SDK promotes code reusability across environments:
- Configuration System — agents can be configured at runtime through a pluggable configuration system, allowing the same agent logic with different configurations.
- Dependency Injection — automatic DI allows reusing agents and dependencies in new agents, reducing duplication.
4. Ease of Debugging and Evaluation
Debugging and evaluation are first-class concerns:
- Local Debugging UI — a local debugging UI allows developers to interact with agents, override configurations, and see real-time changes.
- RAGElo Integration — the SDK integrates with RAGElo for evaluating response quality, comparing agents, and ensuring the best-performing configurations are deployed.
5. Extensibility
The SDK is designed to be extensible:
- Plugin System — new features and functionality can be added without modifying the core codebase.
- Custom Components — developers can build and integrate their own components (sources, providers, tools).
6. Production Readiness
The SDK ensures agents are production-ready:
- Zeta Alpha Enterprise Platform — agents can be deployed inside the platform, leveraging its infrastructure.
- Self-Hosted Model — agents can be deployed on the developer's own infrastructure with multiple deployment options.
- LLMOps Integration — tracing and monitoring capabilities for agents in production.
Configuration over Code
Beyond the foundational principles above, the SDK is specifically designed so that deploying for a new client should never require writing a new agent class. An engineer writes an agent_setups.json (or tenant configuration in the Platform Admin) entry: picks tool sources, configures the index description, sets citation strategy, chooses memory backend, writes a system prompt. The same Agent class, the same ChatAgentFactory, the same providers — different configuration produces a different product.
If a new deployment requires code changes to the agents SDK, the first question is: is the right abstraction missing? Sometimes it is, and a new source or config option gets added to the platform layer. More often it's a premature specialization that should be configuration.
The Four-Layer Customization Stack
The architecture enables different audiences to customize at different levels, each using a narrower, higher-level interface than the one below:
| Layer | Who | What they customize |
|---|---|---|
| Platform | Zeta Alpha engineers | Source ABCs, provider implementations, DI system |
| FDE | Forward-deployed engineers | agent_setups.json, system prompts, custom sources |
| Power User | Team leads, information architects | Agent scope, instructions, tag-note skills |
| End User | Everyone else | Conversation — natural language, memory through usage |
The top layer exposes the full power of the agentic framework — powerful, but far too general for any single enterprise's workflows and domain. Each layer below constrains and adapts it: FDEs wire it to the client's data and processes, power users shape it for their team's needs, until end users get an experience that just works — no configuration, no learning curve, just ask and go.
Additive Composition
Every capability in the SDK is a source that registers with AgentDependencyRegistry, gets auto-collected into a DependencyGroup, and flows through its provider. When search tools were added, the Agent class didn't change. When citations were added, it didn't change. When sub-agent delegation was added, it didn't change.
This is the hardest discipline to maintain and the most important one. The moment someone adds agent-level special-casing for a specific capability, the composition model breaks. New capabilities are additive by design.
Tools Absorb Complexity
Every parameter exposed to the LLM is a parameter it can misuse. The search tool hardcodes mixed retrieval and relevance ranking. The browse tool hardcodes keyword retrieval and document-level collapse. The LLM says "browse by date" and the tool translates that to the correct API call internally.
The same principle applies everywhere: WebToolsSource handles SSRF protection internally, FilterTranslator hides the boolean filter tree from the LLM, ContextWindowManager manages virtualization without the LLM knowing messages were replaced. Complexity is absorbed by tools, not delegated to the LLM.
Each Layer Trusts the Layer Below
A power user creating a tag-scoped agent doesn't need to worry about how search works — the FDE's configuration handles that. An FDE configuring filters doesn't need to worry about how FilterTranslator maps them to search queries — the platform layer handles that. An end user asking a question doesn't need to worry about any of it.