Forem: Olivier Lemaitre

Draw Full Diagrams from Simple Models with Custom Agents in Kiro

Olivier Lemaitre — Mon, 06 Apr 2026 16:03:59 +0000

Imagine that you want to document an AWS account, a network topology, an application, etc, with a diagram. That would be a good idea, because it's certainly the best way to do it.

However this can take time, especially if you have many resources to explore.

Recently wondered how I could minimize this effort using my Agentic IDE.

I ended drawing a simple model of what I wanted and then, with one command, asked my IDE to draw a new one with real data.

In brief, I'm now able to do this kind of thing:

/draw-from-model vpc-and-subnets.model.drawio

Which I can represent this way:

I wanted to share this, and explain the phases that helped me to get there:

Phase 1 - Extract data, create Model Diagram, mix both
Phase 2 - Create Diagram Model, deduct data to extract, mix both
Phase 3 - Do it with a custom agent: /draw-from-model
Phase 4 - Draw new diagrams from any model

N.B.: I chose the AWS Kiro IDE, but you can apply this with another Agentic IDE as long as you can extend it with custom agents.

Phase 1 - Extract data, create Model Diagram, mix both

I started with a simple approach, trying to extract the data I wanted first. Before creating a diagram model.

1.1 - Extract Data from the AWS Account

So, I started to ask for a script that extracts data from my AWS account. I spotted VPC and Subnets, which are basic and easy to understand.

A VPC (Virtual Private Cloud) is an isolated network that covers multiple availability zones (a data center to make things simple) in an AWS region.

VPCs contain Subnets, which are subnetworks associated with an availability zone.

So here is the prompt I used for that:

> create a python script to extract vpc and subnets data from eu-west-1 region

Then I executed the script

$ python3 vpc_subnets_eu_west_1.py

And I got a file named vpc_subnets_eu_west_1.json

1.2 - Draw a model with drawio in your IDE

Then I drew a model of what I wanted with an account, a VPC and multiple subnets (public and private)

1.3 - Cross Data and Diagram Model

Then I asked Kiro to cross the extracted data and the diagram model

cross #diagram.model.drawio + #vpc_subnets_eu_west_1.json and create a new diagram

And I got a new diagram...

Not bad at all...I verified on my account and that was exact!

Phase 2: Create Diagram Model, deduct data to extract, mix both

Then I thought, maybe we can ask the LLM directly to deduct the data I need from the diagram model. That's what I tried.

2.1 Use the model diagram to deduct data to extract

Actually, the data that I want to extract are in the model. So, why should I specify the data in the prompt forehand and take the risk of forgetting something?

So, I started to ask:

from #diagram.model.drawio generate a python script to extract necessary data from aws account if I want to create an equivalent diagram

That created another script to extract the data (the same kind of script I created earlier)

$> python3 extract_vpc_diagram_data.py

The result is a file name diagram_data.json

2.2 Crossing data and diagram model

Then I crossed the data and diagram again.

cross #diagram.model.drawio + #diagram_data.json and create a new diagram

And obtained this diagram:

The layout is a bit different, but the content is similar.

Phase 3 - Do it with a custom agent: /draw-from-model

With Kiro, you can create what we call "custom agents", they are files where you can write a workflow of actions (like a shell script in natural language).

Then this helper can be found in the Kiro Chat interface, thanks to the dash bar ('/').

For example you can create a /draw-from-model custom agent, taking a model as a parameter, that executes exactly what I did with multiple prompts previously.

You can write it manually or generate one with this kiro helper /custom-agent-creator

So I tried it:

/custom-agent-creator using this context create a custom agent does this steps (extract data from diagram, draw new diagram). Keep custom agent as simple as possible.

Here is the result, which actually contains the previous prompt I used, more or less.

And now I can use it in my IDE chat box:

/draw-from-model diagram.model.drawio

The result is similar to what I got previously:

Phase 4 - Draw new diagrams from any model

Then I thought, let's try with a brand new model, with different resources.

So, I redrew my diagram model asking for API gateways and their integrations.

And I used my custom agent:

/draw-from-model diagram.model.drawio

Here is the result:

Not bad at all.

Conclusion

LLM are obviously good at crossing data, in this case I wanted to cross network and subnets data from my AWS account with a network and subnets diagram model.

Then I thought we could extract what I wanted directly from the diagram. It's like I was using my diagram as a query language :)

Then I took advantage of custom agents to create a helper that I can use from my IDE chat, with any model.

It's a very nice and promising discovery. It might need some more tests and improvements, but I think I will use it quite often in the future!

Will I lose my job because of GenAI?

Olivier Lemaitre — Tue, 31 Mar 2026 05:32:32 +0000

Will I lose my job soon? Will my job be replaced by GenAI Agents?

Many developers (and other professionals) might have that question in mind today.

To be honest, I don't have the answer to these questions, but that sounds really weird to me when I hear or read that software developers have no future.

I believe that depends on how we define the developer job.

Of course, if you are the kind of developer who expects to be given the input and the output of a function and only writes the code inside it...you are dead!

But, I hope a large majority of developers do more than that today!!!

If not, they will have to augment their skills. And the good news is that GenAI will help them learn faster!

Then, maybe, we should stop talking about developers, but software architects or software engineers (who should have coding skills of course - but not only).

This diagram illustrates this evolution, where developers become software architects / engineers, building more complex applications.

Now let's say that a job can be threatened when someone has the choice between asking to a human (slow and expensive) compared to asking to an AI Agent (cheap and fast).

Therefore, can we replace a software engineers with GenAI Agents?

Again I don't have a definitive answer, but my gut feeling is that it will be difficult for COMPLEX applications, which is more and more the norm in many companies.

Maybe, I'll be worried the day when all companies around the world will have all the same infrastructure, all the same programming language, all the same database engine, all the same application framework, ...

But this is not the trend I see.

Applications require more and more sophistication: Event Driven Architecture, Distributed Databases, Micro-Services, Data Lakes, etc...

Why?

I think because the purpose of a company is to create value (i.e. improve their customer's life) and differentiate from their competitors.

And the more you want to create value with software, the more you need it to be sophisticated behind the scenes.

Also, building GenAI agents for our customers will not simplify systems, I actually feel the opposite!

Therefore I'm quite optimistic for software engineers in the future 😊

I hope sharing this will help people 😊

From Diagram to Code with Kiro CLI & Claude Opus 4.6

Olivier Lemaitre — Tue, 10 Feb 2026 06:29:57 +0000

A chalk talk is a conference session with a lot of interactivity. The speakers ask questions to the audience, draw diagrams on a whiteboard, and the audience asks questions back to the speakers.

That's one of my preferred session types when I go to AWS re:Invent.

Here I chose one I attended in 2025 to explore a few techniques I use with GenAI and architectural diagrams.

I also took the opportunity that Claude Opus 4.6 is out and already available within Kiro CLI (an equivalent to Claude Code at AWS) to push this forward.

1. From Picture to Diagram

During a chalk talk (like that could happen in any architecture session), the AWS architecture is hand drawn.

In this particular session named "Beyond micro services: Event-driven patterns for modern applications", we designed a web site backend, and for scalability reasons we wanted to use an EDA (Event Driven Architecture) workflow to process shipment events (a parcel was shipped for example).

Here is a picture I took of the architecture during the session:

On the red path, we can see that an application calls an API gateway, then we put the ship event in an SQS queue, which is read by a Lambda function, that writes to a history DynamoDB table, and an EventBridge bus, which triggers a notification to the user via SNS.

The transformation prompt

First I started kiro-cli, uploaded my photo in the IDE and chose the Claude Opus 4.6 model...

...and asked:

Create a diagram from 20251205_085619.jpg

The result

I obtained a nice mermaid diagram in a markdown file as you can see below.

Mermaid is a diagram as code notation that allows describing diagrams with text.

However, I prefer to use Drawio because I can easily add modifications in my diagram with my mouse using Drawio Extension in Kiro-IDE (an IDE based on VSCode open source extension, maintained by AWS).

So, I asked

Create a drawio diagram from architecture-diagram.md using 2025 icons

Which gave me this result:

N.B.: I could also ask to directly generate a Drawio diagram from the picture.

2. From Picture to Diagram - Second Version

Then during the chat talk, after some discussions we made this architecture evolve.

So, I uploaded another picture and asked the same kind of questions which created another Drawio diagram of the architecture:

Create a drawio diagram from architecture-diagram-v2.md using 2025 icons

Why did we update the initial architecture?

You may ask yourself, why did we change our minds?

This is quite common in design and architecture, the first idea that comes to mind is not always the best one, even if you have a lot of people in the room😊

Simply ask Kiro why we replaced a part of the diagram

If it's not obvious (and it's not for a lot of people) you can simply ask kiro-cli.

Why Event Driven Shipping flow has a better architecture in architecture-diagram-v2.drawio than in architecture-diagram-v1.drawio?

The answer was quite impressive because that's exactly the reason why we changed our mind during the chalk talk, here is a chunk of the LLM answer:

The Lambda only writes to DynamoDB. The event propagation happens automatically through the stream and pipe.

Here's why that matters across several architectural characteristics:

1. Data Consistency (the biggest win)
- v1: If the Lambda writes to DynamoDB but the put_events call to EventBridge fails (timeout, throttle, transient error), you have data in DynamoDB but no event was published. Consumers never learn about the shipping update. The system is in an inconsistent state.
- v2: The Lambda does a single write. The DynamoDB Stream guarantees that every successful write produces a stream record. EventBridge Pipes reads that stream. There's no dual-write — the event is derived from the data, not published separately.

...

The dual-write problem

So, in brief, in the first architecture the problem is that the lambda writes in both Event Bridge Bus and DynamoDB Table.

That's a trap we can easily fall into because technically... it works.

However, as you may know, software is not 100% reliable and it can happen that you send a notification to the customer, but (due to an unexpected error) you don't write to the DynamoDB table. That means that you will have an inconsistent state in your system.

For example, your customer might receive an information and your customer support team doesn't see the same information. That will make things confusing for your users if they have to talk to each other.

That's the 'dual-write' problem.

In the picture below we have that dual-write (the lambda writes in DynamoDB and Event Bridge)

Solving dual-write problem

In the picture below we have NO dual-write (the lambda writes in the DynamoDB table only)

The solution is to write the message in one place only, not more. In this case the user will receive a notification only if each step of the process was successful.

That's why we added a DynamoDB Stream, and an EventBridge Pipe that can pull messages from the DynamoDB Stream and write to the Event Bridge Bus (EventBridge Pipes avoid maintaining a lambda for that).

N.B.: For EDA experts, later in the chalk talk we added a dead letter to store the failing messages.

From diagram to code

A technique I find very useful is to generate the CDK (Cloud Development Kit) code from my diagrams.

The generated CDK code can be executed in order to build a template that can be deployed to AWS CloudFormation (an Infrastructure as Code Engine), which atomically creates all the components on AWS. You can find more about this here

That's super powerful.

1. Create a Kiro steering file

So, First I created a steering (i.e. rule file) that I call my ProfesionnalTwin

---
inclusion: always
---
<!------------------------------------------------------------------------------------
   Add rules to this file or a short description and have Kiro refine them for you.

   Learn about inclusion modes: https://kiro.dev/docs/steering/#inclusion-modes
-------------------------------------------------------------------------------------> 
- I work with python 3.10
- I work with CDK V2
- I work in AWS eu-west-1 region

2. Generate code from the diagram

Then, I used Kiro CLI and asked:

architecture-diagram-v2.drawio generate "Event-Driven Shipping Flow" application

And after a few minutes I got that kind of code

3. Deploy the generated application

