DEV Community: Mariano Álvarez 🇨🇷

Baseline Web Features You Can Safely Use Today to Boost Performance

Mariano Álvarez 🇨🇷 — Thu, 01 Jan 2026 01:29:18 +0000

Performance optimization can feel like a gamble. You find an amazing CSS property or API that could shave hundreds of milliseconds off your load time, but then you check browser support and… it's a sea of red on Can I Use. So you give up and stick with the same old techniques.

Here's the thing: there's a growing list of powerful performance features that are now Baseline Widely Available. That means they've been supported across all major browsers for at least 30 months. You can use them today without worrying about compatibility.

Let me show you four that should be in your toolkit.

What Does "Baseline" Mean?

Before we dive in, quick context: Baseline is a compatibility initiative from the Web Platform that identifies when features are safe to use across popular browsers. A feature becomes Baseline Widely Available after it's been supported in Chrome, Edge, Firefox, and Safari for 30+ months.

Think of it as a green light for production use. No polyfills needed, no edge case workarounds—just reliable browser support.

1. content-visibility: Skip Rendering Work You Don't Need

The content-visibility CSS property lets browsers skip rendering work—layout, painting, all of it—for offscreen content. This is particularly powerful for long pages with lots of DOM elements.

Browser Support

Chrome/Edge: 85+
Firefox: 125+
Safari: 18+
Status: Baseline Newly available (September 2025)

How It Works

.article-section {
  content-visibility: auto;
  contain-intrinsic-size: 1000px;
}

The auto value tells the browser to skip rendering when the element is offscreen. The contain-intrinsic-size acts as a placeholder to prevent layout shifts—it's essentially telling the browser "assume this element is about 1000px tall until you actually render it."

If you're building something like an infinite scroller, use the auto keyword with contain-intrinsic-size:

.feed-item {
  content-visibility: auto;
  contain-intrinsic-size: auto 500px;
}

The auto keyword makes the browser remember the last rendered size, which is perfect for content that might be scrolled back into view.

Real Performance Gains

In a travel blog example from web.dev, applying content-visibility: auto reduced initial rendering time from 232ms to 30ms—a 7x improvement. That's the kind of boost that directly impacts Interaction to Next Paint (INP).

Important Considerations

Content remains searchable and accessible (unlike visibility: hidden)
Avoid calling DOM APIs that force layout on skipped subtrees
Use aria-hidden="true" on landmark elements if you're getting accessibility tree clutter
Works best on chunked content sections (articles, feed items, product cards)

2. AVIF: Next-Gen Image Compression

AVIF is an image format built on the AV1 video codec. It delivers greater than 50% file size savings compared to JPEG while maintaining the same visual quality. If you're trying to optimize Largest Contentful Paint (LCP), this one's a game-changer.

Browser Support

Chrome: 85+
Edge: 93+
Firefox: 93+
Safari: 16+
Status: Baseline Widely Available

Why It Matters

Smaller images = faster downloads = better LCP scores. AVIF also supports High Dynamic Range, Wide Color Gamut, and progressive decoding. Think of it as the image format designed for modern web performance needs.

Implementation

The simplest approach uses the <picture> element with fallbacks:

<picture>
  <source srcset="hero-image.avif" type="image/avif">
  <source srcset="hero-image.webp" type="image/webp">
  <img src="hero-image.jpg" alt="Hero image" loading="lazy">
</picture>

Browsers try formats from top to bottom. AVIF-capable browsers get the smallest file, others fall back to WebP or JPEG.

Encoding Considerations

If you're encoding AVIF images yourself using avifenc:

avifenc --cq-level 23 --speed 6 --jobs 8 input.jpg output.avif

cq-level: Quality setting (0-63, lower = higher quality). Start around 23-28 for photos.
--speed: Encoding speed (0-10, default 6). Lower = slower encoding but better compression.
--jobs: Multi-threading. Using 8 threads gives roughly 5x speedup.

Practical Advice

Use lossy encoding for photographs, lossless for line art
Experiment with quality settings—sometimes cq-level 28 looks identical to cq-level 23 but saves another 20%
Consider image CDNs (Cloudinary, Imgix) if you don't want to manage encoding yourself
Always provide fallbacks for older browsers

3. Module Preload: Fix Dependency Waterfalls

If you're shipping ES modules in production, you've probably noticed dependency waterfalls. The browser fetches your entry module, parses it, discovers imports, fetches those, discovers more imports… it's roundtrip city.

<link rel="modulepreload"> solves this by letting you declaratively tell the browser to fetch and compile modules ahead of time.

Browser Support

Chrome: 66+
Edge: 79+
Firefox: 115+
Safari: 17+
Status: Baseline Widely Available

Why Standard Preload Doesn't Work

You might think <link rel="preload" as="script"> would handle this. It doesn't, because:

Modules use an omit credentials mode that standard preload doesn't support
The browser doesn't know to parse/compile the file as a module
Chrome's V8 engine handles module compilation differently than regular scripts

How to Use It

<head>
  <!-- Preload your critical modules -->
  <link rel="modulepreload" href="/js/app.mjs">
  <link rel="modulepreload" href="/js/router.mjs">
  <link rel="modulepreload" href="/js/components.mjs">
</head>

<script type="module" src="/js/app.mjs"></script>

The browser fetches all three modules in parallel, parses and compiles them immediately, then executes when needed. No more dependency waterfalls.

When to Use It

Module preload is most effective when:

You have deep module dependency chains (3+ levels)
You're seeing performance issues from roundtrip delays
Your application has a clear critical path of modules

For shallow dependency trees (1-2 levels), the overhead might not be worth it. Profile first, optimize second.

A Word of Caution

Listing every module defeats the purpose. Focus on the critical path—the modules absolutely needed for initial render. Think of it like this:

<!-- Good: Critical path only -->
<link rel="modulepreload" href="/js/app.mjs">
<link rel="modulepreload" href="/js/critical-component.mjs">

<!-- Bad: Everything and the kitchen sink -->
<link rel="modulepreload" href="/js/utils.mjs">
<link rel="modulepreload" href="/js/helpers.mjs">
<link rel="modulepreload" href="/js/random-thing-used-once.mjs">

4. Server-Timing: Surface Backend Performance Metrics

The Server-Timing HTTP header lets you expose backend performance metrics directly in the browser's DevTools and JavaScript. It's like having a window into your server's performance for every request.

Browser Support

Chrome: 65+
Edge: 79+
Firefox: 61+
Safari: 16.4+
Status: Baseline Widely Available (March 2023)

What You Can Track

Database queries, cache hits/misses, API calls, CPU time, file system access—basically any server-side operation you want visibility into.

Basic Implementation

On the server, add timing headers to your responses:

Server-Timing: db;dur=53.2;desc="Database query"
Server-Timing: cache;dur=2.1;desc="Cache read"
Server-Timing: api;dur=127.8;desc="External API call"

Or as a single header with multiple metrics:

Server-Timing: db;dur=53.2;desc="Database", cache;dur=2.1;desc="Cache", api;dur=127.8;desc="API call"

Node.js Example

app.use((req, res, next) => {
  const start = Date.now();

  // Track database time
  const dbStart = Date.now();
  await db.query('SELECT * FROM users WHERE id = ?', [userId]);
  const dbDuration = Date.now() - dbStart;

  // Track cache time
  const cacheStart = Date.now();
  const cached = await cache.get(cacheKey);
  const cacheDuration = Date.now() - cacheStart;

  // Set Server-Timing header
  res.setHeader('Server-Timing', `
    db;dur=${dbDuration};desc="User query",
    cache;dur=${cacheDuration};desc="Cache check",
    total;dur=${Date.now() - start};desc="Total"
  `.trim().replace(/\s+/g, ' '));

  next();
});

Accessing in JavaScript

// Get timing data for all resources
const resources = performance.getEntriesByType('resource');

resources.forEach(entry => {
  entry.serverTiming?.forEach(metric => {
    console.log(`${metric.name}: ${metric.duration}ms - ${metric.description}`);
  });
});

// Example output:
// db: 53.2ms - User query
// cache: 2.1ms - Cache check
// total: 178.4ms - Total

