Enterprise architecture is evolving from service-oriented systems toward agent-driven systems, where coordination is no longer predefined but emerges from context and intent.
This article presents a practical reference architecture for building agentic systems using AWS AgentCore. Instead of focusing on concepts alone, we describe the core layers, artifacts, and lifecycle required to design, expose, and operate agent-driven capabilities at scale.
Microservices vs Agentic Approach
Traditional microservice architectures rely on explicit orchestration and human-defined contracts. Service interactions are predefined, and workflows are implemented through deterministic logic.
Agentic systems introduce a different model, the coordination is context-driven, services are consumed as on-demand capabilities rather than fixed integrations, and decision-making is delegated to agents instead of encoded in workflows. This shifts the architecture from flow-based execution to intention-driven coordination.
Consumption, Contract, and Coordination
High level axes to compare Microservice architectures and Agentic architecture can be decomposed into three dimensions: Consumption, Contract, and Coordination.
Consumption: The consumption in microservice architecture is direct as service-to-service calls or mediated via BFFs, gateways, or workflows, while in agentic approach, it is dynamic and context-driven, when agent per context decide which tool call must be called.
Contracts: The micorservices' contracts (OpenAPI, events) are prepared and completed by Human-driven alignment and are thought to be consumed by internal or some known consumers with clear needs, those contracts are designed to technically answer needs. In agentic approach the requirement is more than technical consumption but readable and semantically explainable for AI undersatanding.
Coordination: Microservices are a golden box of business logic and encoded orchestration allowing the decisions in a predefined and orchestrated way, but agents take decisions in a natural way without predefined rules or logic, the only guidlines for better decisions by agents is the context and shared context achieved during coordination loop.
Transition to Agentic Architectures
Agentic systems introduce a fundamentally different model—one where consumption and coordination are no longer predefined, but emerge from context. Instead of relying on static orchestration and human-aligned contracts and contracts, Agents operate based on Intent rather than fixed endpoints, Context rather than predefined flows, On-demand capabilities rather than fixed integrations.
Rethinking
In an agentic model, consumption becomes dynamic and context-driven, Agents do not “call a service” because it was predefined, They select capabilities at runtime, based on the current context and goal.
This eliminates the need for rigid consumption paths like fixed API chains and predefined orchestration workflows. Instead, consumption is discovered and decided in real time.
Context as the New Coordination Layer
This is where context-aware coordination replaces traditional business logic and human-driven orchestration. Rather than encoding workflows explicitly, the system maintains a rich context state, agents interpret that context, decisions emerge dynamically, and there is no central orchestrator dictating the flow. The context itself becomes the source of truth for coordination.
How Agents Discover and Coordinate
Using platforms like AWS AgentCore, agents operate through three core phases.
- Discovery
Agents identify available tools dynamically, APIs, Functions (e.g., Lambda), Data sources, External systems, etc. These are not hardwired dependencies but available capabilities in the environment.
- Coordination
Instead of predefined workflows, Agents plan actions at runtime, break down goals into steps, adapt execution paths based on feedback. Coordination becomes iterative and context-sensitive, not static.
- Communication
Agents interact with tools and systems through structured inputs/outputs, shared context updates and communication is no longer just API calls—it is part of a continuous decision loop.
Why This Matters More in Agentic Systems
In traditional systems , developers understand the API, They encode logic and parameter combinations manually. In agentic systems Agents must select and use APIs autonomously, Ambiguity becomes a real problem, Complex parameter-driven behavior is harder to reason about.
So the shift is:
Context Aware Coordination
Agents need coordinate via context that allows them to understand the overall environment in advance or at runtime, Agents read shared context, decide next actions, select tools dynamically and update context based on outcomes. How the agent achieve the context, is via agent description, system instructions but also the semantic knowledge about tools.
This creates a continuous loop as Context → Decision → Tool → Execution → Context Update
Context becomes the primary coordination mechanism, replacing static orchestration logic.
Specialized vs Intentional Apis
API design directly impacts how effectively agents can operate.
Specialized APIs concentrate logic through parameter-driven behavior
Intentional APIs expose clear, single-purpose actions
The trade-off is not about endpoint count, but about where complexity resides:
| Model |
Complexity |
| Specialized APIs |
Rules settled inside API logic, parameters or combination of parameters can lead to different behaviors, exposing those rules to LLM can lead to a lot overhead over the time but putting decision matrix in instructions that are natural language representation of responsabilities |
| Intentional APIs |
Coordination becomes tricky as the agent must understand a langer number of tools and in cases for a very concret task need to call many tools to achieve the required results. |
For agentic systems, clarity and predictability are more critical than flexibility.
In many enterprise systems, APIs are designed to be highly flexible and reusable:
A small number of endpoints
A large number of parameters and flags
Behavior that changes based on input combinations
Specialized exmaple:
POST /orders/process
{
"customer_id": "123",
"validate_only": false,
"reserve_inventory": true,
"process_payment": true,
"notify_user": false,
"mode": "EXPRESS"
}
Intentional example:
POST /orders/validate
POST /orders/reserve-inventory
POST /orders/charge-payment
POST /orders/notify-customer
Trade-offs
|
Specialized (Feature-Rich APIs) |
Intentional (Intent-Based APIs) |
| Flexibility |
High (many use cases in one endpoint) |
Moderate (composed across endpoints) |
| Complexity |
High (parameter combinations, branching logic) |
Low (single-purpose endpoints) |
| Discoverability |
Low (requires documentation and expertise) |
High (self-explanatory actions) |
| Coupling |
Tighter (clients depend on internal logic flags) |
Looser (clear contracts per action) |
| Evolution |
Risky (changes impact multiple use cases) |
Safer (add new intents incrementally) |
| Reusability |
High (generic design) |
High (through composition) |
Level of Intentional Design Approach
The comparison between specialized (feature-rich) APIs and fully intentional (fine-grained) APIs is useful, but it is incomplete when viewed through an agentic lens.
In practice, neither extreme is ideal for large-scale enterprise systems. Instead, agentic architectures benefit most from a balanced design: product-intentional APIs—an intermediate approach that aligns business meaning with executable capabilities.
Re-evaluating the Two Extremes
Best aproach is not a single bullet but that can be often a good mindset to challenge the two horizons and find a fair approach.
Specialized (Feature-Rich) APIs:
These APIs concentrate multiple behaviors into a single interface, controlled through parameters and flags.
Strengths: High flexibility and reuse Fewer endpoints to maintain Efficient for human-driven integrations
Limitations in agentic systems: Hidden complexity in parameter combinations Difficult for agents to reason about correct usage Weak semantic clarity (“what does this call actually do?”) Higher risk of misconfiguration or unintended behavior
Intentional (Fine-Grained) APIs:
These APIs expose explicit actions as separate endpoints, each representing a single operation.
Strengths: High clarity and predictability Easy for agents to discover and use Strong composability Reduced ambiguity in execution
Limitations in enterprise scale: Endpoint explosion over time Fragmented orchestration logic Harder governance across many small capabilities Increased operational overhead The Agentic Reality: Neither Extreme Scales Well Alone
Agents requirements: In agentic systems, APIs are not just consumed by developers—they are also consumed by autonomous decision-making systems.
Product-Intentional Design (The Middle Approach)
Product-intentional APIs are designed around business-level capabilities, not technical granularity or excessive parameterization and they represent a shift
“What does the system technically do?” to “What does the business intend to achieve?” What This Looks Like
So Instead of:
POST /orders/process (parameter-driven behavior)
POST /orders/validate
POST /orders/charge
They are defined intent-aligned capabilities, such as:
POST /orders/fulfill-order
POST /orders/verify-customer-eligibility
POST /orders/resolve-payment
Each endpoint:
Encapsulates a meaningful business outcome
May still coordinate multiple internal services
Avoids excessive parameter branching
Maps cleanly to agent goals
Agents operate on intent, not implementation details. Agents don’t reason about how a system is built internally—they reason about what needs to be achieved. Instead of thinking in terms of service boundaries, database operations, or orchestration steps, an agent starts from a goal (the intent) such as “fulfill an order” or “resolve a payment issue” and determines the sequence of actions required to reach that outcome. The underlying implementation—whether it involves multiple microservices, queues, or workflows—is treated as an abstraction layer that the agent does not need to understand directly.
This is a key departure from traditional software design, where developers explicitly encode the implementation path. In agentic systems, that responsibility shifts upward: the system exposes meaningful capabilities, and the agent dynamically decides how to use them based on context. As a result, the architecture becomes less about exposing technical operations and more about representing clear, business-aligned intents that can be composed and executed flexibly.
A product-intentional API:
Matches how agents decompose goals
Reduces ambiguity in tool selection
Keeps internal complexity hidden without overloading endpoints
Enables safer, more predictable orchestration
Importance of API Contracts and AI Readiness
In agentic systems, API Contracts are not just contracts—they are machine-consumable capability definitions.
Agents rely on Contracts to:
Embedding this logic in system prompts does not scale. Instead:
Each service must provide high-quality, AI-ready Contracts.
These Contracts should:
clearly define service boundaries
expose consistent input/output structures
avoid ambiguity in parameters and behavior
This enables decentralized and scalable agent coordination.
Designing Agentic approach with AgentCore
AgentCore is aws managed service and purpose build offering for agentic approach that allows to build and run agents at scale. It has many components that simplify the adoption and integration of existing apis and services.
While Agentcore provides all necessary means to accelerate the agentic design adoption, enterprises must be aware of how at long term we can maintain that agentic ecosystem. and those tradeoffs are bases on the organization structure how teams collaborate and how things evolve.
Discovering the organization structure lays on teams, product decisions, marketplaces, and ownership. Based on these findings we can define the best approach that will help governance and maintenance at long term.
💡
To earn more about Agentcore aws provides the complete guid and documentation
here
Integrating Existing Ecosystem
Companies often start by integrating existing ecosystem, and the move is mostly started by Openapi spec integration. This is where we need to refer to AI-Readiness quality of our contratcs that was introduced earlier in this article.
The specification quality traditionally was done semantically such as if all paths have a description, all have operation id, etc. For AI models this is not enough but the provided context via those semantic attributes must be qualified.
Looking at petstore swagger example this description gives no value to AI based systems and will not help them to easily use the tool clearly and avoid extra rounds at coordination layer.
{
"openapi":"3.0.4",
"info":{
"title":"Swagger Petstore - OpenAPI 3.0",
"description":"This is a sample Pet Store Server based on the OpenAPI 3.0 specification.",
"version":"1.0.27"
},
"servers":[{ "url":"/api/v3" }],
"tags":[...],
"paths":{
"/pet":....
"/pet/findByStatus":...
"/pet/findByTags":...
"/pet/{petId}":...
"/store/inventory":...
"/store/order":....
},
"components":{
"schemas":{
"Order":...
"Pet":...
}
}
}
But this can be better to give this spec a more meaningful description as
{
"openapi":"3.0.4",
"info":{
"title":"Swagger Petstore - OpenAPI 3.0",
"description":"This service manages pet entities and store order operations within the pet store domain.
It is responsible for maintaining pet data, supporting pet discovery through status and tags, and handling order creation and inventory visibility.",
"version":"1.0.27"
},
...
}
Now that the importance of semantic and context in a contract is clear, lets highlight the importance of ownership
A tool or an existing api is under team ownership that maintain that api, and logically the best owner is the team mastering those bounded contexts, ubiquitous language and the very detailed informations in that context.
Enterprise Glossary
I can not remember how many times in meeting me or someone else asked for a clarification about a single word. Lets give a simple example as "Customer Type" , does it mean the seller category for a product or its the customer asking for information about a product. Or "Contact" vs "Lead", a customer often looks for contact but the business analyst use the lead, LLM can hallucinate in a non deterministic way. does this problem is based on the miss leading attribute name or lack of well explained description?
Glossary plays a vital role in the age of AI and is a simplified way of governing and maintaining services' quality and avoid conflicts.
Agentcore Gateway
The Agentcore gateway has two initial components Gateway and Gateway Target. The Gateway Target is an api binding and must be attached to a Gateway, while the Gateway represents an available tool.
Gateway Target can be managed by the stack or project owning the specification but Gateway can not be alone proxy to a single tool, and as we discussed about "Level of Intentional Design", gateways (agent tools) must have product-based intentions and follow the instrumentation concepts such as versioning.
Agentcore Runtime
Agentcore runtime is aws offering for running agents at scale, it allows to define tools, discover , have isolated memory and sessions, user foundation models, evaluate the agent response, etc.
Runtime provided different communication interfaces as HTTP, MCP, and A2A. This allows your runtime being used across different consumer types such as your website or application, client tools such as chatgpt and in multi agent designs.
The mostly adopted framework in the community with agentcore is strands-agents but other frameworks can be executed in runtime such as LangGraph, CrewAI, and LlamaIndex.
Runtime Requirements:
When using agentcore runtime, you need to define an agent with a minimum of configuration for Model, System Instructions, Tools.
Model: you can define extra parameters side of the model id such as temperature, max tokens, topK, topP , etc (list varies based on selected model).
System instruction: A brief and contextualized prompt helping agent understand its responsibilities and the task it owns to accomplish. The system prompt must be to the point and must not propagate the tools context and is only for sake of leading agent and initiating a task context to agent.
Tools: List of tools the agent needs to accomplish its task, the tool is not agentcore gateway, or target, but the list of endpoints or operations all targets of a gateway provide. You can use the Mcp Client form official "@modelcontextprotocol/sdk" to list tools of each gateway.
Externalizing Agent configuration
With agentic approach we have an initial problem and this is the lack of deterministic behaviors, that means as engineers we iterate many times even in production to find the best balance of configurations being model config, or system instructions, or caching config.
This help to simplify rolling different iterations, apply A/B testing different versions and achieve iterative optimization without redeploying the whole agent.
Enterprise Agentic Landscape
The final approach this article recommend is to descope the internal ecosystem and provide a pragmatic way to accelerate product releases and feedback based improvements. The following diagram showcase the overall landscape.
Consumers: The consumers are the first layer of interaction with your system, they provide intentional requests based on machine or human decision loop. They often explain a requirement that is sent to agent runtime.
Runtime (Agent): The agent is a product oriented server that is designed based on tech and product staffs and brainstormed to give the most of value based on user intentions. The agent has a dedicated life cycle and follows the versioning and is considered as a first layer of interaction with enterprise ecosystem. It must consider crosscutting concerns such as evaluation metrics , A/B testing, feedback loop and versioning, etc.
MCP Kernel: The collection of gateways with well defined boundaries (NO CRUD - but intentional), the kernel must also provide some level of versioning and parameters to simplify internal teams life and product lifecycle.
Tools: Those are existing or AI compatible targets that are well thought and with refined context for a maximum of consumption clearance and realtime decision loop.
The Release Lifecycle
From the initial platform setup to agent configuration, the release lifecycle in an agentic architecture focuses on progressively transforming a business need into executable, AI-ready capabilities. This phase establishes the foundation for scalable and iterative evolution.
Platform Team: The platform team provides the foundational capabilities that enable and accelerate the release process. They act as facilitators of the agentic kernel, runtime constructs, gateways, and configuration workflows.
Their responsibilities include:
Maintaining the agent runtime environment
Providing gateway infrastructure to expose services as tools
Enabling configuration management and versioning mechanisms
Supporting evaluation pipelines and registries (agents, tools, gateways)
This layer ensures consistency, scalability, and standardization across the ecosystem.
Product Team: The product team initiates the lifecycle by identifying and refining a consumer need. They collaborate closely with technical teams to explore what is feasible within the existing ecosystem.
At this stage:
The problem is framed in terms of intent and expected outcomes
Existing agents and capabilities are evaluated
A decision is made whether:
This phase defines the functional direction without locking into implementation details.
Tech Teams: The tech teams translate product intent into executable architecture, aligning requirements with available capabilities across the enterprise ecosystem.
They begin by exploring existing tools and services through agent, gateway, and service registries to determine reuse opportunities and dependencies. The proposed solution is validated against the current ecosystem before moving forward.
At this stage, API Contracts become a central artifact.
Existing Contracts are evaluated for AI-readiness using LLM-based semantic analysis and specification synthesis tools
These evaluations assess clarity of intent, parameter ambiguity, and usability as agent-consumable capabilities
If gaps are identified, Contract are refined or newly created following an intention-based, agent-friendly design approach
Specification ownership remains with the respective service teams, ensuring long-term quality and consistency
Once validated, Contract are used to define gateway targets:
APIs are attached to gateways, exposing underlying services as structured, discoverable tools
Gateway configurations are managed as Infrastructure as Code (IaC) and versioned alongside API repositories
This ensures traceability between service evolution and exposed capabilities
With the tool layer established, the team proceeds to agent development through versioned configurations:
Finally, agents are evaluated through iterative testing pipelines:
This iterative evaluation ensures that agents are not only functional, but reliable, predictable, and aligned with business intent.
Key Insight
In an agentic release lifecycle, the path from idea to implementation is driven by the quality of API Contracts, the clarity of exposed capabilities, and the continuous evaluation of agent behavior.
This foundation enables systems to evolve iteratively while remaining robust, scalable, and aligned with enterprise constraints.