I ran a 'cdk deploy' and the deployment worked right away.

4. Generate an end-to-end test

Testing an EDA workflow is not easy, but I can rely on Kiro-CLI for that, so I asked:

Create a test that will put a message on the sqs queue and verifiy the workflow output

It generated a test suite that I could execute to verify the workflow was working:

Prevent dual-write: From Characteristics to Fitness Functions

Listing architecture characteristics

Architecture has characteristics (security, scalability, ...), so I asked what sort of the characteristics Kiro CLI could identify in this architecture

What architecture characteristics can I identify in my shipping flow architecture

Architecture characteristics I can identify:

1. Scalability / Elasticity
- All components are serverless and scale independently (SQS, Lambda, DynamoDB on-demand, EventBridge)
- No provisioned capacity or concurrency caps anywhere

2. Loose Coupling
- Components communicate through events, not direct calls
- SQS decouples the upstream order management from the shipping-update Lambda
- EventBridge bus decouples the DynamoDB state change from downstream consumers (SNS, event-handler Lambda)
- Adding new consumers requires only a new EventBridge rule — no changes to producers

...

Listing fitness functions

If you want to prevent a drift of your architecture characteristics (scalability reduction, security reduction, ...) you can use what we call "Fitness Functions".

These are static or dynamic tests that will verify the compliance of your architecture with its characteristics. That's super important if you want to make your architecture evolve while minimizing risks.

So, I asked:

What fitness functions can I create for these characteristics?

Based on the characteristics I identified, here are fitness functions you could create beyond the scalability ones you already have:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


## Loose Coupling — Static

- **EventBridge bus exists between producers and consumers** — ensures no direct Lambda-to-Lambda invocations
- **No Lambda environment variables referencing other Lambda ARNs** — proves components don't call each other directly
- **EventBridge rule count matches expected consumer count** — detects accidental tight coupling through hardcoded targets

...

Visualize your fitness functions

To better visualize what fitness functions are and where they apply in my architecture, I simply asked Kiro

Create a new Drawio diagram from architecture-diagram-v2.drawio with representation of the implemented fitness functions

The result is an updated diagram with all the fitness functions (it's focused on scalability only in this case).

For example, for the application to be scalable we shouldn't use FIFO queues (they have limited throughput compared to standard queues), and during runtime, message age should be less than 60 seconds.

Prevent dual-write problem with a fitness function

I asked an implementation of the previous scalability fitness functions, but I also wanted to focus on our dual-write problem.

This fitness function should spot this issue in the future if someone (including me) wants to make the architecture evolve and forget about this.

What fitness function can I implement to avoid dual-write implementation?

## Static — CDK Assertions

Lambda functions have at most one write permission — if a Lambda has grant_write_data to DynamoDB AND grant_put_events_to on EventBridge, that's a dual-write risk.

python
def test_no_lambda_dual_write():
    """Lambdas must write to at most one destination — use streams/pipes for fan-out."""
    template = _template()
    resources = template.find_resources("AWS::IAM::Policy")

    for logical_id, resource in resources.items():
        statements = resource["Properties"]["PolicyDocument"]["Statement"]
        write_actions = set()
        for stmt in statements:
            actions = stmt.get("Action", [])
            if isinstance(actions, str):
                actions = [actions]
            for action in actions:
                if any(w in action for w in [
                    "dynamodb:PutItem", "dynamodb:UpdateItem", "dynamodb:BatchWriteItem",
                    "events:PutEvents",
                    "sqs:SendMessage",
                    "sns:Publish",
                ]):
                    write_actions.add(action.split(":")[0])

        assert len(write_actions) <= 1, (
            f"{logical_id} has write permissions to {write_actions} "
            f"— dual-write risk. Use DynamoDB Streams + EventBridge Pipes instead."
        )

The result is a test suite containing CDK Assertions.

Actually, the test will scan my CloudFormation template and detect if the lambda is allowed to write to more than one target service.

Therefore in the future if someone updates the lambda with a new target, the test will fail when executed locally or in the CI/CD pipeline.

Continue talking to your diagram

There are multiple ways you can continue to use your diagram to extract some information or generate others.

Here are a few examples, and I don't think I'm exhaustive here:

Show Architecture Patterns

Maybe you prefer to work with EIP (Enterprise Integration Patterns), or at least identify these patterns, for a better communication or simply generalize your architecture in order to use it on another platform.

Here is an example of what you can do:

Redraw a new shipping flow with Enterprise Integration Patterns

We see for example that the shipping update lambda function is a 'Message Translator', EventBridge a 'Publish/Subscribe Channel', ...

Show Architecture Constructs

Having a monolithic piece of code to describe your architecture can have some advantages, but for reuse purposes you might want to split this into modules called CDK Constructs in the CDK vocabulary.

You can ask for some help from Kiro for this

Create a new drawio diagram from architecture-diagram-v2.drawio with well defined constructs

Then you can adjust this diagram to your needs and ask Kiro to update your CDK code from your Diagram.

Compute Architecture Cost

Another way you can use your diagram is to estimate the cost of your architecture.

In order to be accurate, I installed the AWS Pricing MCP Server

Then I asked

architecture-diagram-v2.drawio how much would this shipping flow cost with 10000 events per hour

And I got a report with the cost breakdown

Conclusion

Chalk Talks are really interesting and fun. The one I'm talking about in this blog post was the opportunity to learn more about AWS Services and Event Driven Architecture (EDA).

That was also the opportunity to explore the Kiro CLI capabilities with pictures & diagrams. Especially with the new Claude Opus 4.6 (I guess with can get quite similar results with Claude Sonnet 4.5 by the way).

That led me to explore more techniques, like asking why an architecture is better than another one. Then list architecture characteristics, generate fitness functions, and prevent from architecture flaws in the future (the dual-write problem in this case).

When I see all these possibilities, I really feel that we'll be able to build more sophisticated software more easily and software architect jobs will get more and more exciting!

Create a Professional Certification Quiz with Kiro

Olivier Lemaitre — Sun, 11 Jan 2026 15:23:41 +0000

I hold many AWS certifications. That doesn't mean I know everything about AWS, far from that. Actually, AWS is so huge that many certification questions will test you on unknown situations. It's also difficult to have an experience with everything, especially with certifications like the "AWS Solutions Architect professional" which spans tens of AWS services.

Therefore, you have to prepare for your certification exams in order to "compensate" your weaknesses. The main solutions are to read the FAQs and the documentation of the services, practice them through workshops or at work, draw diagrams, take notes, follow videos on AWS Skill builder or Udemy, and train with exam-like questions on platforms like Tutorial Dojo.

The best preparation for me is a combination of all these, but the latest option (training on exam-like questions) is important. I remember how destabilized I was the first time I took an AWS certification exam. At the time (2015) we didn't have a lot of examples and I had no real techniques on how to read and answer questions.

Therefore, you must be prepared to answer questions. At least, the days before taking the exam, you must train your brain to it. Especially for Professional Certifications.

I recently had to renew my Solutions Architect Professional certification and I decided to use recent GenAI capabilities with AWS Kiro IDE in order to add another preparation tool and train on my weaknesses.

I wanted to share this. So, here is the story.

What is a Professional certification question?

First, let's see what is a Pro Cert question.

Professional Certifications are different from Associate Certifications on several aspects. They come with a combination of 4/5 services (instead one 1/2 service(s) for associate exams) which makes the questions longer and more complex. Moreover, more than one proposition can make sense sometimes, but you have to identify the less expensive solution to tick the correct answer.

A certification question example

You can find solutions architect sample questions here: https://d1.awsstatic.com/training-and-certification/docs-sa-pro/AWS-Certified-Solutions-Architect-Professional_Sample-Questions.pdf

Let's extract one of them (question 4):

4) A company runs a serverless mobile app that uses Amazon API Gateway, AWS Lambda functions, Amazon Cognito, and Amazon DynamoDB. During large surges in traffic, users report intermittent system failures. The API Gateway API endpoint is returning HTTP status code 502 (Bad Gateway) errors to valid
requests.

Which solution will resolve this issue?

A) Increase the concurrency quota for the Lambda functions. Configure Amazon CloudWatch to send notification alerts when the Concurrent Executions metric approaches the quota.

B) Configure notification alerts for the quota of transactions per second on the API Gateway API endpoint. Create a Lambda function that will increase the quota when the quota is reached.

C) Shard users to Amazon Cognito user pools in multiple AWS Regions to reduce user authentication latency.

D) Use DynamoDB strongly consistent reads to ensure that the client application always receives the most recent data.

One technique to answer a certification question

Here is one technique to answer the question (N.B. I sometimes use other techniques, depending on the question, but I won't explain them here in order to keep this part short enough).

So, as you may see, the question involves multiple services (4 in this case) so you have to spot the issue with the most certainty.

What I do when I see this kind of question is to try to visualize things in a "pattern" (in this case a multi-tier application pattern with authentication).
N.B.: I heavily draw diagrams when I'm preparing for a certification.

Then, I try to think of one possible answer without looking at the propositions. In this case I know that the bad gateway error (502) is probably an issue with the backend behind the API gateway. Probably a Lambda function issue, but I'm not completely sure at this stage.

Then, I read the answers, looking for inconsistencies or non-relevant answers that sound weird to me, like this one:

D) Use DynamoDB strongly consistent reads to ensure that the client application always receives the most recent data.

Which says the issue is due to the lack of freshness of data (that sounds weird for a 502 error).

The Cognito answer sounds weird as well

C) Shard users to Amazon Cognito user pools in multiple AWS Regions to reduce user authentication latency.

It does not seem to be a latency issue (I would better expect a timeout in this case).

So, I eliminated 2 answers, I can now make my choice among the remaining 2.

A) Increase the concurrency quota for the Lambda functions. Configure Amazon CloudWatch to send notification alerts when the Concurrent Executions metric approaches the quota.

B) Configure notification alerts for the quota of transactions per second on the API Gateway API endpoint. Create a Lambda function that will increase the quota when the quota is reached.

They both propose to increase a quota: should I increase the number of concurrent lambda functions or the number of API calls per second?

But, if the number of PAI calls per second was reached I wouldn't get this 502 response, but rather a 429 error code. Moreover, as I explained earlier, a 502 error is an issue behind the API gateway. Therefore that confirms the issue must happen due to lambda functions, therefore I choose answer A) with a bit of confidence.

Let's verify the answer to the previous question

Let's see what the answer and explanation are from the sample questions document:

4) A – Amazon API Gateway will intermittently return HTTP status code 502 (Bad Gateway) errors if the AWS Lambda function exceeds its concurrency quota. Option B is incorrect because, in this case, API Gateway would
return a status code 429 error for too many requests. Option C is incorrect because the errors occur during calls to the API Gateway API endpoint, not during the authentication process. Option D is incorrect because stale data would not cause a Bad Gateway error.

Ok, my reasoning wasn't too bad, even though I rarely found myself in the exact situation described in the question.

N.B. : You make think that I could follow my first intuition with lambda functions and answer A) right away, but some questions can be quite subtle and I would advise to make sure you can eliminate other responses.

Of course, knowing the services (like DynamoDB) + HTTP and having some experience with those helps a lot. However, the way you read the question will also help, like identifying important words and elements that will confirm the right answers and/or discard others.

Can you find questions tailored to your needs?