DevTools Integration

The best part? These metrics show up automatically in Chrome DevTools under the Timing tab for each request. No special configuration needed—just set the header and open DevTools.

Security Considerations

Be thoughtful about what you expose:

Avoid revealing sensitive infrastructure details
Consider exposing detailed metrics only to authenticated users
Use Timing-Allow-Origin header to control cross-origin access
Don't expose internal service names or database schemas

For public APIs, stick to high-level metrics:

Server-Timing: total;dur=245;desc="Processing time"

For internal tools or authenticated users, go wild with detail:

Server-Timing: db-users;dur=23;desc="Users table", db-posts;dur=45;desc="Posts table", redis;dur=3;desc="Cache", s3;dur=89;desc="Asset storage"

Putting It All Together

Here's what a performance-optimized page might look like using all four features:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>High Performance Page</title>

  <!-- Module preload for critical JavaScript -->
  <link rel="modulepreload" href="/js/app.mjs">
  <link rel="modulepreload" href="/js/router.mjs">

  <style>
    /* content-visibility for long sections */
    .article-section {
      content-visibility: auto;
      contain-intrinsic-size: auto 800px;
    }
  </style>
</head>
<body>
  <!-- AVIF images with fallbacks -->
  <picture>
    <source srcset="hero.avif" type="image/avif">
    <source srcset="hero.webp" type="image/webp">
    <img src="hero.jpg" alt="Hero" fetchpriority="high">
  </picture>

  <main>
    <section class="article-section">
      <!-- Content here -->
    </section>
    <section class="article-section">
      <!-- More content -->
    </section>
  </main>

  <script type="module" src="/js/app.mjs"></script>

  <script type="module">
    // Log server timing metrics
    performance.getEntriesByType('navigation').forEach(entry => {
      entry.serverTiming?.forEach(metric => {
        console.log(`Server: ${metric.name} took ${metric.duration}ms`);
      });
    });
  </script>
</body>
</html>

And on the server:

// Express.js example
app.use((req, res, next) => {
  const timings = [];

  // Your request handling with timing tracking...

  res.setHeader('Server-Timing', timings.join(', '));
  next();
});

The Bottom Line

These four features are production-ready today. They're not experimental, they're not behind flags, and you don't need polyfills. They're just solid, well-supported tools that can genuinely improve your site's performance.

content-visibility: Reduce rendering work for offscreen content
AVIF: Cut image file sizes in half
Module preload: Eliminate dependency waterfalls
Server-Timing: Surface backend performance metrics

The combination has noticeably improved Core Web Vitals scores—particularly LCP and INP.

Start with one. Add AVIF support to your hero images. Try content-visibility on a long article page. Add module preload to your critical JavaScript. The beauty of Baseline features is you can adopt them incrementally without worrying about breaking browsers.

Want to dive deeper? Check out the official documentation:

If you found this useful, a like or share helps others discover it. And if you've used any of these features in production, I'd love to hear about your experience in the comments.

Gemini, Local and Free with Chrome and Angular

Mariano Álvarez 🇨🇷 — Tue, 30 Dec 2025 04:00:16 +0000

AI is impressive, but it is also expensive. In today’s landscape, developers need smarter ways to add AI-powered features without burning through budgets. Fortunately, the Chrome team has been working on a set of on-device AI APIs that let you run models locally, trained for specific tasks, at zero inference cost.

Some of the available APIs include:

Language API: Detects the language of a given text
Translation API: Translates text from one language to another
Prompt API: Accepts free-form prompts for structured outputs
Summarization API: Condenses long text into concise summaries

In this post, I’ll show how you can take advantage of these APIs to add genuinely useful features without paying for tokens.

One thing I find particularly interesting is how Google Search now often gives you an AI-generated summary or even a direct answer. Sometimes you just want the takeaway, not the entire article. That idea is exactly what we’re going to replicate here.

The goal is simple: build a small piece of logic that generates a TL;DR (too long to read) section in bullet points for a blog post, so readers can instantly understand what it’s about.

Getting Started

Make sure you are running the latest version of Chrome. Older versions may not include the most recent on-device models.

Next, enable the following flags and restart Chrome:

chrome://flags/#optimization-guide-on-device-model
chrome://flags/#prompt-api-for-gemini-nano-multimodal-input

Once that’s done, install the models by running:

const session = await LanguageModel.create({
  monitor(m) {
    m.addEventListener('downloadprogress', (e) => {
      console.log(`Downloaded ${e.loaded * 100}%`);
    });
  },
});

const summarizer = await Summarizer.create({
  monitor(m) {
    m.addEventListener('downloadprogress', (e) => {
      console.log(`Downloaded ${e.loaded * 100}%`);
    });
  }
});

When the download reaches 100%, you are ready to use the APIs.

Implementation

We’ll use Angular for the implementation. If you don’t already have it set up:

Install the Angular CLI: npm install -g @angular/cli
Navigate to your desired folder and run: ng new <name-project>

To speed things up, we’ll use Google’s new IDE, Antigravity, which relies on agents to generate code. The following prompt describes the UI we want to build:


You are an expert Frontend Developer. Your task is to build a premium, visually stunning blog post page for an Angular application. The project is already initialized.

### Goal
Create a standalone component named `BlogPost` that serves as a static blog post page. The design should be modern, "dark mode" by default, and evoke a high-tech, futuristic feel suitable for the topic of "Agentic AI".

### Structure & Content Constraints
The page must contain the following specific elements, stacked vertically:

1.  **Header Section**:
    *   **Tags**: A row of small pill-shaped tags: "Artificial Intelligence", "Future", "Tech".
    *   **Title**: Large, impactful typography: "The Rise of Agentic AI: A New Era of Coding".
    *   **Subtitle**: A lighter sub-heading: "How autonomous agents are transforming the software development landscape".

2.  **TL;DR Section**:
    *   Placed prominently below the header but before the main content.
    *   This section must clearly stand out from the rest of the text (e.g., using a border, different background tint, or accent color).
    *   **Heading**: "TL;DR".
    *   **Content**: A bulleted list summarizing the article (e.g., AI moving from autocomplete to autonomy, changing developer roles to architects).

3.  **Main Content**:
    *   Several paragraphs of text discussing "Agentic AI".
    *   Explain how it differs from traditional coding assistants.
    *   Discuss the shift from "writing code" to "guiding agents".
    *   Use highly readable typography with good line height and contrast.

### Design & Aesthetics (Crucial)
*   **Theme**: Dark mode. Background should be very dark (nearly black), text should be light grey/white.
*   **Typography**: Use a clean sans-serif font like 'Inter'.
*   **Color Palette**: Use neon/electric accents to pop against the dark background.
    *   *Primary Accent*: Electric Teal or Cyan (for tags/highlights).
    *   *Secondary Accent*: Electric Purple (for the TL;DR section or links).
*   **Visual Style**:
    *   The blog post container should look like a "card" floating in the center of the screen with a subtle shadow and rounded corners.
    *   Use subtle gradients for the text title if possible.
    *   Ensure the design is fully responsive (looks good on mobile).

### Technical Requirements
*   Use Angular Standalone Components.
*   Hardcode all the text content directly in the template or component class for now.
*   Do NOT implement any actual AI calls or backend services; this is purely a UI implementation task.

At this point, the focus is purely on UI. No AI calls yet.

Implementing the APIs

Create a new service to hold all the AI-related logic.

Start with a function that creates a session for the Summarization API:

private async createSummarizerSession() {
  return await Summarizer.create({
    type: 'key-points',
    length: 'short',
    expectedInputLanguages: ['en'],
    outputLanguage: 'en',
    expectedContextLanguages: ['en'],
    sharedContext: 'About AI and Agentic AI'
  });
}

Most parameters are self-explanatory. The most important one is type, which directly influences how the summary is generated.

If you want to explore all available options, check the official documentation:
https://developer.chrome.com/docs/ai/summarizer-api

Next, create a session for the Prompt API. We’ll use it to format the summarizer output into a clean structure:

private async createLanguageModelSession() {
  return await LanguageModel.create({
    initialPrompts: [
      { role: 'system', content: 'Convert this bullets into html. Return only the HTML' }
    ],
  });
}

