Abstract
Traditional microservice and API development often involves a top-down approach where a rigid contract is defined, and services are built to adhere to it. This creates a tight coupling between the API gateway and the service implementation, making evolution and maintenance complex. This paper presents a novel framework that inverts this paradigm. By treating autonomous "agents" as the single source of truth, API contracts become an emergent property of the system's components rather than a top-down constraint. We demonstrate how this agent-centric, declarative model allows for the creation of multiple, distinct API surfaces from a single codebase and enables the deployment of a fully functional web service as a trivially simple, stateless wrapper around a powerful core engine.
1. Introduction
The promise of microservice architecture is agility and decoupling. However, in practice, the management of the API gateway—the public-facing contract—often becomes a new monolithic bottleneck. Defining and maintaining the interface between the outside world and the internal services requires significant effort in documentation (e.g., OpenAPI/Swagger), authorization logic, and routing configuration. Changes to internal services frequently necessitate corresponding changes in the gateway, re-introducing a form of coupling that microservices were meant to eliminate.
This paper introduces a Dynamic Agent Workflow framework designed around a core principle: the agent is the atom of the system, containing all knowledge about itself. An "agent" in this context is a self-contained unit of logic defined declaratively in a JSON structure. It knows what it does, what inputs it requires, and, crucially, which public-facing service contracts it wishes to participate in.
We will demonstrate that this bottom-up, declarative approach leads to a system that is not only powerful and performant but also possesses a unique architectural elegance. Specifically, we will show how:
Complex business logic can be modeled as workflows of interconnected, autonomous agents.
API contracts are not explicitly defined but rather emerge from the self-declared properties of these agents.
A complete, secure, and multi-contract web service can be implemented as a "dumb," stateless wrapper with minimal code, completely decoupled from the business logic it serves.
2. Core Architecture: The Agent as the Single Source of Truth
The framework is composed of three primary components: the Agent Definition, the Core Engine, and the Service Wrapper.
2.1. The Agent Definition (
The entire logic of the system resides in a declarative JSON file. Each top-level key in the agents object is a self-contained component. The key innovation is that an agent's definition includes not just its implementation details but also its public interface declarations.
Implementation: Keys like type (proc, template, workflow), function_def, prompt, and steps define how the agent executes.
Signature: Keys like inputs, optional_inputs, and outputs define its functional signature.
Interface Contract: A key named web_services, a list of strings, declares which named API contracts the agent belongs to.
Figure 1: Agent Definition Example
"read_file": {
"type": "proc",
"help": "Reads content from a file",
"inputs": ["file_name"],
"outputs": ["file_content"],
"web_services": ["public_api", "internal_tools"],
"function_def": "def read_file(...): ..."
}
In this example, the read_file agent contains everything needed to understand, execute, and expose it. There is no external knowledge required.
2.2. The Core Engine (
The engine is a compact, high-performance interpreter for the agent definitions. It is designed as a pure Python library with no dependencies on how it is hosted. Its primary function, exec_agent, accepts an agent's definition and input parameters and returns a result and status. The engine is responsible for:
Resolving variable dependencies between workflow steps.
Executing different agent types (proc, template, workflow).
Managing state and control flow (including loops and conditionals, which are themselves implemented as agents).
Producing structured log output.
Crucially, the engine is completely ignorant of the concept of a "web service" or an "API contract." It simply executes the logic it is given.
3. Emergent API Contracts
The most powerful feature of this architecture is how the API is defined. Instead of a central routing file or a separate API specification, the contract is a dynamic query performed by the service wrapper at runtime.
When the web service is started with a specific contract name (e.g., public_api), it does not consult a central list. Instead, its behavior is governed by two simple rules applied to the agent definitions:
Discovery Rule: To list available endpoints, the service iterates through all agents and includes only those where the provided contract name exists within the agent's web_services list.
Execution Rule: Before executing a requested agent, the service validates that the provided contract name is present in that agent's web_services list. If not, it returns a 404 Not Found error, making no distinction between a disallowed agent and a non-existent one, thus preventing information leakage.
This design means the API contract is an emergent property of the system's components. It is always perfectly in sync with the implementation because the declaration of the interface is atomically linked to the implementation within the agent's definition. This eliminates a common source of bugs and maintenance overhead in traditional systems.
4. The Trivially Simple Service Wrapper
The decoupling of the core engine from any specific hosting model allows the web service wrapper (agent_service.py) to be remarkably simple. Implemented using the Flask micro-framework, its sole responsibilities are HTTP translation and contract enforcement.
4.1. Responsibilities of the Wrapper
Startup: Load the config.json and the core engine library.
Request Translation: Parse the agent name and parameters from an incoming HTTP request.
Contract Enforcement: Apply the discovery and execution rules described in Section 3.
Execution Delegation: Make a single function call to the core engine's exec_agent function, passing the agent's definition and parameters.
Response Formatting: Take the dictionary and log output returned by the engine and format them into an XML response.
4.2. Implications of Simplicity
The wrapper's triviality is a direct measure of the framework's architectural success.
Decoupling: The wrapper contains no business logic. It can be replaced with a different web framework (e.g., FastAPI) or protocol (e.g., gRPC) with minimal effort and no changes to the core engine.
Agility: A new, complex, multi-step workflow can be designed in the GUI, have its web_services tag set, and be instantly exposed as a production-ready API endpoint without a single line of code changing in the service wrapper.
Stability: The attack surface of the web layer is minimal. Its logic is simple, stateless, and easy to secure and maintain.
5. Conclusion
The Dynamic Agent Workflow framework demonstrates that by prioritizing the autonomy and self-descriptive nature of its core components, it is possible to build highly complex and powerful automation systems that remain simple to manage, extend, and deploy.
By making the agent the single source of truth for its own implementation and public interface, we have shown that API contracts can be treated as emergent, dynamic views of the system's capabilities. This fundamentally decouples the business logic from the public-facing API, allowing for unparalleled agility. The resulting architecture allows a fully-featured, multi-contract web service to be realized as a trivially simple wrapper, proving the power and elegance of an agent-centric design.
No comments:
Post a Comment