Of course, I don't have experience with all the services covered in the certification, and maybe I want to focus on them when I'm preparing for it (that's also a way to improve my skills in general).

So, I asked myself, can I generate bespoke questions on specific services where I feel weak and answer them within an application that would look like a certification application?

Then I thought, let's try to develop this with GenAI and Kiro (the new name for Amazon Q Developer)...

Step 1 - Generate a GUI for the certification questions

We can surely generate certification questions with LLMs, but first I wanted to create a little app that allows me to answer questions with something that resembles exam conditions.

Let's do it with Kiro... in Spec Driven Mode

I want a simple web application that can work locally (a web page in an IDE) that asks one certification question with 4 possible answers

First I get a requirements.txt file containing 4 requirements that I can inspect and modify.

But, let's keep these requirements as is, and accept them all. Then move to the design phase.

The design phase gives you a document containing the application architecture and the design of the GUI components (like the HTML structure of the web page for this single page application). It's a bit like a readme for the developers of the application.

Again, I can modify that and change a few things, but in this case let's directly move to the implementation phase.

In the implementation phase, Kiro will generate a list of tasks. Then, I can click on "Start Task" to generate the related code (e.g. 1.1 create the index.html with container, question, 4 answer options (A-D), submit button, ...)

The result (that I can watch thanks to Live Preview VS Code extension) is quite basic, but that's exactly what I want.

Now what is *important * from there is to initiate a git repo so I can save the result and roll back if the next step fails or does not produce what I expect.

These 3 commands in the terminal are enough:

git init
git add .
git commit -m "create index.html page"

I continue with the next task (CSS formatting), and in a matter of seconds I get this rendering:

That's nice for someone like me who is not an everyday front end developer 😊

Now, if I'm satisfied, I can commit this, or if I want to change something, I can reject it, modify the task description and regenerate.

Actually, I kept it as it was, and continued to iterate this way through all tasks.

After a 20 minutes or so, I got a working quiz with 4 possible answers.

Which is very nice.

Let's switch to vibe mode now...

Now, I want to quickly improve this first result and I have 2 options: carry on with the Spec Mode or Vibe Mode.

I chose Vibe mode, because my goal isn't to share this application with a team of developers, but to prototype a solution that suits my needs only.

So, I asked for some improvements in vibe coding mode, like this one:

Create a questionData with 2 questions (update the logic consequently)

Again, what is important is that I can test a modification, then accept or reject it (i.e. rollback if I'm not satisfied). If I reject, I can reformulate my demand; otherwise I can commit the generated code.

After a few iterations, I have an interesting application structure that accepts a list of questions and a score at the end.

This is exactly what I wanted to achieve first.

Step 2 - Populate the Quiz App with sample questions

Now let's populate this with more interesting (professional) questions.

Feed the quiz app using the sample question document

For this I extracted the text from the solutions architect professional sample questions pdf because Kiro doesn't read pdf directly yet.

Then I asked:

From #Solutions-Architect-Professional-Sample-Questions.txt create a new questionData.js (update quiz logic if necessary)

Answer questions in the generated quiz app

That worked quite well (it even noticed when questions needed multiple answers and updated the quiz logic consequently).

Here is, below, the question I took as an example in the first paragraph of this blog post:

Step 3 - Generate new certification questions

This is where it becomes interesting😊.

Create new questions, tailored to you needs

Now that I have my application and data structure, let's generate/invent new questions.

replace existing questions with 5 questions having #Solutions-Architect-Professional-Sample-Questions.txt style related to api gateway, lambda, dynamoDB

And that works. I get questions pretty close to real exam questions for a first try (I also get explanations to understand why a response is good and not the others).

Maybe the level of difficulty is high here, but again this is a first try and we surely can adjust this, but personally, I like it 😊

Here are the generated questions if you want to have an idea:

Question 1:

Question 2:

Question 3:

Question 4:

Question 5:

Score:

What can we do next

I'm sure I could go much further by specifying more context to Kiro (i.e. using Claude Opus 4.5 LLM model in my case) to generate more questions with my preferences.

For example, I tried to use the AWS Documentation MCP Server that reads AWS services documentation. Actually, some certification questions are often related to some part of the documentation.

But, I believe we can have something even more tailored to our specific needs, in order to make us progress faster with more fun!

If you ever wanted to add improvements or test this prototype at home, here is a GitHub repo with the Kiro generated code: https://github.com/welcloud-io/wio-professional-certification-quiz-generator

Conclusion

Preparing a certification can be a challenge and you need to combine multiple tools to prepare them. Training your mind with exam-like questions can be an important one.

With today's GenAI we can create application quickly, at the speed of light compared to not so long ago. Kiro IDE, propose 2 approaches, Spec Driven and Vibe Coding mode to achieve this. I don't have a preference yet, even though I think Spec Driven Development might be better suited for large teams already using this kind of workflow. Anyway, what is important for me is to work in small steps whatever the choice.

And even if I could rapidly create an app and generate bespoke certification questions with Kiro (which was unimaginable just 3 years ago), I have the feeling that I just scratched the surface of this! And that we can do much better! Sometimes I'm wondering if certifications (and exams in general) will still look the same in the near future!

I hope that will inspire people to create quickly what they are missing in their everyday job (not only a certification quiz app). The kind of idea you thought would have taken days to build would now take a few hours to come to life. And obviously an IDE like Kiro can really help to achieve this.

Understand how AI Agents work, with AWS Strands

Olivier Lemaitre — Sun, 14 Sep 2025 16:56:38 +0000

What are AI Agents? Why are they so popular these days? What's the mechanics behind them? Do we have to learn a lot of new skills to build one?

I found myself asking these same questions recently.

Then I discovered Strands Agent (provided by AWS), and I found it so simple and interesting to answer all these questions that I wanted to share my discoveries here.

How does the world work without agents?

I was inspired by a simple, but good example in which an agent could be useful: Booking a table at a restaurant online.

First, let's see how you could potentially execute that workflow WITHOUT an AI agent.

1. You open your browser
2. You look for a restaurant near the place you want to go
3. You select some restaurants and look at the menu
4. You select the restaurant with your food preferences
5. You fill in a form (your name, date & time, ...)
6. You validate your reservation

N.B.: Our job as engineers is to create value (i.e. make users' lives easier), and shortening workflows is a very common way to create value. Actually, AI agents can shorten workflows; that's certainly why they are valuable. So, let's explore this further.

What can an AI agent do?

A Simple conversation example

With an AI agent we could imagine this conversation:

You : What is the best restaurant serving veggie burgers in Paris?
The Agent: Green Farmer's is the best veggie burger restaurant in Paris

You : Reserve a table at Green Farmer's tomorrow at 7pm please.
The Agent: ok, table is booked.

How is it possible? I don't have to make a search on the web, I don't even have to fill in a form or click on a button to validate!

That's because the agent will take care of that for you.

The use of tools behind the scenes

Technically, here is the generic and simplified mechanics of agents (as I understand it)

Let's take a concrete example.

A simple addition example

Imagine that you want to create an agent that computes additions.

Here is what happens.

After I send my prompt "compute 1 + 1":

1 - The agent sends the prompt to the LLM with the available tools (i.e. my add function), and the LLM answers with the tools to use if necessary (in this case it will ask using the add() tool)

2 - The agent calls the tools (in my case add(1+1)) and gets the answer

3 - The agent sends the context and the tools answer, so it can create the final response (in my case 1 + 1 = 2)

Of course, this simple addition can be done with the LLM without any tool, but only because the result is obvious and present in the model they are trained with.

However if you want to compute more complex things (a sinusoidal function for example), I would recommend not to rely too much on the NON deterministic output of the LLMs :)

A simple table booking example

So, an LLM needs tools to do things they cannot do on their own, like computing complex things, searching the web or writing to a database for example.

For instance, when we say "Reserve a table at Green Farmer's tomorrow at 7pm please.", here is what could be the mechanic behind the scenes:

In this case the LLM needs a tool to book the table at the restaurant (it cannot do it on its own), that's why we have a book() tool which is actually a function that executes standard code (e.g. python).

We could also add tools to search the web or tell when is "tomorrow" (which is something an LLM will never know).

In the example above, the agent process would be this one:
1 - Send the prompt to the LLM specifying that a book() tool is available
2 - Call the book() tool if the LLM answers to do so
3 - Send the tool answer to the LLM which creates a final response

That's it. So far you should have understood the basics of agents.

How to build an agent with Strands?

With your new knowledge in mind, you could code your own agents from scratch.

However, it's best to use a framework to handle the plumbing behind the scenes and actually AWS has it's own framework: Strands Agents.

Let's take the table reservation and let's see what would be the components to declare with Strands.

Actually a Strands agent is a Python class that you initiate with 3 main parameters:

The LLM model that you want to use (Claude4Sonnet for example)
The Tool list (added the tool registry) that contains all the tools we can send the the LLM so it can make a choice
The system prompts which defines the accurate role of the agent. For example "You are a restaurant assistant helping customers reserve a table...", to make sure it won't respond off topic.

Here is what the Python code of a Strands AI agent could contain

...
@tool
def create_booking(tool: ToolUse, **kwargs: Any) -> ToolResult:
  ...
...
system_prompt = "You are a restaurant assistant ..."
...
agent = Agent(
    model=model,
    system_prompt=system_prompt,
    tools=[create_booking, delete_booking],
)
...
result = agent("Reserve a table at Green Farmer's tomorrow at 7pm please.")

That's it. Now you know how to build an agent with Strands, and that's not very difficult as you may see. The difficulty resides more in the writing of the system prompt and the writing of the tools code. This is where you should focus on from my point of view.

Some more capabilities for agents & Strands

Call external systems like databases

Previously the "book(...)" tool was supposed to book a table at the restaurant. That could be done by calling an external API or/and writing to a database for instance.

Here is a representation of a tool calling a database. This database could be any kind of database like DynamoDB, RDS MySQL, ...

Call remote tools with MCP (Model Context Protocol)

Your tools (i.e your functions) can be called "locally", inside your agent process, but they can be called outside the agent process by calling a server.

This server can run locally (through stdio protocol) or remotely (through streamable http protocol).

We can see an MCP server like a classic http server that can communicate with an AI agent. The AI Agent can call this server to list the tools that it provides for example.

Strands integrate with MCP Servers as we can see below.

Agent to Agent (A2A) with Strands

We can imagine that an agent not only uses tools, but... other agents.

These agents actually like tools, but they contain a Strand agent.

We can imagine specialized agents with their own system prompts that interact with the LLM to achieve a task. For example, I can have an agent to reserve a restaurant, but also an agent to plan a trip:

You: Reserve a table at Green Farmer's tomorrow at 7pm please and show me how to get there from Gare du Nord, Paris.

Agent: ok, table is booked. Here is the best way to get there...

Below is a representation of this pattern. Note that we need an "orchestrator agent" to take care of the orchestration between agents.

N.B.: Strands supports the A2A protocol which runs on top of HTTP, exactly like the MCP protocol. We can, by the way, mix A2A and MCP in the same agent depending on the sophistication you need (i.e. MCP is simpler).

Deploy and expose your AI Agent to the world

When you are happy with an agent, you can deploy it on a server and call it through an API.

You can run the AI Agent and its tool in a Docker container (using ECS/Fargate for example) or in a Lambda function as we can see below.

We could also do something more complex, calling tools outside the containers using MCP.

My first AI Agent with Strands

I couldn't resist the idea of generating a Strands agent from a Drawio Diagram with Amazon Q Developer.

That wasn't straight forward, it's not easy to reproduce, but that was really fun and full of learnings. So I decided to share this part as well.

Here is what I wanted to achieve for my first AI agent

It's a simple Strands AI agent. I want it to... reserve a table at a restaurant :)

First I drew the diagram above and I created a rule file that I called 'ProfessionalTwin', where I describe what I use as a professional.

- I use python 3.10
- I use AWS CDK V2
- I use AWS Strands SDK for AI Agents

Then I asked Q developer

@diagram.drawio.xml generate application

It generated the application, but introduced a few errors, and it didn't work right away, so I had to create some more files containing rules for each thing I had put in my Professional Twin file: CDKRules, PythonRules and StrandsRules.

Here is, for example, what StrandsRules contains:

When asked to use AWS Strands SDK, here are the rules

- use lambda layer for strands packages
- install strands-agents python module in lambda layer folder
- install strands-agents-tools python module in lambda layer folder
- Strands Agent Class parameters are model, tools, system_prompt
- create rules with @tool decorator
- create a system prompt that describes the role of the agent
- use "anthropic.claude-3-haiku-20240307-v1:0" model
- Allow lambda calling bedrock with stream response

After several trials I reused:

@diagram.drawio.xml generate application

That gave me a URL as an output, I clicked on it, and I could start a conversation with my assistant. I then could verify my reservation in my DynamoDB table. And I didn't write or modify a single line of code!

Don't get me wrong, I'm not saying we can generate everything from diagrams, but that can help bootstrap ideas.

For example I had no clue how to design and build the landing page. Amazon Q Developer created this in a few seconds!

Now I can iterate on this code.

I shared the code generation result in a GitHub repo.

You can also follow this little tutorial and try to make a generation on your side, improve it or just review and deploy the generated result.

Conclusion

Are AI Agents a revolution? Are they great? If so, why?

From the value creation perspective that seems to offer great perspective and that should shorten many processes. Combined with voice that should be impressive. And I clearly understand the enthusiasm around this.

From the technical point of view, I tend to think AI agents are traditional servers using the power of LLMs to process a query. That's one more component in the architecture.

Moreover, it's a NON-deterministic component that can have unexpected behaviors sometimes. That comes with a lot of technical questions and some challenges as well.

I guess a framework like Strands can really help answer some of them. I'm personally a big fan of its simplicity. That's a great discovery!

If you want to practice and understand more about AI Agents, I warmly recommend this workshop : Getting Started with Strands Agents

Building and Using MCP Servers in Amazon Q CLI

Olivier Lemaitre — Sun, 04 May 2025 17:21:35 +0000

What is an MCP server? Even if you know that MCP stands for Model Context Protocol, that's no that obvious to understand or see the benefits, at least for me.

I thought the best way to figure this out was to build one. so I started to build the simplest MCP server possible and play with it. After that, I used an existing open source MCP server to understand more.

1) The simplest MCP Server

I could ask Amazon Q (or an LLM like Anthropic Claude) to build the simplest MCP server for me, but I didn't get satisfying answers. It was not relevant or too complex already, so I looked for some examples with a web search engine, and I cherry picked some ideas.

1.1) Using FastMCP v2 to create the simplest MCP server