Finally, combine both sessions. The summarizer extracts the key points, and the Prompt API enforces a structured output using a schema.

async generateTlDr(content: string): Promise<string[]> {
  const session = await this.createSummarizerSession();
  const summary = await session.summarize(content, {
    context: 'This article is intended for a tech-savvy audience.',
  });

  session.destroy();

  const lmSession = await this.createLanguageModelSession();
  const result = await lmSession.prompt(summary, { responseConstraint: schema });

  lmSession.destroy();

  const parsed = JSON.parse(result);
  return parsed?.items || [];
}

Here is the full service code:

import { Injectable } from '@angular/core';

declare const Summarizer: any;
declare const LanguageModel: any;

const schema = {
  type: 'object',
  required: ['type', 'items'],
  properties: {
    type: {
      type: 'string',
      enum: ['bullet_list'],
      description: 'Identifies the content as a bullet list'
    },
    items: {
      type: 'array',
      minItems: 1,
      items: {
        type: 'string',
        minLength: 1
      },
      description: 'Each entry is one bullet item, without bullet symbols'
    }
  },
  additionalProperties: false
};

@Injectable({
  providedIn: 'root'
})
export class AiService {
  async generateTlDr(content: string): Promise<string[]> {
    const session = await this.createSummarizerSession();
    const summary = await session.summarize(content, {
      context: 'This article is intended for a tech-savvy audience.',
    });

    session.destroy();

    const lmSession = await this.createLanguageModelSession();
    const result = await lmSession.prompt(summary, { responseConstraint: schema });

    lmSession.destroy();

    const parsed = JSON.parse(result);
    return parsed?.items || [];
  }

  private async createSummarizerSession() {
    return await Summarizer.create({
      type: 'key-points',
      length: 'short',
      expectedInputLanguages: ['en'],
      outputLanguage: 'en',
      expectedContextLanguages: ['en'],
      sharedContext: 'About AI and Agentic AI'
    });
  }

  private async createLanguageModelSession() {
    return await LanguageModel.create({
      initialPrompts: [
        { role: 'system', content: 'Convert this bullets into html. Return only the HTML' }
      ],
    });
  }
}

At this stage, most of the work is done.

Wiring It into the Component

Call the service from your component:

private aiService = inject(AiService);
public readonly postContent = content;
public tltrContent = signal<string[]>([]);

async ngOnInit() {
  const tldr = await this.aiService.generateTlDr(this.postContent);
  this.tltrContent.set(tldr);
}

Then update the template to render the TL;DR section:

<section class="tltr">
  <h3>TL;DR</h3>
  <div class="whitespace-pre-line">
    @if (tltrContent().length > 0) {
      <ul>
        @for (item of tltrContent(); track $index) {
          <li>{{ item }}</li>
        }
      </ul>
    } @else {
      <p>Loading...</p>
    }
  </div>
</section>

The TL;DR shown below is real and generated entirely on your machine. No tokens. No cost.

Support and Stability

Some of these APIs are still experimental, while others are already stable. In this example, the Summarization API does most of the heavy lifting and is already stable. The Prompt API is still experimental, but replacing it with regular code later should be straightforward.

You can find the full example here:
https://github.com/marianocodes/ai-local-gemini-nano-and-summarize

If you found this useful, share it and give it a like ❤️.

Using AI and Chrome MCP to Automate Core Web Vitals

Mariano Álvarez 🇨🇷 — Wed, 24 Dec 2025 03:33:42 +0000

One of the hardest and most tiring parts of working on web performance is the number of edge cases you need to consider. Some optimizations are purely code-related, while others require running real tests and analyzing the results.

The main challenge is keeping all of this in mind at the same time. This becomes even harder when you work with a team, where not everyone has the same level of experience or knowledge of performance best practices.

This is a great use case for AI. You can introduce a step where an LLM runs performance tests, uses ChromeMCP, executes the latest checks, gathers the results, and summarizes them in a way that works for your workflow.

The key piece here is ChromeMCP, which provides a wide range of functions that allow an LLM to access a page, interact with it, and run Chrome DevTools programmatically.

Prompts

The following two prompts are designed to gather performance data and then apply fixes based on what was found.

Get Core Web Vitals report

This prompt generates a Core Web Vitals report for a specific URL. It performs the following steps:

Navigate to the URL
Change the network to Slow 4G
Start a performance trace
Take a screenshot of the page
Click interactive elements to test INP
Analyze the results
Generate the report and close the page

The report is stored in the /reports directory along with the screenshot.

# Core Web Vitals Performance Test

Test the page at `<url>` and generate a Core Web Vitals report.

## Instructions

1. **Navigate to the page:**
   - Use `mcp__chrome-devtools__new_page` or `mcp__chrome-devtools__navigate_page` to go to `<url>`

2. **Apply network throttling:**
   - Use `mcp__chrome-devtools__emulate_network` with "Slow 4G" throttling to simulate real-world conditions

3. **Run performance trace:**
   - Use `mcp__chrome-devtools__performance_start_trace` with `reload: true` and `autoStop: true`
   - This will measure LCP, CLS, and other performance metrics

4. **Take a screenshot:**
   - Use `mcp__chrome-devtools__take_screenshot` with `fullPage: true` to capture the page
   - Save it to the `reports/` folder using the `filePath` parameter
   - Name it using the pattern: `screenshot-{domain}-{timestamp}.png`

5. **Test interactions (for INP):**
   - Use `mcp__chrome-devtools__take_snapshot` to identify interactive elements
   - Click on buttons/links using `mcp__chrome-devtools__click` to test interaction responsiveness

6. **Analyze results:**
   - Review the performance trace data
   - Identify LCP, CLS, INP scores
   - Look for performance insights and warnings

7. **Generate report:**
   - Create a markdown file in the `reports/` folder
   - Name it using the pattern: `core-vitals-{domain}-{timestamp}.md`
   - Include all findings, metrics, and actionable recommendations

8. **Clean up:**
   - Use `mcp__chrome-devtools__close_page` to close the browser tab after testing is complete
   - This ensures proper cleanup and prevents memory leaks

## Report Format

The report should be concise and easy to read, including:

- **Test Conditions**: Network throttling, URL tested
- **Core Web Vitals Scores**: LCP, CLS, INP with brief breakdowns
- **Additional Performance Insights**: Key findings from Chrome DevTools
- **Critical Problems Summary**: Top issues prioritized
- **Optimization Opportunities**: High-impact and medium-impact recommendations with estimated improvements

Keep the report focused and actionable. Avoid excessive detail or lengthy code examples.

---

## Example Report

# 🔴 Core Web Vitals Report: /products Page

**Test Conditions:**
- Network: Slow 4G throttling
- URL: https://example.com/products
- Test Date: 2025-01-29 10:30:00 UTC

---

## Core Web Vitals Scores

### 1. LCP (Largest Contentful Paint): 3,245ms 🔴

**Status:** Poor (Target: < 2,500ms for "Good")

**LCP Element:** Hero banner image

**Breakdown:**
- TTFB (Time to First Byte): 850ms ⚠️
- Load Delay: 1,200ms 🔴 (37% of LCP - time before image starts loading)
- Load Duration: 450ms ⚠️ (actual download time)
- Render Delay: 745ms ⚠️ (23% of LCP - time after download before paint)

**Key Issues:**
- Hero image is not discoverable immediately from HTML
- No preload hint for critical image
- Image served at 4MB uncompressed (3000x2000px)
- No modern image format (WebP/AVIF)

---

### 2. CLS (Cumulative Layout Shift): 0.25 🔴

**Status:** Poor (Target: < 0.1)

**Major Shifts:**
1. Hero image load: 0.15 shift (no width/height attributes)
2. Ad insertion: 0.08 shift (dynamic content injection)
3. Web font loading: 0.02 shift (FOUT)

**Key Issues:**
- Images missing explicit dimensions
- Dynamic content inserted without reserved space
- Fonts loaded asynchronously causing text reflow

---

### 3. INP (Interaction to Next Paint): 580ms 🔴

**Tested Interaction:** "Add to Cart" button click

**Status:** Poor (Target: < 200ms)

**Key Issues:**
- Heavy synchronous JavaScript execution on click (450ms)
- Main thread blocked during state update
- No visual feedback during processing
- Long tasks preventing quick response

---

## Additional Performance Insights

### Render Blocking Resources
- 3 CSS files blocking render (total 245KB)
- 2 JavaScript bundles blocking initial paint (total 890KB)
- **Estimated savings:** 1,200ms on LCP

### Network Dependency Chain
- Long chain of sequential resource requests (5 levels deep)
- Hero image depends on CSS → JS → API call

### Third-Party Impact
- Google Analytics: 180ms execution time
- Facebook Pixel: 220ms execution time

---

## Critical Problems Summary

1. **LCP Problem (3,245ms):**
   - 1,200ms load delay + 745ms render delay = 1,945ms of preventable delay
   - Image optimization and preloading are critical

2. **CLS Problem (0.25):**
   - Missing image dimensions causing major layout shifts
   - Dynamic content injection without space reservation

3. **INP Problem (580ms):**
   - Synchronous blocking operation prevents quick interaction response
   - Violates the 200ms INP threshold for good user experience

---

## Optimization Opportunities

### High Impact:
- Convert hero image to WebP/AVIF and compress to < 200KB
- Add `fetchpriority="high"` and preload hint to hero image
- Add explicit width/height to all images
- Use non-blocking state updates for button interactions
- **Estimated LCP improvement:** < 1,500ms (54% faster)
- **Estimated CLS improvement:** < 0.05 (80% better)
- **Estimated INP improvement:** < 180ms (69% faster)

### Medium Impact:
- Implement code splitting for JavaScript bundles
- Defer non-critical third-party scripts
- Reserve space for dynamic content (ads, widgets)
- Optimize font loading strategy
- Enable Brotli/Gzip compression

---

**Report generated:** 2025-01-29 10:30:00 UTC

---

## Usage

Replace `<url>` with the actual URL to test:

Test the page at http://localhost:3000/unoptimized and generate a comprehensive Core Web Vitals report.

Fix the issues found in the report

Once you have the report, you know exactly what needs to be fixed. The prompt below takes the report as part of the context and attempts to apply the recommended improvements.

# Optimize Code for Core Web Vitals

Read the Core Web Vitals report at `<path>` and implement the recommended optimizations to improve performance.

## Instructions

1. **Read the report:**
   - Use the Read tool to load the report file at `<path>`
   - Identify all issues and recommendations
   - Prioritize high-impact optimizations first

2. **Analyze the page:**
   - Identify the files that need to be modified
   - Use Glob and Grep tools to find relevant code
   - Read the current implementation

3. **Implement optimizations:**
   - Start with high-impact fixes (LCP, then CLS, then INP)
   - Make code changes using the Edit tool
   - Add clear comments explaining each optimization
   - Follow the recommendations from the report

4. **Common optimizations to implement:**

   **For LCP Issues:**
   - Convert `<img>` tags to Next.js `Image` component
   - Add `priority={true}` to hero/above-fold images
   - Add explicit `width` and `height` props
   - Set appropriate `quality` (e.g., 75 instead of 100)
   - Add responsive `sizes` attribute

   **For CLS Issues:**
   - Add explicit dimensions to all images
   - Add `aspect-ratio` CSS or container dimensions
   - Reserve space for dynamic content
   - Optimize font loading with `font-display`

   **For INP Issues:**
   - Replace blocking operations with async/non-blocking code
   - Use React's `useTransition` for state updates
   - Add loading states for immediate user feedback
   - Move heavy computations to Web Workers or defer them

   **General Optimizations:**
   - Add lazy loading (`loading="lazy"`) to below-fold images
   - Implement code splitting where appropriate
   - Defer non-critical scripts
   - Add preload hints for critical resources

5. **Document changes:**
   - Create a summary document in `reports/`
   - Name it: `optimization-summary-{timestamp}.md`
   - List all files modified
   - Describe each change made
   - Include expected performance impact

6. **Verify changes:**
   - Ensure no syntax errors were introduced
   - Check that imports are correct
   - Verify that the code follows best practices

## Optimization Guidelines

- **Be precise:** Only modify the code that needs optimization
- **Add comments:** Explain why each optimization was made
- **Follow patterns:** Use existing code style and conventions
- **Test safety:** Don't break existing functionality
- **High impact first:** Prioritize optimizations with the biggest performance gains

## Example Usage

Read the Core Web Vitals report at reports/core-vitals-localhost-1738166400.md and implement the recommended optimizations to improve performance.


---

## Example Optimization Summary

# Core Web Vitals Optimization Summary

**Date:** 2025-01-29 14:30:00 UTC
**Report Used:** reports/core-vitals-example-1738166400.md
**Page Optimized:** /products

---

## Issues Identified from Report

Based on the report analysis, the following high-priority issues were found:

1. **LCP (3,245ms):** Hero image not optimized, no preload hints
2. **CLS (0.25):** Missing image dimensions, dynamic content shifts
3. **INP (580ms):** Blocking JavaScript execution on button click

---

## Changes Made

### 1. LCP Optimization - Hero Image

**File:** `app/products/page.tsx` (lines 45-52)

**Issue from report:**
- Hero image served at 4MB uncompressed
- No preload hint for critical image
- Image not discoverable from HTML immediately

**Changes applied:**
- [Specific changes based on report recommendations]
- [Added necessary props/attributes]
- [Modified relevant code sections]

**Expected Impact:** -1,200ms on LCP

---

### 2. CLS Optimization - Image Dimensions

**File:** `app/products/page.tsx` (lines 78-120)

**Issue from report:**
- Images missing explicit dimensions causing 0.15 shift
- Dynamic ad insertion causing 0.08 shift

**Changes applied:**
- [Specific changes based on report recommendations]
- [Added dimension specifications]
- [Reserved space for dynamic content]

**Expected Impact:** -0.23 CLS (from 0.25 to 0.02)

---

### 3. INP Optimization - Button Interactions

**File:** `app/products/page.tsx` (lines 156-168)

**Issue from report:**
- Heavy synchronous JavaScript execution (450ms)
- Main thread blocked during state update

**Changes applied:**
- [Specific changes based on report recommendations]
- [Refactored blocking code]
- [Added non-blocking patterns]

**Expected Impact:** -400ms on INP (from 580ms to ~180ms)

---

## Files Modified

- `app/products/page.tsx` - Optimized images and interactions
- [Additional files if needed]

---

## Expected Performance Results

### Before Optimization (from report):
- LCP: 3,245ms 🔴
- CLS: 0.25 🔴
- INP: 580ms 🔴

### After Optimization (estimated):
- LCP: ~2,045ms ⚠️ (37% improvement)
- CLS: ~0.02 ✅ (92% improvement)
- INP: ~180ms ✅ (69% improvement)

**Note:** Run a new performance test to verify actual improvements.

---

**Optimization completed:** 2025-01-29 14:30:00 UTC

---

## Important Notes

- Always read the entire report before making changes
- Focus on high-impact optimizations first (those with largest expected improvements)
- Test after each major change to ensure nothing broke
- Keep the original unoptimized version for comparison
- Add detailed comments to explain each optimization
- If the report mentions issues that don't apply to the current code, skip them
- Don't over-optimize - focus on the specific issues identified in the report

Tips and ideas to improve your development flow

These prompts can be used with any AI tool such as GeminiCLI, Claude Code, Cursor, or Antigravity. You will need to adapt and tweak them depending on the tool and setup you are using.

Some ideas:

Create custom slash commands in GeminiCLI and pass the URL directly, for example: @test-core-vitals url:/products
Create a sub-agent in Claude Code and call it in a similar way. The AI is smart enough to understand that url is a variable and replace it in the context.
Add a Git hook that triggers these prompts automatically to detect performance issues and apply fixes early.

The optimization prompt is focused on React applications, but it can be adapted to any framework. For Angular projects, you can combine this approach with the Angular MCP to get better and more consistent results.

If you want to see more of my content, follow me on LinkedIn.

Don't forget to like and share ❤️

Avoiding Hallucinations When Building Angular Apps with Gemini CLI