I discovered that there was a python library that could handle this protocol: FastMCP v2.

Little refresher: a protocol is a set of rules defining how data must be formatted, transmitted, received between systems. In our case how the coding assistant based on LLM (e.g. Q Developer) must communicate with the server and how the server should answer it.

FastMCP can be compared to flask for python or express for node. And like flask or express will handle an HTTP request between a web browser and remote resources (e.g. HTML pages), FastMCP will handle the communication between the LLM and the server tools (e.g. python functions).

After a little exploration, I took that simple example, that we can find in the FastMCP documentation

# server.py
from fastmcp import FastMCP

mcp = FastMCP("Demo 🚀")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

if __name__ == "__main__":
    mcp.run()

It's very similar to what you would do with a flask server

from flask import Flask

app = Flask(__name__)

@app.route('/')
def hello():
    return "<h1>Hello, World!<h1>"

if __name__ == '__main__':
    app.run()

The difference is that in the first case you will expose functions also called tools (e.g. the 'add' method) to your coding assistant, in the second case you will expose functions to your web browser.

So, that means I can start this server locally like a flask server

N.B.: I need 'fastmcp' to be installed with

pip install fastmcp

$ python3 server.py 
[05/04/25 14:39:37] INFO     Starting server "Demo 🚀"...

That works, but it's not "connected" with Q CLI, which is unaware of this server.

1.2) Integrate the simplest MCP server with Q CLI

Now, I want Q CLI to use my 'simplest_mcp_server', and for that I will need to initiate Q CLI with this server.

The way we do that is by creating this file:

~/.aws/amazonq/mcp.json

With the content below.

{
  "mcpServers": {
    "simplest-mcp-server": {
      "command": "python3",
      "args": ["server.py"]
    }
  }
}

Note that the json file describes how to start the server, like we did above, but this time Q will start it during Q initialization.

Now I start Q CLI (make sure you are in 1.9.1 version or above), and I get that result:

$ q
To learn more about MCP safety, see https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-security.html
✓ simplest_mcp_server loaded in 0.59 s
✓ 1 of 1 mcp servers initialized

Welcome to 

 █████╗ ███╗   ███╗ █████╗ ███████╗ ██████╗ ███╗   ██╗     ██████╗ 
██╔══██╗████╗ ████║██╔══██╗╚══███╔╝██╔═══██╗████╗  ██║    ██╔═══██╗
███████║██╔████╔██║███████║  ███╔╝ ██║   ██║██╔██╗ ██║    ██║   ██║
██╔══██║██║╚██╔╝██║██╔══██║ ███╔╝  ██║   ██║██║╚██╗██║    ██║▄▄ ██║
██║  ██║██║ ╚═╝ ██║██║  ██║███████╗╚██████╔╝██║ ╚████║    ╚██████╔╝
╚═╝  ╚═╝╚═╝     ╚═╝╚═╝  ╚═╝╚══════╝ ╚═════╝ ╚═╝  ╚═══╝     ╚══▀▀═╝ 



╭───────────────────────── Did you know? ─────────────────────────╮
│                                                                 │
│   You can programmatically inject context to your prompts by    │
│           using hooks. Check out /context hooks help            │
│                                                                 │
╰─────────────────────────────────────────────────────────────────╯


/help all commands  •  ctrl + j new lines  •  ctrl + k fuzzy search
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
>

You can see the MCP server initialisation

...
✓ simplest_mcp_server loaded in 0.59 s
✓ 1 of 1 mcp servers initialized
...

You can also verify the 'add' function is in the list of tools by typing '/tools' (it's like listing the routes for a flask server)

> /tools

Tool                           Permission
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔simplest_mcp_server (MCP):
- simplest_mcp_server___add    * not trusted

Built-in:
- report_issue                 * trusted
- fs_write                     * not trusted
- execute_bash                 * trust read-only commands
- use_aws                      * trust read-only commands
- fs_read                      * trusted


Trusted tools can be run without confirmation

* Default settings

>

1.3)Test my simplest MCP server with Q CLI

Now when I ask Q to add 2 numbers, Q will use the 'add' function (i.e. tool):

> add 1 + 1

I'll calculate 1 + 1 for you.


🛠️  Using tool: add from mcp server simplest_mcp_server
 ⋮ 
 ● Running add with the param:
 ⋮  {
 ⋮    "arguments": {
 ⋮      "a": 1,
 ⋮      "b": 1
 ⋮    },
 ⋮    "name": "add"
 ⋮  }
Allow this action? Use 't' to trust (always allow) this tool for the session. [y/n/t]:

>

It shows what it will do (i.e. call the add function) and ask if you want to execute this or not.

If you are ok, you can type 'y' to trust the tool this time only. Or you can type 't' to trust it all the time (at least until you exit Q CLI).

I choose 't' and I get the result of the 'add' tool

Allow this action? Use 't' to trust (always allow) this tool for the session. [y/n/t]:

> t

 ⋮ 
 ● Completed in 0.5s


The result of 1 + 1 is 2.

>

Now when I list my tools I can see my 'add' function is trusted

> /tools

Tool                           Permission
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔simplest_mcp_server (MCP):
- simplest_mcp_server___add      trusted
...

and when I ask another addition it uses the tool automatically. No question asked as you can see:

> add 2 + 2

I'll calculate 2 + 2 for you.


🛠️  Using tool: add (trusted) from mcp server simplest_mcp_server
 ⋮ 
 ● Running add with the param:
 ⋮  {
 ⋮    "arguments": {
 ⋮      "a": 2,
 ⋮      "b": 2
 ⋮    },
 ⋮    "name": "add"
 ⋮  }
 ⋮ 
 ● Completed in 0.12s


The result of 2 + 2 is 4.

>

Now when I ask Q CLI to subtract 2 numbers it tells me it doesn't have the tool (i.e. the function) for that. Which is true because I only have one add function in my server file. However, Q can make a simple subtraction.

> substract 3 - 2

I don't have a direct subtraction function available in my tools, but I can help you with this calculation.

The result of 3 - 2 is 1.

If you'd like me to perform more complex calculations or operations, please let me know!

>

For simple calculation, an MCP server is not necessary, but let see how we can use MCP servers for more specific tasks that the LLM is less good at or need more (up to date) context.

2) Using an existing MCP Server

I will now use a trusted MCP server that has been developed by AWS here https://github.com/awslabs/mcp/blob/main/src/aws-diagram-mcp-server/README.md

This MCP server will help generating diagrams with the python Diagram library. It's diagram as code, but unlike mermaid which uses static code, Diagram uses python imperative code.

Then, I just follow the documentation here: https://awslabs.github.io/mcp/servers/aws-diagram-mcp-server/

And I update my :

~/.aws/amazonq/mcp.json

with

{
  "mcpServers": {
    "awslabs.aws-diagram-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.aws-diagram-mcp-server"]
    }
  }
}

This time I need 'uvx' to be installed with

pip install uv

I start q and list the tools

q
To learn more about MCP safety, see https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-security.html
✓ awslabsaws_diagram_mcp_server loaded in 2.34 s
✓ 1 of 1 mcp servers initialized

Welcome to 

 █████╗ ███╗   ███╗ █████╗ ███████╗ ██████╗ ███╗   ██╗     ██████╗ 
██╔══██╗████╗ ████║██╔══██╗╚══███╔╝██╔═══██╗████╗  ██║    ██╔═══██╗
███████║██╔████╔██║███████║  ███╔╝ ██║   ██║██╔██╗ ██║    ██║   ██║
██╔══██║██║╚██╔╝██║██╔══██║ ███╔╝  ██║   ██║██║╚██╗██║    ██║▄▄ ██║
██║  ██║██║ ╚═╝ ██║██║  ██║███████╗╚██████╔╝██║ ╚████║    ╚██████╔╝
╚═╝  ╚═╝╚═╝     ╚═╝╚═╝  ╚═╝╚══════╝ ╚═════╝ ╚═╝  ╚═══╝     ╚══▀▀═╝ 



╭───────────────────────── Did you know? ─────────────────────────╮
│                                                                 │
│        You can use /compact to replace the conversation         │
│      history with its summary to free up the context space      │
│                                                                 │
╰─────────────────────────────────────────────────────────────────╯


/help all commands  •  ctrl + j new lines  •  ctrl + k fuzzy search
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> /tools

Tool                                                      Permission
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔Built-in:
- fs_write                                                * not trusted
- report_issue                                            * trusted
- execute_bash                                            * trust read-only commands
- fs_read                                                 * trusted
- use_aws                                                 * trust read-only commands

awslabsaws_diagram_mcp_server (MCP):
- awslabsaws_diagram_mcp_server___list_icons              * not trusted
- awslabsaws_diagram_mcp_server___get_diagram_examples    * not trusted
- awslabsaws_diagram_mcp_server___generate_diagram        * not trusted


Trusted tools can be run without confirmation

* Default settings

>

I can see 3 new tools, that can be used:

list_icons
get_diagram_examples
generate_diagram

Then I ask