Mariano Álvarez 🇨🇷 — Tue, 23 Dec 2025 05:28:12 +0000

We are seeing new models released every five or six months. That does not mean they are trained with the latest information. For example, a model may not include the most recent Angular documentation and can easily generate outdated code that does not follow current best practices.

GeminiCLI is a great tool for building faster with AI, but it is not immune to hallucinations. Below are a few techniques you can use to get more accurate output and better-aligned Angular code.

Prompt with best practices

You can define a shared prompt in your Gemini.md file. This helps guide the model to generate code that follows modern Angular patterns and current best practices.

Another option is to define a custom slash command and trigger it with every request. That way, you make sure your instructions are always included.

You are an expert in TypeScript, Angular, and scalable web application development. You write functional, maintainable, performant, and accessible code following Angular and TypeScript best practices.

## TypeScript Best Practices
- Use strict type checking
- Prefer type inference when the type is obvious
- Avoid the `any` type; use `unknown` when the type is uncertain

## Angular Best Practices
- Always use standalone components over NgModules
- Must NOT set `standalone: true` inside Angular decorators. It is the default in Angular v20+
- Use signals for state management
- Implement lazy loading for feature routes
- Do NOT use `@HostBinding` or `@HostListener`. Use the `host` object in the `@Component` or `@Directive` decorator instead
- Use `NgOptimizedImage` for all static images
  - `NgOptimizedImage` does not work with inline base64 images

## Accessibility Requirements
- Must pass all AXE checks
- Must follow WCAG AA minimums, including focus management, color contrast, and proper ARIA attributes

## Components
- Keep components small and focused on a single responsibility
- Use `input()` and `output()` functions instead of decorators
- Use `computed()` for derived state
- Set `changeDetection: ChangeDetectionStrategy.OnPush` in the `@Component` decorator
- Prefer inline templates for small components
- Prefer reactive forms over template-driven forms
- Do NOT use `ngClass`; use `class` bindings instead
- Do NOT use `ngStyle`; use `style` bindings instead
- When using external templates or styles, use paths relative to the component TypeScript file

## State Management
- Use signals for local component state
- Use `computed()` for derived state
- Keep state transformations pure and predictable
- Do NOT use `mutate` on signals; use `update` or `set` instead

## Templates
- Keep templates simple and avoid complex logic
- Use native control flow (`@if`, `@for`, `@switch`) instead of `*ngIf`, `*ngFor`, `*ngSwitch`
- Use the async pipe to handle observables
- Do not assume globals like `new Date()` are available
- Do not write arrow functions in templates

## Services
- Design services around a single responsibility
- Use `providedIn: 'root'` for singleton services
- Use the `inject()` function instead of constructor injection

This approach gives you full control over the rules you want the model to follow. The downside is that this file becomes another artifact you need to keep up to date as Angular evolves.

llms.txt

Another approach is exposing a llms.txt file. The idea is for websites to provide a single entry point that language models can use to discover official and structured documentation. Conceptually, it is similar to a RAG setup, but without the infrastructure overhead.

Angular currently exposes two versions:
• llms.txt A lightweight file that links to key resources
• llms-full.txt A comprehensive set of resources that explains how Angular works and how to build Angular applications

This solves part of the maintenance problem because you no longer need to keep your own prompt updated. The tradeoff is that you now depend on an external source being available and accurate.

Angular MCP

The Angular CLI now includes an MCP that GeminiCLI can consume to access up-to-date documentation and best practices. This is the most robust option and requires very little setup.

In .gemini/settings.json, add the following:

{
  "mcpServers": {
    "angular-cli": {
      "command": "npx",
      "args": ["-y", "@angular/cli", "mcp"]
    }
  }
}

This gives GeminiCLI access to several Angular-specific tools:
• ai_tutor
Launches an interactive Angular tutor. Recommended for new Angular v20+ projects
• find_examples
Finds authoritative and up-to-date code examples based on official Angular sources
• get_best_practices
Retrieves the Angular Best Practices Guide, covering standalone components, typed forms, and modern control flow
• list_projects
Lists all applications and libraries defined in an Angular workspace by reading angular.json
• onpush_zoneless_migration
Analyzes your codebase and provides a step-by-step plan to migrate to OnPush change detection, a requirement for zoneless applications
• search_documentation
Searches the official Angular documentation at angular.dev for APIs, guides, and best practices

If you have not tried GeminiCLI yet, it is worth a look. It is simple to use and surprisingly powerful when paired with the right context.

Don't forget to like and share! ❤️

Use Your ADK AI Agent in a UI

Mariano Álvarez 🇨🇷 — Mon, 30 Jun 2025 02:13:35 +0000

In the last post, we created an agent with memory using ADK and ran it through the dev dashboard.

Cool. But… now what?

You probably want to use that agent outside of the testing UI — like inside your own app. Let’s walk through how to serve the agent with FastAPI and connect it from a front-end.

Set up your agent

Start by organizing your project like this:

Then, in a file called agent.py, define your agent:

from google.adk.agents import Agent

root_agent = Agent(
    name="costa_rica_expert_agent",
    model="gemini-2.0-flash",
    description="Agent to answer questions about Costa Rica and its culture",
    instruction="You are a helpful agent who can answer user questions about Costa Rica and its culture",
)

Important: You need to name your agent variable root_agent. ADK looks for that name specifically — if it’s called anything else, it won’t work.

Set up your server

Now let’s wire it up with FastAPI.

Here’s what your main.py might look like:

import os
import uvicorn
from google.adk.cli.fast_api import get_fast_api_app

AGENT_DIR = os.path.dirname(os.path.abspath(__file__))
SESSION_DB_URL = "sqlite:///memory.db"
ALLOWED_ORIGINS = ["http://localhost", "http://localhost:8080", "*"]
SERVE_WEB_INTERFACE = True

app = get_fast_api_app(
    agents_dir=AGENT_DIR,
    session_service_uri=SESSION_DB_URL,
    allow_origins=ALLOWED_ORIGINS,
    web=SERVE_WEB_INTERFACE,
)

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

This is one of the things I like most about ADK — they give you a helper to set up the whole FastAPI app in one line. No need to wire everything manually.

And if you want to add your own routes, just treat it like any FastAPI app:

@app.get("/hello")
async def say_hello():
    return {"hello": "world"}

Then just run:

python main.py

You’re live.

Frontend integration

If you’re building your UI in Angular (like I am), here’s how you can connect to the agent.

ADK’s dev dashboard is open source and built with Angular. Here’s how it makes API calls to the agent using Server-Sent Events (SSE):

runSse(req: AgentRunRequest) {
  const url = this.apiServerDomain + `/run_sse`;
  this.isLoading.next(true);
  return new Observable<string>((observer) => {
    const self = this;
    fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'text/event-stream',
      },
      body: JSON.stringify(req),
    })
    .then((response) => {
      const reader = response.body?.getReader();
      const decoder = new TextDecoder('utf-8');
      let lastData = '';

      const read = () => {
        reader?.read()
          .then(({ done, value }) => {
            this.isLoading.next(true);
            if (done) {
              this.isLoading.next(false);
              return observer.complete();
            }
            const chunk = decoder.decode(value, { stream: true });
            lastData += chunk;
            try {
              const lines = lastData.split(/\r?\n/).filter((line) => line.startsWith('data:'));
              lines.forEach((line) => {
                const data = line.replace(/^data:\s*/, '');
                JSON.parse(data);
                self.zone.run(() => observer.next(data));
              });
              lastData = '';
            } catch (e) {
              if (e instanceof SyntaxError) {
                read(); // wait for the next chunk
              }
            }
            read(); // keep reading
          })
          .catch((err) => {
            self.zone.run(() => observer.error(err));
          });
      };

      read();
    })
    .catch((err) => {
      self.zone.run(() => observer.error(err));
    });
  });
}

Yeah — not exactly simple.

Even if you don’t want streaming, the /run_sse endpoint always returns an event-stream. So you still have to handle it this way for now.

If you want to check it out directly, here’s the link to the actual implementation.

Can this be easier?

Definitely.

In the next post, I’ll show you how to simplify this and connect to your agent from any front-end — without needing to manually handle SSE streams.

Stay tuned.

And if this helped, a like or comment goes a long way.

Adding Sessions and Memory to Your AI Agent with Agent Development Kit (ADK)

Mariano Álvarez 🇨🇷 — Sun, 29 Jun 2025 16:42:54 +0000

In my previous post, I walked through how to build a basic AI agent using ADK. It’s exciting to get an agent running and see it respond to prompts — but once the session ends, that context is gone. It has no memory of anything that happened before.

This is fine for demos, but if you’re aiming to build something real then you’ll quickly hit a wall.

Fortunately, ADK gives us tools to fix that.

Why Sessions Matter

Let’s say you build a ticket finder agent that helps someone search for flights. During the conversation, the user mentions that they prefer Delta and want to fly out of San Francisco.

Without session management, the agent forgets all of that context between interactions. So even if the user follows up with, “What about something cheaper?” the agent has no clue what they’re referring to.

That’s where Session comes in.

What is a Session?

In ADK, a Session is an object that represents a conversation. It keeps track of who the user is, what app (agent) is running, what’s been said, what tools were called, and any custom state you want to track along the way.

Each session includes:

Basic identifiers
• id: A unique session ID
• appName: Name of the agent application
• userId: The user having the conversation

Events

A chronological list of everything that happens — user messages, tool calls, agent replies, etc.

State

A dictionary that stores structured data the agent can access and modify during the session.

lastUpdateTime

Timestamp for the latest interaction in the session.

Choosing the Right SessionService

To use sessions, you need a session service. ADK gives you a few out-of-the-box options, depending on your environment:

1. InMemorySessionService

This is great for local development or protyping. Everything is stored in memory — and wiped as soon as the app restarts.

from google.adk.sessions import InMemorySessionService

session_service = InMemorySessionService()

2. DatabaseSessionService

This option is for when you’re running something in production. It stores sessions in a relational database and uses a built-in migration system to manage the schema.

from google.adk.sessions import DatabaseSessionService

db_url = "your_database_url"
session_service = DatabaseSessionService(db_url=db_url)

A heads-up: ADK manages the database schema internally, so if you’re integrating this with your existing database, I strongly recommend using a dedicated schema with a separate user that has limited access.

3. VertexAiSessionService

If you’re on Google Cloud and want tight integration with Vertex AI, you can use this session service to leverage Google’s managed infrastructure.

from google.adk.sessions import VertexAiSessionService

session_service = VertexAiSessionService(
    project="your-gcp-project-id",
    location="us-central1"
)

Creating a Session

Once your session service is initialized, you can create a new session like this:

session = await session_service.create_session(
    app_name="ticket_finder_app",
    user_id="marianocodes",
    state={"preferred_airline": "delta"}
)

You’ll get back a session object that you can attach events to, store state in, and use throughout the conversation.

Working with Session State

The state object is a dictionary you can use to store anything your agent should remember while the session is active.

If you’re a frontend developer, think of it like a Redux store scoped to the conversation. If you’re coming from a backend background, you can think of it like a session object tied to a user’s request — only it’s more flexible.

State Guidelines

A few things to keep in mind:
1. Use primitives — strings, numbers, booleans. Don’t store complex objects or custom classes.
2. Scope your data using prefixes:

No prefix session.state["last_message"] = "hello" visible only during this session
user: session.state["user:theme"] = "dark" shared across all of the user’s sessions
app: session.state["app:language"] = "en" shared across the app
temp: session.state["temp:step"] = "waiting_for_payment" temporary info, not persisted long-term

How to Update State

There are multiple ways to update the session state, depending on the structure of your agent.

1. Via output_key

This is the simplest method. If your agent returns a value and you want to store it automatically:

ticket_finder_agent = LlmAgent(
    name="Ticket Finder",
    model="gemini-2.5-flash",
    instruction="...",
    output_key="best_ticket"
)

Whatever value is returned from the model will be stored under session.state["best_ticket"].

2. Via ToolContext or CallbackContext

Inside tool or callback functions, you get access to the session’s context. You can use that to manually update state at any point.

def purchase_ticket(tool_context: ToolContext):
    context.state["waiting_for_purchase"] = False

This is useful when you want to track a specific action or condition and update state based on logic inside your tools.

3. Using EventActions.state_delta

This gives you full control — you define what changes in the state and register that as a system-level event.

state_changes = {
    "ticket_in_screen": "AV-258"
}

actions = EventActions(state_delta=state_changes)

event = Event(
    invocation_id="inv_state_update",
    author="system",
    actions=actions,
    timestamp=time.time()
)

await session_service.append_event(session, event)

It’s more verbose, but also more precise when you want to track a series of changes or attach metadata.

Adding Memory

Sessions let your agent remember context during a conversation. But what about after the session ends?

That’s where memory comes in.

InMemoryMemoryService

This lets your agent access information during a single session — similar to InMemorySessionService but not the same.

VertexAiRagMemoryService (GCP)

ADK includes a memory service built on RAG (retrieval-augmented generation). It stores content as embeddings and lets your agent retrieve relevant context across sessions.

from google.adk.memory import VertexAiRagMemoryService

memory_service = VertexAiRagMemoryService(
    rag_corpus="projects/your-gcp-project-id/locations/us-central1/ragCorpora/your-corpus-id",
    similarity_top_k=5,
    vector_distance_threshold=0.7
)

To use it inside an agent:

from google.adk.tools import load_memory

ticket_finder_agent = LlmAgent(
    name="Ticket Finder",
    model="gemini-2.5-flash",
    instruction="...",
    tools=[load_memory]
)

Then, once the session is done, you can store its content:

session = await runner.session_service.get_session(
    app_name=APP_NAME,
    user_id=USER_ID,
    session_id=session_id
)

await memory_service.add_session_to_memory(session)

What If You’re Not Using GCP?

I got you, You can still build something similar.

Under the hood, load_memory just performs a similarity search using Vertex AI. You can replicate this using your own vector DB (like Pinecone, Qdrant, or AstraDB). You just need to handle chunking, embedding, and retrieval on your own.

Here’s a peek at what the function looks like behind the scenes:

What's next?

We’ve covered how to set up an agent — and now, how to give it memory. But so far, everything’s only been accessible through the testing UI.

What if you want to run it in a real web app?

Want to support my work? A quick like goes a long way ❤️.

Lessons from 6 Months of Building AI Agents

Mariano Álvarez 🇨🇷 — Fri, 20 Jun 2025 16:49:02 +0000

Over the past six months, I’ve been deep in the trenches working with AI agents. I’ve built prototypes, tested frameworks, broken things, and occasionally gotten something to work the way I intended.

It’s been exciting — but also humbling.

There’s a lot of hype out there, and while much of it is grounded in genuine progress, I’ve seen first-hand how different the day-to-day reality is from the glossy demos and blog posts.

If you’re getting started with AI agents or just curious about what it’s really like, here are eight honest takeaways from my experience.

1. Most “AI Agents” Aren’t Really Agents

You’ve probably seen demos of AI agents that can schedule appointments, handle customer support, or generate content for your brand. They look polished. They seem smart. But here’s the truth:

Most of these are just well-structured workflows with a bit of LLM magic sprinkled in.

They aren’t making real decisions. They’re running predefined steps — like “if the message includes a time, call the calendar API” — and using the LLM only to interpret input or format output. That’s automation, not agency.

If you’re expecting autonomy, judgment, or adaptation, you’ll be disappointed — unless you build it yourself.

2. We’re Early. Really Early.

There’s a shared moment a lot of people have when they first dive into AI: “This is going to replace us.”

And maybe it will, someday. But not today.

As developers, we already know where AI can help right now — drafting code, writing tests, summarizing input. But there are still major limitations in reasoning, context retention, memory, and reliability.

AI agents aren’t anywhere close to replacing full-time employees in most domains. There’s a long road ahead.

3. The Happy Path Isn’t Enough
Almost every tutorial or demo out there shows the same types of agents: the travel assistant, the research bot, the meeting note taker.

They’re helpful — but they only show the “happy path.” The scenario where everything works, every tool returns a valid result, and the user asks perfect questions.