create a diagram from the code in this folder

And it starts using the list_icons tool

Now that I understand the architecture, I'll create a diagram that represents this serverless application. Based on the SAM template, we have:

1. A landing page function that serves an HTML page
2. A feedback function that records feedback in DynamoDB and sends notifications via SNS
3. A DynamoDB table for storing feedback
4. An SNS topic for email notifications


🛠️  Using tool: list_icons from mcp server awslabsaws_diagram_mcp_server
 ⋮ 
 ● Running list_icons with the param:
 ⋮  {
 ⋮    "arguments": {},
 ⋮    "name": "list_icons"
 ⋮  }
Allow this action? Use 't' to trust (always allow) this tool for the session. [y/n/t]:

> y

Then, it uses the generate_diagram tool. The input argument is the Diagram python code that Q as generated. Here generate diagram means executing the python code so it creates a diagram in png format.

🛠️  Using tool: generate_diagram from mcp server awslabsaws_diagram_mcp_server
 ⋮ 
 ● Running generate_diagram with the param:
 ⋮  {
 ⋮    "arguments": {
 ⋮      "code": "from diagrams import Diagram, Edge\nfrom diagrams.aws.compute import Lambda\nfrom diagrams.aws.database import Dynamodb\nfrom diagrams.aws.integration import SimpleNotificationServiceSnsTopic\nfrom diagrams.aws.network import APIGateway\nfrom diagrams.aws.general import Users\n\nwith Diagram(\"Serverless Feedback Application\", show=False, direction=\"LR\"):\n    # Define components\n    users = Users(\"Users\")\n    api = APIGateway(\"API Gateway\")\n    \n    # Lambda functions\n    landing_page = Lambda(\"Landing Page\\nFunction\")\n    feedback_function = Lambda(\"Record & Confirm\\nFeedback Function\")\n    \n    # Backend services\n    dynamodb = Dynamodb(\"Feedback\\nTable\")\n    sns = SimpleNotificationServiceSnsTopic(\"SNS Topic\\n(Email Notifications)\")\n    \n    # Define relationships\n    users >> api\n    api >> landing_page\n    api >> feedback_function\n    \n    feedback_function >> dynamodb\n    feedback_function >> sns",
 ⋮      "filename": "serverless_feedback_app_diagram.png",
 ⋮      "workspace_dir": "/home/olivier/wio-from-diagram-to-code-with-amazon-q-developer/_playground/vscode-app-folder"
 ⋮    },
 ⋮    "name": "generate_diagram"
 ⋮  }
Allow this action? Use 't' to trust (always allow) this tool for the session. [y/n/t]:

>

Then I receive that result, which is not bad.

The tools (the python functions) created a new folder 'generated_diagram' and created the png file containing the diagram.

Then I thought, can we get a similar result WITHOUT an MCP server? And I removed my Diagram MCP server and asked

create a diagram with python Diagram package from the code in this folder

I receive a quite similar result

The difference it that it generates the python file and execute it locally (not on the server).

Which means that, as for a simple calculation, an MCP server is not always necessary to draw a simple diagram.

How to reproduce this at home

I've created a GitHub repo with multiple starting points you can use to quickly test what I explained and more. Here are the commands to execute in VS Code.

Start tutorial environment

$> git clone git@github.com:welcloud-io/wio-from-diagram-to-code-with-amazon-q-developer.git

$> cd wio-from-diagram-to-code-with-amazon-q-developer
$> ./install-mcp-utils.sh # Installs uv + fatsmcp if not installed yet
$> ./install-q-cli.sh # Installs q cli (>=19.1) if not installed yet

$> ./start-vscode-tutorial-window.sh

Test simplest MCP server

$> ../init-playground.sh --with-simplest-mcp-server
...
Where do you want to start from ?: 0 #Empty folder
...

$> cat ./simplest-mcp-server.py # Displays MCP server content
...

$> cat ~/.aws/amazonq/mcp.json # Displays MCP configuration
...

$> q
...
✓ simplest_mcp_server loaded in 1.34 s
✓ 1 of 1 mcp servers initialized
...

> add 1 + 1
...

Test diagram MCP server

$> ../init-playground.sh --with-diagram-mcp-server
...
Where do you want to start from ?: 1 #Folder with code
...

$> cat ~/.aws/amazonq/mcp.json # Displays MCP configuration
...

$> q
...
✓ awslabsaws_diagram_mcp_server loaded in 4.79 s
✓ 1 of 1 mcp servers initialized
...

> create a diagram from the code in this folder
...

Conclusion

Finally, creating an MCP server that works with Q CLI is not very difficult. Using an existing MCP server is not that hard either. But, I note that we the in-house functionalities of the coding assistant can be sufficient for basic tasks. Therefore, my opinion is that MCP servers should be built or used for hard tasks that the LLM cannot deal with.

Diagram As Prompt (or how to write less text with Amazon Q Developer CLI)

Olivier Lemaitre — Mon, 07 Apr 2025 17:07:39 +0000

As an architect in the software industry, you have to first to understand the problem you have to solve (don't forget this 😉) and then find a solution.

In many situations, you may have to prototype these solutions. To see if it fits well with the problem at hand or to create modules that can be used by others for example.

Implementing and testing can take time, but today coding assistants based on LLM (Large Language Models) can help to generate the code you need, which is a big step forward.

But still, writing good prompts with all the characteristics of your architecture isn't that intuitive and not very flexible in an exploratory phase. At least less intuitive and flexible than an architecture diagram.

So, what if we could directly use a diagram to express our architecture intents, iterate on it and leave the LLM deals with the implementation?

This is something I already tried, somehow, but I pushed this a bit further with Amazon Q Developer CLI. And that's what I explain in this blog post.

The prerequisites

You will need VS Code with Amazon Q Developer, some extensions and Amazon Q CLI 1.7.2 or above to make this work (Other combination of tools should be possible, but I didn't try them).

You can find how to configure and use Amazon Q Developer Desktop with diagrams in this blog post:

https://dev.to/welcloud-io/from-diagram-to-code-with-amazon-q-developer-2da4

You can also find how to install Amazon Q Developer CLI here:

https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-installing.html

If you are working with Ubuntu 22.04, you can find some installation scripts & tutorials in this repo:

https://github.com/welcloud-io/wio-from-diagram-to-code-with-amazon-q-developer

Let's begin this journey!

1) Create a simple diagram

As explained in the introduction, the technique I describe can be useful to explore solutions to a problem.

As an example here, I will explore some solutions to protect my APIs calls.

So, let's first create a blank diagram

Then let's add the Amazon API Gateway service icon to the diagram.

And since I don't need a backend to test this, let's represent a mock integration which means the API will always return the same answer.

That's simple and perfect for testing purpose.

2) Generate code from diagram

That's already possible with Q Desktop & Q CLI as shown in this 2 blog posts:

https://dev.to/welcloud-io/talk-to-your-diagrams-with-amazon-q-developer-cli-13bc

https://dev.to/welcloud-io/from-diagram-to-code-with-amazon-q-developer-2da4

In both blog posts, I use the same prompt:

can you generate application from the drawio diagram (I want the code of the lambdas to be written in python and the infrastructure as code with the python cdk v2)

However, I always have to search for this prompt and then copy/paste it in the Q chat interface. And the reason why I always use the same prompt is because it gives good results, but also because python for lambdas and python CDK v2 for infrastructure is what I use at the moment.

Why should I repeat that information each time? Can Q Developer simply know my preferences?

And the answer is... yes! Since recently, it's possible with Amazon Q Developer Desktop and CLI (version 1.7.2)!

So let's create a "Professional Twin", who will work with my habits!

3) Create your "Professional Twin"

This capability is really simple to put in place, but very powerful in my opinion.

At the root of your folder, you can create a specific folder (.amazonq/rules) where you can create your markdown files (.md) containing your rules.

And that's what I did:

# Create rule folder
$> mkdir -p .amazonq/rules

# Create rule file
$> touch .amazonq/rules/FROM_DIAGRAM_TO_CODE_RULES.md

Then I edited my file, and I wrote this:

When asked to generate application:
- search for the drawio diagram
- use python 3.9 for lambda code
- use python CDK V2 for infrastructure as code

If the folder contains code already, keep this code in sync with the diagram

As usual, I express this very naively to show that it's really easy to get interesting results quickly. That was my first try by the way.

However, I encourage you to tailor this kind of file carefully, and experiment your rules in order to make sure you get the best results for your use cases each time.

4) Generate Code from Diagram iteratively

This is where it's becoming very interesting.

Now that my rule file is created. I will iterate on my diagram while always using the same prompt in Q CLI Chat:

| > generate application

Let's go!

Iteration 1: Generate code from scratch

My folder is almost empty and only contains my diagram and my rules.

In my terminal, I type

| $> q chat

And then I start to ask a first generation using the below prompt:

| > generate application

As you can see in the screenshot, Q takes my rules into account (my "professional twin" is working 😊)

Then I enter 'y' (yes) to all the Q CLI proposals, and at the end I get a folder full of files ready to be deployed!

And that's what I did, I deployed the app without quitting Q chat (I use the exclamation mark '!' for this)

Once deployed, I go to my browser and test the API URL (that was output by Q in my CDK template)

And I get this response (once again created by Q in my CDK template)

N.B. I didn't have to check or modify my CDK code at this point!

Iteration 2: Test the API Lambda Authorizer Solution

Now, I want to test a lambda authorizer (that means something that will validate a custom API key) to protect my API.

Let's start from the previous diagram...

...and add a lambda labeled "Lambda Authorizer".

And now, let's reuse the exact same prompt

| > generate application

First, Q CLI proposes to keep the code in sync with the diagram

Second, it detects that there is a difference between the diagram and the code (The lambda authorizer)

In fact, this is the behavior I expect from my "professional twin".

I don't know if you have noticed earlier in my rule file, but I specified that I wanted to keep my code in sync with my diagram, here is the rule file again:

When asked to generate application:
- search for the drawio diagram
- use python 3.9 for lambda code
- use python CDK V2 for infrastructure as code

If the folder contains code already, keep this code in sync with the diagram

Let's deploy the changes:

Let's test the url again, and this time we are not authorized because we haven't used an API key.

To completely verify it works, I also test this from the command line (without leaving Q CLI and using '!'). These curl commands were proposed by Q CLI chat and I just copy/pasted them.

Then I can verify that I can get an API answer with a valid token, otherwise I cannot.

N.B. I didn't have to read or change the CDK code, or the lambda code so far!

Iteration 3: Test a Captcha Solution

Now let's say that I changed my mind, and I want to test a Captcha.

A Captcha is another way to protect my API and make sure only humans can call it.

Creating a Captcha for your API is possible with AWS WAF (Web Application Firewall) where you can configure a Captcha Rule.

So, let's first let's add a WAF icon on the diagram with a label set to 'WAF with Captcha Rule"

I also want to remove the lambda authorizer, because for the moment I don't want to mix these protections and stay focused on Captcha only.

Moreover, I was curious to see how Q would react to this suppression...

So, I used the exact same prompt again:

| > generate application

And as you can see, it detects that the lambda authorizer has been removed.

Then I deploy the code and I see that my lambda authorizer is removed as expected.

Let see if my Captcha is working by reloading my API URL.

First, I can see a web page telling me it wants me to verify I am human and ask me to select a group of similar pictures.

Then if I select the correct group it displays my API message

N.B. I had to make a small modification of the CDK code to trigger the Captcha right away (not after n calls over 5 minutes). This is where I am thinking, that I should update my rule to "always take the simplest solution" for example. The goal is to build this professional twin bit by bit until I get the best result each time.