Building real agents means dealing with broken APIs, vague input, long-running tasks, and dead ends. The real world is messy — your agents need to be prepared for that.

4. Agents Are Slow (and That’s a Problem)

One of the biggest performance surprises when building agents is how slow they can be.

You’re likely calling an LLM multiple times, invoking tools or APIs, chaining results, and possibly routing through sub-agents. Each step adds latency.

Unlike ChatGPT — where billions have been spent on speed and optimization — your custom agent lives in your infra. And speed will matter to your users.

If you want the experience to feel responsive, you’ll need to optimize around latency: infrastructure, parallelism, UI tricks like optimistic rendering — whatever you can do to mask the delay.

5. Tooling Is Easy. Prompting Is Hard.

Writing the code to call a tool? Easy.

Getting your agent to consistently decide when to call that tool — and how to use it — based on messy, real-world inputs? Not so easy.

Prompts are where most of the real work happens. They’re fragile. Small wording changes can completely shift the model’s behavior. And you’ll spend a lot of time iterating, debugging, and rephrasing.

It can be frustrating. But when you finally get a clean, natural response chain — it’s worth it.

6. Modularity Comes at a Cost

As engineers, we’re trained to decompose problems into smaller units — functions, services, components.

It’s tempting to do the same with agents: one for scheduling, one for research, one for recommendations, and a router that directs traffic.

That works, but it introduces two big problems:
• Context fragmentation: It becomes harder to maintain state across multiple agents.
• Latency overhead: Every routing decision is another round-trip with the model or server.

Sometimes, fewer agents with more tightly scoped memory works better than trying to modularize everything too early.

7. Prompting > Coding (and That’s the Job)
If you want to get good at building agents, you need to get good at writing prompts.

Use Gemini, ChatGPT, or your LLM of choice to help generate and improve them. But don’t blindly trust the output. Always read it. Test it. Make sure the behavior aligns with what you intended.

Too many devs treat LLMs like a black box that “just works.” That leads to brittle systems. If you’re not reading and refining your prompts, you’re not really building.

8. Frameworks Matter, but Start Simple

My first experience building agents was with LangGraph. It’s powerful and flexible — but also low-level and hard to grasp at first. The documentation isn’t always clear, and there are often multiple ways to solve the same problem.

If you’re just getting started, pick a simpler tool and focus on getting something working.

In my case, I eventually moved to Google’s Agent Development Kit (ADK). It’s easy to use, supports multi-agent flows, tool integration, memory, and works great with Google’s infrastructure like MCP and A2A.

I’ve used it since the early versions and reported a few bugs — the team behind it is active and responsive, and the framework has improved fast.

Final Thoughts

Building AI agents is hard. It’s not magic. It’s not plug-and-play. But it is possible — and incredibly satisfying when it works.

The biggest unlock isn’t the model. It’s how you design your prompts, your tools, your UX, and your system architecture to work with the model — not against it.

⸻

I’d love to hear your perspective:

What lessons have you learned while building or exploring AI agents? What’s worked — and what hasn’t?

Build your first AI Agent with ADK - Agent Development Kit by Google

Mariano Álvarez 🇨🇷 — Sun, 01 Jun 2025 23:22:48 +0000

I’ve been working with AI agents since the beginning of the year. It hasn’t been an easy journey — there was a ton of learning and experimentation along the way.

Throughout this process, I tried different libraries and frameworks. For example:

LangGraph: It's a great tool for building low-level flows. Getting a simple flow working is easy, but things quickly get complex when you start connecting more than one node. Another issue I found is the documentation — it’s confusing, as there are several ways to define an agent.

Agno: I really liked this one. The API is simple and easy to understand, and the documentation is great. However, when I tried to set up a multi-agent architecture, I ran into performance issues.

But then I tried ADK (Agent Development Kit) — and it solved most of my problems. It has great documentation, it’s backed by Google, and the team seems very active, delivering fixes weekly. I was able to understand everything very quickly.

Movie Finder with ADK

ADK works with Python, and there’s also a recent version available in Java. For this example, we’ll stick with Python. Let’s get started:

Install the package:pip install google-adk

Set up your environment keys — in this case, we’ll use Gemini. You can generate the API key in Google AI Studio:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=PASTE_YOUR_ACTUAL_API_KEY_HERE

Now, create the folder structure for your agent:

parent_folder/
    movie_finder_agent/
        __init__.py
        agent.py
        .env

In __init__.py, make sure to include from . import agent

Now let’s work on the tool our agent will use:

MOVIES = [
    {"title": "The Matrix", "genre": "Sci-Fi", "year": 1999},
    {"title": "Inception", "genre": "Sci-Fi", "year": 2010},
    {"title": "Titanic", "genre": "Romance", "year": 1997},
    {"title": "The Godfather", "genre": "Crime", "year": 1972},
    {"title": "Interstellar", "genre": "Sci-Fi", "year": 2014},
    {"title": "Pulp Fiction", "genre": "Crime", "year": 1994},
]

def find_movies(genre: str, decade: int) -> str:
    """
    Find movies that match the specified genre and year.

    Args:
        genre (str): The genre to filter movies by (e.g. "Sci-Fi", "Romance", "Crime")
        decade (int): The start year of the decade to filter movies by (e.g. 1990, 2000)

    Returns:
        str: A newline-separated string of matching movie titles, or a message if no matches found
    """    
    results = []
    year_range = range(decade, decade + 10)

    for movie in MOVIES:
        if genre and movie["genre"] == genre and movie["year"] in year_range:
          results.append(movie["title"])          

    if not results:
        return "No matching movies found."

    return "\n".join(results)

As you can see, a tool is just a regular function the agent can call — nothing new here. In this case, the agent’s job is to figure out the parameters the tool needs in order to run correctly.

Here’s how the agent is defined:

root_agent = Agent(
    name="root_agent",
    model="gemini-2.5-flash-preview-04-17",
    description="Answers questions from the user",
    instruction="You are a helpful assistant that can answer questions about movies.",
    tools=[
        find_movies
    ],
)

It’s very simple to understand, but let me break down the properties:
- name – the agent’s name
- model – the model version; if you want to use a non-Google model, you can use LiteLLM
- description – a short summary of what the agent does
- instruction – your agent’s prompt and behavior guide
- tools – the list of tools your agent can call

Now let’s see it in action. Run adk web

This dashboard is the testing environment, and here you can see the agent in action, and as you can see I asked: I'm looking for a sci-fi movie in the 90s. It correctly used the tool and generated the final response.

If we inspect the tool call, we can see the correct parameters were passed:

And it returned the result as expected.

In under 5 minutes, you created your first agent — with minimal effort and simple prompts!

Agents Are Not Just LLMs

It’s important to understand a few key concepts to avoid confusion or wrong expectations when working with agents:

LLM ≠ Agent An LLM is a pretrained model built using massive datasets, high compute costs, and long training cycles. An agent is a runtime layer built on top of an LLM that adds tools, memory, and logic.
Agents can think, remember, and act They can analyze a question, call a tool to get an answer, and store that result for future use — like a lightweight brain with short-term memory.
Agents are slower than chat apps Don’t expect the speed you see in ChatGPT or Gemini.

⸻

If you want a part 2 of this tutorial, leave a like!

Cómo Utilizar el API Experimental de AI en Chrome

Mariano Álvarez 🇨🇷 — Tue, 01 Oct 2024 03:44:18 +0000

Historial de cambios:

25/10/24 Edición: se actualizo el API, cambio de ai.assistant a ai.languageModel

Para utilizar el API experimental de AI en Chrome, sigue estos pasos:

Requerimientos de Hardware

4GB de RAM
GPU disponible
Mínimo 22GB de espacio
Windows 10.11 o macOS Ventura o versiones más recientes (sin especificación para Linux)

No hay soporte aún para:

ChromeOS
Chrome iOS
Chrome Android

Requerimientos de Software

Instalar Chrome Canary
Activar la AI y los modelos modificando los siguientes flags:

Ve a chrome://flags/#optimization-guide-on-device-model y selecciona "Enabled BypassPerfRequirement"
Ve a chrome://flags/#prompt-api-for-gemini-nano y selecciona "Enable"
Reinicia Chrome
Verifica la instalación ejecutando este comando en la consola: (await ai.languageModel.capabilities()).available. Debe devolver "readily".

Si falla, prueba lo siguiente:

Ejecuta await ai.languageModel.create() para intentar forzar a Chrome a activar el API (aunque podría no funcionar).
Ve a chrome://components y revisa si el componente "Optimization Guide On Device Model" tiene una versión igual o mayor a 2024.5.21.1031. Si no tiene versión, haz clic en "check for updates" e intenta nuevamente.

Nota: A veces, la instalación del modelo puede tardar. Ten paciencia y repite el proceso si es necesario.

Activación de Modelos

Para activar los modelos, habilita los siguientes flags en Chrome:

chrome://flags/#prompt-api-for-gemini-nano
chrome://flags/#summarization-api-for-gemini-nano
chrome://flags/#rewriter-api-for-gemini-nano
chrome://flags/#writer-api-for-gemini-nano
chrome://flags/#language-detection-api

Las funciones disponibles

Prompt API

Este es el modelo más sencillo, utilizado para tareas generales. Al enviarle un prompt, intenta devolver una respuesta. Aquí un ejemplo básico:

const session = await ai.languageModel.create();
const result = await session.prompt("Explain what JavaScript is");

También puedes utilizar systemPrompt para pasarle instrucciones adicionales:

const session = await ai.languageModel.create({
  systemPrompt: "You are an expert in JavaScript, providing helpful code best practices."
});

Language Detection

Esta API detecta el idioma de un texto, soportando más de 100 lenguajes y variantes.

Ejemplo:

const detector = await translation.createDetector();
const results = await detector.detect("Bonjour le monde");
for (const result of results) {
  console.log(result.detectedLanguage, result.confidence);
}

Writer y Rewriter

Writer API: Crea contenido nuevo.
Ejemplo: escribir un borrador de una solicitud al banco.

const writer = await ai.writer.create();
const result = await writer.write("Write a email asking for feedback");

Rewriter API: Mejora o reestructura un texto ya existente.

const rewriter = await ai.rewriter.create();
const result = await rewriter.rewrite("La inteligencia artificial es...", { context: "Use simple words." });

Todos estos APIs están en fase experimental, por lo que es normal encontrar errores o inconsistencias. Todo feedback es bienvenido. Si te interesa estar al tanto de los cambios, puedes llenar este formulario para acceder a la documentación y recibir actualizaciones.

AI Local con el API de Chrome

Mariano Álvarez 🇨🇷 — Mon, 30 Sep 2024 17:18:44 +0000

Es común que la mayoría de los productos que utilizan inteligencia artificial (IA) lo hagan a través del consumo de un API, que a su vez se conecta a un servidor para retornar los resultados a la web. Esto tiene mucho sentido cuando las tareas son intensas y requieren un gran poder de procesamiento.

Pero, ¿existe alguna opción más eficiente para tareas sencillas?

El equipo de Chrome ha lanzado de manera experimental un API que permite interactuar con el modelo Gemini Nano de manera local. Así, se elimina la necesidad de utilizar modelos más grandes, como Gemini Pro 1.5, para tareas complejas.

Principales Diferencias

Integración Local: No es necesario hacer deploy del modelo. Al estar integrado directamente en el navegador, este se encarga de gestionar la descarga, actualización y mejoras. El desarrollador solo debe preocuparse por integrarlo en su aplicación.
Eficiencia en la Descarga: Al no requerir que la aplicación descargue el modelo, se mejora la eficiencia. Incluso los modelos pequeños, en el contexto web, pueden ser de gran tamaño. Por ejemplo, el modelo de transformer.js pesa alrededor de 60MB.
Mejora en el Rendimiento: Esta integración local permite acceder a recursos del dispositivo, como el GPU, lo que mejora significativamente el rendimiento.

Beneficios de Correr un Modelo de Manera Local

Ahorro de Llamados al Servidor: Al evitar consultas constantes al servidor, la aplicación web se vuelve más eficiente, reduciendo tiempos de espera.
Privacidad: Los datos permanecen en el dispositivo, lo que añade una capa extra de seguridad al no tener que enviarlos a servidores externos.
Uso Offline: Una vez descargado, el modelo está disponible en el dispositivo, lo que permite su uso sin conexión a internet.

Arquitecturas Híbridas

Aunque el modelo local es eficiente, no podemos descartar completamente el servidor. Este seguirá siendo necesario para procesar tareas más complejas. La clave está en encontrar el "sweet spot", es decir, el punto óptimo en el que se determine cuándo utilizar un modelo local y cuándo recurrir al servidor.

Además, los modelos integrados pueden servir como respaldo en caso de fallos del servidor o falta de conexión a internet.

Limitaciones

Al ser un modelo pequeño y optimizado para correr en el navegador, tiene una capacidad más limitada. Por ahora, se recomienda su uso para tareas puntuales como traducciones, resúmenes o mejoras de texto. Este tipo de modelos son conocidos como "Expert Models", ya que son más eficientes para tareas específicas.

Únete al Programa Experimental

Si quieres probar este API, puedes unirte al programa experimental llenando el formulario en el en este enlace. Recibirás acceso a la documentación y a un Google Group donde podrás mantenerte informado sobre las actualizaciones y cambios en el API.

Aprende en el siguiente post cómo empezar a utilizar este API y las funciones disponibles.

Performance: Los valores de Lighthouse y PageSpeed Insights son diferentes

Mariano Álvarez 🇨🇷 — Tue, 18 Jun 2024 14:33:49 +0000

Existen dos tipos de herramientas para hacer pruebas de performance en web:

1. Herramientas de laboratorio

Funcionan en condiciones específicas, por ejemplo:
• No consideran el cache, bfCache, ni AMP
• Ambientes controlados (geografía, dispositivo, velocidad)
• Sirven en la etapa de desarrollo, antes de producción
• Son estables, generalmente el score es el mismo aunque se corra la herramienta varias veces

2. Herramientas de campo

Utilizan datos reales para comparar los resultados y determinar el score.

Pueden ser datos recolectados manualmente o utilizando el Chrome UX Report

🧪 Lighthouse en los Devtools de Chrome funciona como una herramienta de laboratorio. Lo puedes determinar porque al final del reporte vienen las condiciones en las que se corrieron las pruebas, por ejemplo:

• Initial page load
• Slow 4G throttling
• Single page session
• Using Chromium 125.0.0.0 with devtools
• Emulated Moto G Power with Lighthouse 11.7.1

⚡️ PageSpeed Insights por su parte entrega una información similar pero puedes detallar que las pruebas corren en diferentes condiciones:

• Full visit durations
• All Chrome versions
• Various mobile devices
• Various network connections
• Latest 28-day collection period
• Many samples (Chrome UX Report)

Así que no te asustes, está bien que los valores sean diferentes, solo tienes que entender la razón.

Te ayudo a ser un mejor Web Developer
Click + Mariano Alvarez + Seguir + 🔔

Like si te gustó este contenido ❤️

Microsoft hace a un lado React

Mariano Álvarez 🇨🇷 — Tue, 11 Jun 2024 16:06:22 +0000

Así como lo lees, recientemente Microsoft anunció que logró una mejora de rendimiento del 76% en su navegador Microsoft Edge.

En un experimento que realizaron al reemplazar un menú que fue construido originalmente con React con WebUI 2.0, su nueva librería de componentes.

Impresionantemente, sus modificaciones tuvieron como resutlado que el componente sea un 42% más rápido, pero para aquellos que no tienen equipos más limitados, con menos de 8GB de RAM o sin estado sólido (SSD), se vio una mejora del 76%.

Probablemente te estás preguntando:
• ¿Un navegador con React?
¡Claro! Al final, todo se traduce a HTML, CSS y JavaScript.

• ¿Qué significa esto para React?
NADA, esto no es ni positivo ni negativo.

• ¿React es lento?
No, pero para ti, ¿qué es velocidad?

Todas estas mejoras están disponibles en la versión 122 de Microsoft Edge.

Te leo en los comentarios.