From there, I let you imagine, that I could carry on exploring other solutions or go deeper into one of these.

But wait... what if I trigger Q automatically on each diagram updates?

After all, I can generate code from diagrams, and I always use the same prompt to generate a new version of my code with q chat:

| > generate application

But if I wish, I can use inline prompts with q chat, and accept all the proposals like this:

q chat --accept-all "generate application"

Let's automate this each time I save my diagram!

For that I install a watcher on my machine...

$> sudo apt install inotify-tools

...and I create a watcher script

while inotifywait -e modify diagram.drawio; do
    echo "File changed, executing command..."
    q chat --accept-all "generate application"
done

Now let's modify my diagram, and...that works!

Each time I modify my diagram I get a new version of my code, all I have to do is a 'Ctrl-S' to save my diagram.

There is a little constraint though. My q chat command doesn't exit at the end. So I have to do a 'Ctr-C' or 'Ctrl-D' to exit the chat and have my watcher ready to detect file changes again.

I thought this would be an issue, but if true in some situations, you might also want to execute some commands like ! cdk deploy in the chat, that can be handy then.

Conclusion

Expressing an architectures with diagrams is actually easier (at least for me) compared to using text. But a diagram alone is not always enough (at least for me again) to evaluate a solution.

Today, I think we are approaching something very interesting with the new Amazon Q Developer features and LLM capabilities.

I also still think I just scratched the surface. I know I can go much further with my "professional twin" for instance. I tried, for example, to ask Q to generate unit tests, which worked quite well, because it has also the capability to verify if these tests are working...and correct them if they aren't. I could put this in my rules as well, so it creates/updates these tests each time, because having automated tests is something important for me.

Finally, I am wondering if diagrams could be the future of prompting? At least for cloud architects?

It's too soon to answer, but what I'm sure of, is that this technique is useful for exploring and prototyping things quickly, create reusable components like CDK constructs, and probably more...

q developer

Olivier Lemaitre — Tue, 01 Apr 2025 16:09:49 +0000

Talk to your diagrams with Amazon Q Developer CLI

Olivier Lemaitre — Tue, 11 Mar 2025 11:00:41 +0000

CLI (Command Line Interface) is something I have been using a lot, and I prefer this to using GUI (Graphical User Interface) because it's way more flexible and powerful.

For decades, when you were working in a terminal you could already start a "conversation" with your computer by typing some commands that it would respond to (with the aws cli for example). That is so true that sometimes, non technical people seeing me working like that, have the feeling that I'm talking to the computer. However, traditional CLI is quite limited if you don't give the right inputs and it has a very low intelligence when it answers.

But today, with Amazon Q, you can combine the standard CLI with GenAI, which is super powerful and that's what I discovered while testing the new capabilities of Amazon Q Developer CLI agent with architecture diagrams.

The Prerequisites

There are already a lot on how to configure Amazon Q Developer desktop (not Q Developer CLI) for diagrams in this blog post: https://dev.to/welcloud-io/from-diagram-to-code-with-amazon-q-developer-2da4

But you can now add a new companion called Amazon Q for command line (Q CLI for simplicity here), which can be installed on Mac or Linux. Here is the procedure you can follow to install it:

https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-installing.html

N.B. : My installation did not integrate well right away with my VS Code terminal, so I had to use Q CLI in a separate shell window. I believe it's quite a challenge to build a solution that works everywhere and maybe my environment configuration is not standard.

If you encounter any issue you can also use these blog post:

https://dev.to/aws/the-essential-guide-to-installing-amazon-q-developer-cli-on-linux-headless-and-desktop-3bo7

https://dev.to/aws/the-essential-guide-to-installing-amazon-q-developer-cli-on-windows-lmh

Once installed, open a terminal, and type:

q chat

then you are good to go!

The sample application

I always use the same simple feedback application. This simple application records feedbacks and acknowledge they have been recorded by sending an email back to the user.

The code of this application is right there:

https://github.com/welcloud-io/wio-from-diagram-to-code-with-amazon-q-developer/tree/main/tutorials-starting-points/feedback-app-code

The drawio diagram of this application is right there:

https://github.com/welcloud-io/wio-from-diagram-to-code-with-amazon-q-developer/tree/main/tutorials-starting-points/feedback-app-diagram

Using the code and the diagram, you can reproduce what I explained in this blog post :)

N.B. This is generative AI, and results can be slightly different on your side.

1- Extract diagram from code

My first idea with the Q CLI was to extract an architecture diagram of the application from the code. So, I gave the prompt below to Amazon Q CLI:

create a file containing a mermaid diagram of this application

And not surprisingly (even if I am always surprised it works right away :)) it generates code, ask me to approve and creates a markdown (.md) file in my folder containing a mermaid diagram (diagram as code) that I can preview!

2- Update the diagram

Now that I have my application diagram I would like to change it and instead of sending an email, I want to send an SMS to the user.

So I ask Q CLI:

update this diagram so now I send an sms instead of an email

And it proposes an update, that I can accept or not.

Of course I accepted it by typing 'y' (i.e. yes) in the CLI and here is the result: it replaces the 'Email' by 'SMS' and the 'User Email' by 'User Phone'.

3- Generate code from diagram

Now I would like to generate code from a diagram. Even though it's quite common to sketch an architecture diagram before implementing it, the difference now, with GenAI, is that we can ask the generation of the infrastructure and application code from this diagram.

So I started with my (always the same) draw.io diagram in a folder and I gave Q CLI my (always the same) prompt.

can you generate application from the drawio diagram (I want the code of the lambdas to be written in python and the infrastructure as code with the python cdk v2)

And I obtained complete folder structure with all I need to deploy this app!

Note that I say "always the same", because this is exactly the prompt I used in a previous blog post (https://dev.to/welcloud-io/from-diagram-to-code-with-amazon-q-developer-2da4) about generating code from diagrams.

But, at the time, that was with Amazon Q Desktop with VS Code extension where I used the Q /dev agent or Q @workspace.

What I think is nice here, is that Q CLI combines, from my point of view, advantages of both /dev agent and the use of @workspace in VS Code Q chat extension.

Actually, /dev can create or update files in your folder (what Q Desktop + @workspace doesn't do) which reduces copy/paste work.

However, using @workspace, which also knows about your files in the folder, streams the response in the chat and you get an answer much faster the /dev.

In brief, Q CLI knows about the files in your folder (like /dev and @workspace), it will write/update files in your folder (no copy/pasting needed) and it will split and stream the response (faster answers with more interactions).

Note that I didn't test what was generated at this point, I made the assumption that it was working, let see later if I was too confident😊

4- Update and Improve my architecture

My architecture diagram is quite simple, and everything is contained into one single CDK app with CDK Level 2 "technical" Constructs like DynamoDB, SNS, ...

The Construct concept is very important in the CDK and the beauty is that you can create your own Constructs (let's say more business domain oriented, autonomous, Constructs).

So I will ask Q CLI to redraw my diagram with higher abstraction Constructs (this is where I have the feeling that I can talk to my diagram through Q CLI 😊), and I wrote this prompt:

can you update the drawio diagram file with well defined cdk constructs?

N.B. I discovered later that it's not the best prompt if you want to repeat that. Check the 'Epilogue' section at the end of this blog post to find a better one. I keep this one though, for the sake of the story.

Then it proposes some modifications, and I typed 'y' (yes) to accept them...

... and the result is quite impressive to me!

I obtained a new diagram with CDK Constructs tied into colored boxes and a diagram legend as you can see below.

Note that I didn't have to specify the color and legend stuff in my prompt, but I found it was a very good idea.

And, by the way, when you look at the result I guess you can better understand what I mean by a CDK Constructs 😊

But even better...

...Q CLI naturally proposed me to change my code with these CDK Constructs, so my code and diagram are in sync!

Of course, I accepted this proposal, and I got some new code proposed, what I also accepted.

Does this work when I deploy?

This is an important question to me, and I was worried that, with all the stuff that had been generated, I would find a lot of errors. After all, I generated code and changed it without testing it yet (what I wouldn't recommend as a professional, but I wanted to see how far we could go 😊)

So I deployed the CDK code and... I still cannot get used to it... it worked right away!

And when I clicked on the landing page link of my application here is what I got:

Did I ask for all this in my prompt? No, but the diagram contains enough information for Q to understand what the landing page could look like. That's crazy!

The infrastructure code worked right away, but to be honest, with this prompt I always get a little issue. When I click on the "Submit feedback" button once deployed for the fist time, the "record feedback" URL is not accessible. The reason is this URL is missing the api stage (i.e. /prod in my case), so I have one line of code to change in the landing page HTML code.

But, that's it... When I change that, and I submit feedback, I get this message below (again I didn't have to specify this in my prompt)

... and the feed back is recorded in my DynamoDB table!

Does it improve the quality of my architecture?

As I previously wrote, CDK Constructs can help you build better abstractions of your architecture, but this might not be something obvious to do. That's where, I believe, GenAI can give you ideas.

If I look at the structure of my resources with the first generation (with only technical Constructs), I get something like this.

If I look at the structure of my resource with the updated generation (with abstracted Constructs), I get more something like this:

We can see a difference (even thought it's not big). In the second hierarchy, our lambda functions are grouped together in their own Construct. The other components live in their own Construct.

Of course, it's far from perfect, that could be discussed, but it's a very good start with such a little effort (just one simple update prompt!).

We can start to see the power of constructs however.

For example, I can see there is a "FeedbackNotifications" Construct that was generated. That isolates this part (let's say this domain) of this architecture into it's own Construct.

I find this interesting and more explicit than "FeedbackTopic" from the first generation, which is specifically related to Amazon SNS (Simple Notification Service).

So now I can make this Construct evolve independently.

For example, I can find a better way to send the feedback confirmation to my user (while keeping SNS as the point of contact with the rest of the architecture). And I could extend this Construct with another type of notification, like an SMS notification with Amazon SNS, or use an even more sophisticated services like Amazon SES or Amazon Pinpoint.

I feel like I have (or more honestly Q CLI has) abstracted away this notification part and now, as it is decoupled, it can have it's own life, be tested independently, etc as explained in the Q CLI summary 😊

Conclusion

I could carry on talking to my diagram, and maybe ask more things. That was possible with /dev or VS Code Q extension + @workspace, however I feel like we could go a step further with the Q CLI, and I am keen to carry on the experimentation and use it in my every day job!

The only thing I regret, which is a detail, but however important, is that it does not integrate well with my VS Code terminal yet (probably due to my VS Code & O.S. configuration) so I have to use an external terminal to execute the Q CLI. But, once this will be solved, I feel like it will be a terrific tool!

Epilogue

I wanted to write this epilogue, because a few days later I could easily configure my VS Code terminal with Q CLI, and that works well😊

But, I retried my prompts and I didn't get always the same kind of response and behavior. Basically, GenAI is build on probability and I think that, for my first try with Q CLI, I was lucky😊

Anyway, I modified one prompt and now I get very similar results each time (even if, again, GenAI is still not deterministic). And by the way, after a lot of trials I haven't reached my BuilderId free tier yet. The free tier seems quite generous so far!

So, if you want to try what is in this blog post, you should first ask (and I didn't change that):

can you generate application from the drawio diagram (I want the code of the lambdas to be written in python and the infrastructure as code with the python cdk v2)

...and then ask (this is the prompt I changed):

modify the drawio diagram to split the architecture diagram into well defined cdk construts (use colors and legend)

That proves prompt engineering is an important part with GenAI!

Here is also a YouTube video that shows this in action 👉https://www.youtube.com/watch?v=D6cYFDoX1Es

Document, Test & Review your code with Amazon Q Developer

Olivier Lemaitre — Tue, 31 Dec 2024 10:49:56 +0000

This year, at re:Invent 2024, there were a few announcements about Amazon Q developer. Among these announcements, three new agents looked interesting to me.

The first agent generates your documentation (/doc), the second agent generates your unit tests (/test) and the third agent review your code vulnerabilities (/review).

They look interesting because, even if crucial in software projects, these tasks are often overlooked. And I guess you would agree that writing documentation can be tedious, writing unit tests can be discouraging, and reviewing vulnerabilities can require too much expertise...

So, in this blog post, I evaluated those agents.

For that, I used this simple feedback application, which records feedbacks and acknowledge they have been received by sending an email. Here is its architecture:

The code I used is right there: https://github.com/welcloud-io/wio-doc-test-review-with-amazon-q-developer. Everything I demo here can be reproduced from it.

N.B. This is generative AI and results can be slightly different on your side.

/doc to document your application

I started by creating a README.md file that wasn't existing yet in my folder.

I first choose the /doc agent in the Amazon Q Chat in my IDE (you can also see the project tree that I want to document in the terminal)

And then I click on "Create a Readme" button

Q inspect your project and once done, I accept the generated README.md, which will be created in my folder.

The result is not bad, and when I verify what has been generated... that seems correct. I don't really see any correction to apply. At least, these are very small, like adding more arguments to the CDK commands. However compared to the time I saved compared to writing this documentation on my own, it's negligible.

However, I am a bit disappointed with the diagrams and I would like to add more of them.

Lets start a new documentation task:

Then, I don't create, but update the existing readme file...

...with a specific change

And I ask Q

add sequence diagram

And it naturally adds a mermaid sequence diagram, after the right section (the Data Flow section)

I accept this update, and I preview the diagram. The result is not bad at all once again, at least better than the original data flow for me.

I think I could add more things, but so far I understand that this agent has to be used in an iterative process. The documentation will not be generated in one go.

/test to test your code

Now I want to add unit tests to my code, so I will use the new /test agent.

For that I must open the file which contains the code I want to test, in my case the 'send_feedback.py'.

It proposes to specify a function, but since I just have only one function...

...I directly press enter.

After a few seconds I can see the test suite, that will be placed in a new generated test file.

I accept the tests...and I run them.

Very quickly, after just a few modifications, they are all running (7 tests, 130 lines of code). Again, the time to fix things, compared to the time I would have needed to write these tests on my own is negligible.

Now I will intentionally introduce an error and see if it's covered (therefore detected) by my new test suite. So, I select the feedback field in my table update instruction...

...and remove it from the code

I run my test suite again, and here is the result: the missing field has been detected.

So now I should be able to refactor my code safely. Pretty interesting!

N.B. I tried to use /test agent on my CDK code, but the result was not as good as when I generate it with my own prompt in the chat.

/review to detect code issues

Then, before committing I want to review my code, so I will use the /review agent

I will choose review workspace to scan all my files

Quickly, I get all the issues of my code. There is no critical issue, but one High level issue in my CDK code.

It detected there is no encryption of my DynamoDB database, and spots the lines of code that are involved

By clicking on the search icon of the issue, I can view the details of this weakness (CWE).

I can also ignore this issue, or ask Q to fix it.

I want to fix it. I click on the "Generate Fix" button, I take a look at the suggested code, and accept it

My code is updated, and the issue disappears from my list :)

I'm now more confident about deploying my code.

As a next step, I can rerun the tests previously generated by /test agent, or update my test suite with new tests. I can also use /doc agent to update my readme file with what was added since last generation. That could be part of a workflow, that will increase the quality of my project :)

Conclusion

Personally, I am not really looking for more agents with Amazon Q Developer. I believe we can manage a lot of things with what exists already. I don't want to feel overwhelmed, not knowing what to choose.

However, I think that specialized, well defined agents like /doc, /test, /review, can incredibly increase the quality of your work and save time.

They can be part of a software design workflow that you will create or re-invent :)

Overcome startup challenges with Amazon Q Developer

Olivier Lemaitre — Wed, 27 Nov 2024 23:57:24 +0000

I like working for startups. The main reason it that you create new things. Things that haven't been created before. The other reason is that you have a lot of freedom in your technical choices and you can choose the tools that are the most appropriate for the situation (which is not always the case in big companies).

However, working for startups brings many challenges. The main one is that you want to move fast. In software that often means you have to reduce code quality. That will slow you down over time, but...you have to move fast.

Another challenge is that you don't know your domain well and the problem to solve. Actually, you want to solve a problem, but you can discover that your users want to solve another problem with your product. Therefore, you might have to redesign things.

How Amazon Q Developer can help?

Amazon Q Developer is a GenAI Coding assistant, provided by AWS, which generates code from a natural language description, but it's also used for code explanation, refactoring, optimizing, securing, ...

As an architect, it's also a very good "architecting" assistant. It can generate code from a diagram but also a diagram from the code, which for me is a great new capability.

As of today, my intuition makes me feel it's a super powerful tool to increase code quality and ease software design evolution.

That's what I try to demonstrate in this article.

The context

I recently worked for a very small startup, which needed to analyse videos and especially audios from these videos.

This doesn't sound difficult today, but it's not trivial to implement. Especially when you start from scratch and when the application will be used by real users one week later!

By chance the front end was already developed with a No Code solution, however a complete backend had to be built on AWS.

The Architecture starting point

When you start a project, people often come with a design of the solution and we can have the feeling that if you follow that solution, everything will be working well.

That never happens in software!

Here a simplified representation of the AWS solution that I was proposed before I started the project.

That does not look very complicated, but I did not want to fall into a too early design trap, I decided to start with a very simple AWS backend using: serverless technologies, a lambda-lith and the AWS CDK.

The Foundational Architectural Decisions

Why serverless?

AWS pioneered serverless technologies, and it's not only lambda functions. For instance, Amazon S3 (the AWS object storage service) is considered as serverless, because you do not manage any server.

Not only you manage less servers, but you also manage less availability, less security, less scalability, less network, ... all these things are AWS's problems.

That makes it an ideal choice for startups which want to move fast.

Why a lambda-lith?

Building a distributed architecture based on events can be hard, but also difficult to maintain, debug and evolve.

I like the idea of "Monolith First", popularized by Martin Fowler, and I wanted to apply this to my serverless architecture, because I think it brings the same benefits.

So, I started to write the algorithm in one lambda only, instead of multiple lambdas.

Why the AWS CDK?

The CDK (Cloud Development Kit), is a library that helps you build infrastructure as code with imperative/Turing complete languages like python, java,... instead of declarative languages like Yaml, Json, ...

That brings more possibilities, and you can build things much faster with more safety because CDK components "encapsulate" multiple low level components and best practices.

Among many CDK benefits, I do not have the feeling that I spend more time playing with IAM Policies to apply least privilege principle than building my architecture.

For example, when I write

...
lambda.grant_read(s3_bucket)
...

This simple line of code will handle all the policy generation with just enough privileges. That saves a lot of time and brings more serenity.

The quick and dirty phase

The main architecture constraint was the performance of the analysis. Therefore, I first needed to create a workflow that would be realistic enough to prove the choices were the best regarding performance. I didn't want to discover the wrong choices were made after one week of work!

That's where lambda-lith is interesting because you don't focus on distribution first, you just concentrate an measure what is interesting for you. I know that distribution can increase performance, but do we need it now? I think that the old adage: "Premature performance is the root of all evil" is still relevant in the cloud!

This is where I started to use Q, and asked it to help me create my Infrastructure with the CDK V2.

@workspace generate CDK v2 template from the draw.io diagram

I chose to use a draw.io diagram for that, because it is less text to write and give to Amazon Q. More on that in my previous article: https://dev.to/welcloud-io/from-diagram-to-code-with-amazon-q-developer-2da4

Since I had a bit of algorithm to develop inside the lambdalith, I asked Amazon Q to help me.

Then I tested the entire workflow and I proved we were under the expected duration.

Rewrite almost all code!

When the quick and dirty phase was finished and that I could prove performance was not an issue with this architecture I decided to rewrite most of my lambda code!!!

Remember I produced quick and dirty code, and leaving this code as is, was risky. After a just few days, it could have been more and more difficult to maintain or change because it's hard to code fast and keep good quality (at least it's hard for me).

But actually... I didn't rewrite the code myself... I asked Q to rewrite it!

I did it in 3 steps:

Generate the sequence diagram from existing code
Generate new code from the diagram
Generate unit tests from code.

Generate the sequence diagram from existing code

First, I asked Q to create sequence diagram from my quick & dirty code.

It was not perfect I had to change a few things to the sequence, but not that much.

The diagram can primarily be used as a documentation. But, it can also be used for generating new things... like code and unit tests.

So, let's do it!

Generate new code from sequence diagram

It's not very complicated to do, you just asked Q:

Generate code from that mermaid diagram
[mermaid diagram as code]

The benefit for me is that Amazon Q is a better developer than I am, and I can see a better written and a better organized code very quickly.

Generate unit tests from code

Unit tests are a simple concept, they are automated tests that you execute to make sure your code is still working after you change it.

This is often something we wish we had. However, behind an apparent simplicity it's not easy to write them or to master techniques like TDD (Test Driven Development). Therefore, these tests are often overlooked.

But with GenAI, you have no excuse. Generating them is easy with Q:

write unit tests for that code

And Q generated a lot of tests (4 files in total and ~ 250 lines of tests)

Then I executed the generated tests. Not every test was working right away, but it took less than 1/2 h to do the fixes and make them all pass!

Some tests are very interesting, for example I had to poll a third party provider, and Q generated a test to evaluate the timeout case, when after a certain number of polls you stop calling the third party provider and raise an error.

That's something I wouldn't have thought about, or at least it would have taken me more time to write. And it's important because if you do not have a timeout mechanism you will consume lots of resources for probably nothing.

Another interesting test is the high level test (the lambda handler test), which execute my entire workflow to detect general errors.

I also completed manually this test suite with a simple integration "end to end" test, where I could put an audio file in my input bucket and verify the analysis in the output bucket, again with Amazon Q's help.

So, now, my architecture looks like this:

The feedback loop & code refactoring

With test harnesses you can put in place a very short feedback loop. Therefore, every change that breaks something in the workflow will be detected immediately and you can roll it back right away.

What's the advantage?

First, in the software development process, when you discover that something is broken one day or even one hour after the mistake was made, it's often much harder to fix it compared to fixing it when it was just introduced. Unit tests are a way to move faster.

Second, without test harnesses, even simple things like renaming objects in your code, and that can happen quite often when you don't know your domain well, can become very difficult, because you fear the application will break. So you don't take the risk and leave inconsistent names, making your production harder to understand and maintain. Unit tests are a way to redesign things with more confidence.

Setting up your environment for a short feedback loop

One trick I use is, each time I save a file, all my test suite is executed. With pytest I just had to install this plugin:

pip install pytest-xdist

So, now each time I modify a file, it runs all my tests automatically, each time I make a mistake I roll back immediately.

Here is an example of my test suite running when everything is green:

Here is an example when it breaks, and how it spots the issue:

The feedback is very quick, and that's very comfortable.

Ask Amazon Q Inline chat to refactor your code

From my point of you, refactoring is at the heart of software development. It's very important, but almost never practiced.

Refactoring is a technique where you improve the quality/evolvability of your code, without changing its behavior.

Refactoring is not trivial, it takes time and requires reflection, but today you have a very good friend to help you out: Amazon Q Developer!

Q Developer has an impressive feature that I use to refactor my code: Q Inline Chat.

For example, I simply select the chunk of my code I want to refactor, then I press Ctrl-I, and type "refactor" in the dialog box:

It proposes a refactoring that I can accept or reject. In this screenshot below, what is in green is the new code, what is in red if the code that will be removed!

That's what I like with refactoring, your code becomes much clearer, easier to understand and maintain.

Now that the code is refactored I can check if my tests are still passing.

If I am satisfied, I commit the update and even deploy it into production if I want.

Amazon Q and test harnesses is a good combination to refactor your code within minutes, but I experimented another technique using Q and tests I found very interesting. Let's explain it.

Solve issues with Amazon Q test generation

During this project, I had an issue that was hard to fix for me.

I had two pieces of code that were supposed to do the same thing, but one was working and the other wasn't. And I couldn't see the differences.

This was a new piece of code that was not covered previous tests.

So, I first created a test for the function that was working using Q:

Then, I launched the tests against my working code (the one I gave to Q), to make sure the test was green.

Then, I replaced my working code with the non working code in my function, and I ran the test again.

The test was red as expected, and it showed me differences in an input data format! In fact, this input data format was slightly different between the two versions of the code.

Then, I fixed it, and... here we are... this error will never happen again! Or at least it will be detected very soon.

The final architecture

After a few iterations and many modifications (safeguarded by tests), I landed with a final architecture.

Here is the (too early) solution architecture I was proposed first:

Here is what I really started with:

From there, I used Q to generate the infrastructure, the code and the unit tests. Then I refactored the code, solved issues, still using Q.

By the way, we discovered the frontend could not extract audios as expected (which was not in the 'too early' architecture).

So I introduced AWS Media converter (another serverless service) in the architecture, and here is what I ended up with:

This architecture was built on time, it was production ready and has been used by real users!

That was a challenge I could overcome while keeping a good quality and evolvability thanks to my developing/architecting assistant. Maybe that will be normality in the near future, but today... it blows my mind!

Conclusion

This project was ideal to demonstrate the benefits of Amazon Q Developer to kickstart new and innovative projects with good practices.

With Amazon Q Developer, I could rewrite dirty code, add unit tests and put in place a short feedback loop. I also used it to refactor my code in order to keep a good quality and allow evolutionary design. I don't think that would have been possible without it in such a short amount of time.

Of course, I don't think we can overcome all startup challenges with Amazon Q Developer, there are many other dimensions. I am also wondering if that could apply each time or to bigger projects. I don't have enough experience with it yet. But again, that looks very promising!

Links
https://martinfowler.com/bliki/MonolithFirst.html

From Diagram to Code with Amazon Q Developer

Olivier Lemaitre — Thu, 31 Oct 2024 12:58:41 +0000

Architecting a solution is not easy, and we need multiple tools to do it right. Among these tools, diagrams is an important one.

Diagrams can be used to understand something that has been built or to envision what will be built.

Whatever the situation, drawing them is a difficult exercise that takes time.

The good news is that today, with GenAI, it becomes easier to build a diagram from the code, but much more impressive, we can generate an application from a simple diagram.

In this blog post I demonstrate how to do this with a small project, and the result is already very promising.

You can replay this example on your side by following the steps below. Note that since it's GenAI, the result might look a bit different on your side and you might not get the same fixes to apply. But, give it a try, it really worth it if you like software design and architecture.

Prerequisites if you want to try it

Install VS Code:

https://code.visualstudio.com/download

Install Amazon Q Developer in VS Code:

https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/q-in-IDE-setup.html#setup-vscode

Enable workspace with Q:

https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/workspace-context.html

Install mermaid extension in VS Code:

https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid

Install Draw.io Integration extension in VS Code
https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio

Install AWS CDK (not necessary if you don't want to deploy the application, but only see how to generate code from a diagram):

https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html

Install AWS SAM (not necessary, only if you want to to test the original application)

https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html

GitHub repository & Videos

This repo contains the code and diagram you can start with. The first step will be to extract a diagram from this application code and later recreate a new application code from the diagram.

git clone https://github.com/welcloud-io/wio-from-diagram-to-code-with-amazon-q-developer

The purpose of this application is to record feedbacks from a user and send feedback acknowledgement to the user mailbox.

The Infrastructure as Code is built with AWS SAM here, so you can test it by executing _deploy.sh in the feedback-app-project-original directory.

You can also find some demos I created in these videos: https://www.youtube.com/playlist?list=PL7uUliWSzuvF0GS9jpaFGQxLKGC0CC2vq

Amazon Q, From Code to Diagram

So, the first step will be to generate a diagram from the code (I mean from all the files in my project). To do this you need Amazon Q to be aware of all the existing files in your folder. This is why you have to activate @workspace, which will index all your files so they can be retrieved when you ask a question in the chat.

The secret is that Q will not draw a diagram (like we would do on a piece of paper), I will ask Q to generate a diagram with the mermaid diagram as code language. So, my diagram will be a text that I can modify in a code editor and that I can reuse as a source for multiple tools. In this case I will use it later to rebuild my project.

I tested multiple types of diagram generation, but I guess we can do much more, and better with more crafted prompts.

So, open the feedback-app-project-original folder in VS Code (File/Open Folder... menu) and follow the prompts...

Example 1: Application Diagram

Here is the prompt I used in Amazon Q developer VS Code Chat:

@workspace can you generate a mermaid diagram of my application

It took less than a minute to generate the diagram of the application.

Then I use the mermaid viewer in VS Code and... here is the result, which is correct right away.

Example 2: UML Sequence Diagram

Here is the prompt I used in Amazon Q developer VS Code Chat:

@workspace can you generate a mermaid sequence diagram of the application

Example 3: UML Class Diagram

Here is the prompt I used in Amazon Q developer VS Code Chat:

@workspace can you generate a mermaid class diagram of this application

Amazon Q, from Diagram to Code

The most impressive part is to build the entire application from the diagram itself.

I decided to start from an empty folder in VS code, so please create a new folder and open it using 'File/Open folder...' menu if you want to reproduce the example, so Q is not influenced by any context.

Step 1: Code Generation

Here is the prompt I used in Amazon Q developer VS Code Chat:

/dev can you generate application files from this mermaid diagram (I want the code of the lambdas to be written in python and the infrastructure as code with the python cdk v2)
graph TD
A[User] -->|HTTP GET /| B[API Gateway]
B -->|Invoke| C[Landing Page Function]
C -->|Return HTML| B
B -->|Return HTML| A
A -->|HTTP POST /feedbacks| B
B -->|Invoke| D[Send Feedback Function]
D -->|Write| E[(DynamoDB Table)]
D -->|Publish| F[SNS Topic]
F -->|Send Email| G[User Email]
subgraph AWS Cloud
B
C
D
E
F
end

I use the /dev agent which is an Amazon Q agent that will analyse the existing files and update them (but we have none in our case) or generate new files in our folder (that's what we want).

Note that the prompt is very short compared to what will be generated, this is where I am the most amazed, I can still not believe it worked!

Now Q starts generating code and validates that it fits the diagrams that was specified in the prompt (I guess it does a reverse engineering of its own generated code for that).

I now get code suggestions containing five new files in a folder tree, but these are not placed in my empty folder yet, I have to accept the suggestions.

It took one minute or so to get to this result, and when I click on 'Accept code' it takes about one second to create the file structure in my former empty folder.

Step 2: Test and Fix

I start first to install the requirements and make the cdk deployment.

$> pip install -r requirements.txt 
$> cdk deploy --app "python3 app.py"

And it starts to deploy 22 resources...

I thought I would have had to fix something here, but it worked RIGHT AWAY!!!

So let's go to Amazon API Gateway and copy paste my landing page endpoint in my web browser address bar to see if it works.

And this is what I get, and it works right away as well!!!

So, let's submit a first feedback now...

But this time I have a 403 error (the url access is not allowed, a common error when in fact the url does not exist in API Gateway)

Obviously the stage name (/prod in my case) is missing in the url, so let's add it, and redeploy.

I do another test, that solved my problem, but now I have a 500 error (a server side error), with this message as a response:

It turns out that the lambda function is supposed to receive an event, and this event should be in a json format.

So I ask Q to change the code of my landing page in order to send a json document instead of an HTML Form format with a new prompt in VS Code Chat. I update my code, redeploy and make a new test.

I want my feedback data to be sent as a json document to the '/prod/feebacks' endpoint with a field called "feedback" containing the feedback value typed into the html form

Ok, that works now!

I have NO error when I send some feedback, and the API call returns a 200 status

So, let's got to the DynamoDB (which has been created by the CDK code) to see if my feedback has been recorded

And boom! It is there!

I am also supposed to receive a email to acknowledge the feedback has been recorded, so I will change the destination email which contains a default value in the CDK template (again generated earlier) and I redeploy.

My user has been added and is now pending for confirmation

I confirm my subscription in my mailbox and I send a new feedback

And here is what I get straight away in my mail box!

I am really impressed so far, but...

Step 3: Let's push it a bit further

Mermaid is nice, but maybe we want to draw our diagram with a mouse and then generate the associated code...

So, I tested the idea, I took a draw.io diagram of my application, that I exported in an XML format (and a png format to display it in my IDE).

Then I created an empty folder where I put my app.drawio.xml file and I ask Q:

/dev generate application (code+infrastructure)

And, that's amazing, it has enough information to generate my application, and this time it works right away, no need to fix anything!

Note that since I do not specify anything more, Amazon Q chooses the tools, in this case python and SAM. Not sure it would choose the same for you if you try this :)

But wait..., can I generate a draw.io diagram from my code?

Let's try it...

First I remove the app.drawio.xml file to avoid Q to be influenced by it in the context and then I type:

@workspace can you generate a draw.io diagram in an xml format of this application (I want to use AWS 2024 Icons, lines should be orthogonal, dataflow from up to bottom)

And I copy/paste the generated XML document in draw.io (https://app.diagrams.net/), and again almost nothing to change!

Step 4: Integrate Draw.io in VS Code

Finally I asked myself, does it exist a draw.io extension in VS Code, so I can directly edit my diagrams in my IDE, and...that exits!

It's called 'Draw.io Integration' and it seems to work quite well. So, I redrew my diagram in VS Code directly.

The only trick that I had to apply was to change the editor file extension association, by default '.drawio', to 'drawio.xml'.

That's because Amazon Q @workspace doesn't take the '.drawio' extension into account, but only the well known text base file extensions like .xml, .yaml, .py, ....

To make this work, go to 'File > Preferences > Settings', search for 'editorasso' setting and add the association item (*.drawio.xml => hediet.vscode-drawio-text)

Now I can create my diagrams directly in VS Code using 'drawio' and then ask Q to generate my application :)

That's it, but I think I could carry on this blog post with many other stuff I have in mind although it's already amazing to me!

Conclusion

Diagrams can be a powerful tool to convey a vision, document and understand the structure of your software architecture.

With today GenAI tools, this is made easier, and Amazon Q coding assistant can really help you.

But, what is really new and powerful to me is that you can scaffold an entire project from your diagram.

I am not sure it's MDA (Model Driven Architecture) reshaped yet, because the problem I guess, is that if you want to make a change to your project you will have to change the diagram and regenerate things, I don't think GenAI is deterministic enough for that today (but I will try).

However, I think, it's already good for prototyping or rewriting the same small project with different technologies. For example, here I ask to use python in my code and the CDK for the IaC, but I could change my mind and use javascript and pulumi to see the differences and make my choice from there.

There would be a lot more to say about this experience, and I think it is a very simple trial with many things that would need to be improved in order to be production ready, but it's already very promising.

I think we can do much better with more crafted prompts, and that's surely what I will try to do in the next couple of weeks. It was so much fun!