DEV Community: Wassim Chegham

Prompt Stuffing Is Killing Your Agent

Wassim Chegham — Mon, 30 Mar 2026 15:49:49 +0000

Classic RAG is like packing your entier wardrobe for a weekend trip. Sure, you'll have options, but good luck finding what you need.

In Part 1, we talked about why agents fall apart in production: compounding errors, the reliability tax, the gap between demo magic and real-world chaos. Now let's zoom into one of the biggest culprits — how most agents handle retrieval.

Because classic RAG has a mantra: "We always retrieve context." And that's exactly where the problems start.

The Problem: Retrieve Everything, Hope for the Best

Let's go back to our running example: a travel-planning agent. A user asks for a 4-day trip with hiking, a modest budget, and one fancy dinner. Reasonable request. Here's what classic RAG does with it:

It grabs everything. Weather data. Hotel options. Flight details. Restaurant suggestions. Trail maps. Local events. Currency exchange rates. It crams all of that into a single prompt and says, "Hey model, figure it out."

This is fragile for reasons that should be obvous, but let's spell them out anyway:

The model has to reason across too many dimensions at once. Flights, budget constraints, hiking trail difficulty, restaurant dress codes, weather windows, all competing for attention in one context window.
Constraints get missed. When you stuff a 6,000-token context blob into a prompt, the model has to juggle everything simultaneously. Your budget limit? Buried somewhere between the hotel listings and the weather forecast.
It breaks as complexity grows. A simple "book me a flight" query works fine. A multi-day, multi-constraint trip plan? The prompt becomes a minefield.

Here's the uncomfortable truth that a lot of RAG tutorials gloss over:

More context ≠ better answers. It means higher cost, slower responses, and more room for the model to get confused.

You're paying more tokens to get worse results. That's not a tradeoff — that's a bug in your architecture.

Look at the left side. That's a prayer, not a pipeline. Now look at the right side. That's engineering.

The Solution: Agentic RAG or Conditional Retrieval

Agentic RAG flips the model. Instead of "always retrieve," it uses conditional retrieval. The agent fetches information only when it actually needs it, validates what it got, and only then moves on.

The key insight is simple: retrieval should be a decision, not a reflex.

Here's what that looks like for our travel agent:

The user asks for a 4-day hiking trip on a budget with one fancy dinner.
The agent doesn't immediately fire off six API calls. It thinks first: "What do I need to know before I can even start planning?"
It retrieves destination info: where can you hike for 4 days that fits the budget?
It validates that against the constraints. Are there actually trails there? Is it the right season?
Only then does it retrieve flight options. And it checks: does this fit the budget?
Then hotels. Then activities. Each step, validated before moving on.

This is the "conditional retrieval + validation loop" pattern, and it removes a huge class of production bugs.

Notice the loops. The agent isn't just a straight pipeline — it pauses, checks constraints, and only then decides what to do next. Classic RAG has no loops. It's a one-shot gamble. Agentic RAG is iterative and self-correcting.

The Validation Loop in Practice

Let's make this concrete. Say the agent is looking for hotels for our hiking trip:

Each retrieval gets validated against specific constraints — budget, availability, location — before the agent moves on. If validation fails, the agent adjusts and re-retrieves. No silent failures. No hallucinated hotel that doesn't actually exist at that price.

Compare this to classic RAG, where the model gets a list of 20 hotels in one context dump and picks one that looks right. Maybe it's in budget. Maybe it's not. You won't know until the user tries to book it.

The Cost Case for Conditional Retrieval

Here's the part that makes your finance team happy: Agentic RAG is cheaper to run.

This seems counterintuitive. You're doing more steps — reason, retrieve, validate, repeat. But here's why it's actually cheaper:

Fewer tokens per request. You retrieve only the data you need for the current step, not the entire knowledge base dump. A focused hotel query is 200 tokens of context. The "everything at once" approach can easily be 4,000+.
Fewer tool calls overall. Conditional retrieval means you skip irrelevant sources. If the user's destination is already decided, you don't waste a call retrieving "top destinations for hiking."
Fewer retries. When the model gets confused by too much context, it gives bad answers. Bad answers trigger retries, clarifications, follow-up calls. Clean context → right answer the first time.

But here's the piece that most tutorials miss: budgets are part of agent state.

If you're running agents in production, you need to track:

Token usage per step and per session
Number of tool calls
Retry counts
Total execution time

Your supervisor loop (the thing orchestrating the agent's steps) should enforce limits. If the token budget is hit, the agent should stop, summarize what it has so far, or ask the user for confirmation before continuing.

Think about it this way: we don't keep searching hotels forever just to find a $2 cheaper option. At some point, the cost of searching exceeds the savings. A well-designed agent knows when to stop.

This is where the "agentic" part really matters. A classic RAG pipeline has no concept of cost awareness, it retrieves, it stuffs, it's done. An agentic system can reason about whether the next retrieval is worth the cost.

Why This Matters in Production

In a demo, classic RAG works fine. The inputs are controlled. The context is small. The constraints are simple. You show it on stage, everyone claps, you ship it.

Then production happens.

Real users have complex, multi-constraint requests. The context grows. The prompt gets bloated. The model starts missing things. You add more retrieval to "fix" it, which makes the prompt bigger, which makes the model miss more things. It's a death spiral.

Agentic RAG breaks this cycle because:

Each step is scoped. The model reasons about one thing at a time with only the context it needs.
Validation catches errors early. A constraint violation at step 3 gets caught at step 3, not discovered when the user sees the final output.
The agent is cost-aware. It doesn't burn through your API budget retrieving data it doesn't need.
It scales with complexity. Adding a new constraint (e.g., "must be wheelchair accessible") means adding a validation check, not restructuring the entire prompt.

Takeaways

If you're building agents that use retrieval (and most agents do) here's your checklist:

Make retrieval conditional, not automatic. The agent should decide whether to retrieve, not just retrieve by default.
Validate after every retrieval step. Check the results against your constraints before moving on.
Scope your context. Each step should get only the data it needs — not the full knowledge base.
Track your costs as state. Token usage, tool calls, retries, and execution time should be first-class values in your agent's state.
Enforce limits in your supervisor loop. Set budgets and let the agent know when to stop searching and start deciding.
Design for re-retrieval. When validation fails, the agent should be able to adjust parameters and try again, not crash or hallucinate.

For a deeper dive into advanced Agentic RAG patterns, check out Pamela Fox's session on the topic — it's an excellent companion to what we've covered here.

Are you using classic RAG or agentic RAG in your projects? Share your thoughts in the comments below!

Why Your AI Agent Demo Falls Apart in Production

Wassim Chegham — Fri, 20 Mar 2026 15:49:47 +0000

Your agent demo crushed it on stage. The audience clapped. Your PM high-fived you. The travel-planning agent nailed it — a 4-day hiking trip, budget-friendly, one fancy dinner on night three. Beautiful.

Then you deployed it and… it fell apart.

Not dramatically. Not all at once. It just started doing weird things. Booking a hotel in Paris, then recommending a restaurant in London. Picking a "budget" flight that cost $1,200. Suggesting a hiking trail that's been closed since 2019. Death by a thousand paper cuts.

If this sounds familiar, you're not alone. And the problem isn't your model, your prompt, or your vibes. It's math.

Multi-Step Agents Are Distributed Systems (Whether You Like It or Not)

Here's the thing nobody tells you when you're building that first agent prototype: a multi-step AI agent is a distributed system. Every tool call is a network request that can fail, time out, or return garbage. Every reasoning step is a non-deterministic decision that might go sideways.

Your travel agent doesn't just "plan a trip." It orchestrates a chain of operations: search flights, check hotel availability, look up hiking trails, find restaurants, cross-reference budgets, verify dates. Each step depends on the last. Each step can break.

We've been building distributed systems for decades. We know they're hard. But somehow, when we slap "AI" on it, we forget everything we learned and expect magic.

Let's stop doing that.

The 5 Failure Modes of Multi-Step Agents

I've seen agents fail in production in roughly five ways. Every. Single. Time.

1. Wrong Tool Selection

The agent has six tools available and picks the wrong one. You ask for hiking trails near Chamonix and it calls the hotel booking API. Why? Because the model decided "outdoor activities" was close enough to "hotel amenities." This isn't a bug you can reproduce consistently — it happens 1 in 20 times, which is exactly often enough to ruin your weekend.

2. API Timeouts

External APIs are flaky. The flight search takes 30 seconds instead of 3. The agent doesn't wait — it either times out and hallucinates a result, or it retries in a loop until your user gives up. Welcome to the real world, where third-party APIs don't care about your agent's plans.

3. Partial Failures

This one's sneaky. The tool responds, but with incomplete data. The flight API returns 2 results instead of 15 because of a pagination bug. The agent doesn't know it's working with a partial dataset — it just picks the "best" option from a bad menu. Your user gets a suboptimal flight, and nobody understands why.

4. Inconsistent State

Over a long conversation or a multi-step plan, the agent loses track. It picks Paris as the destination in step 1, finds flights to CDG in step 2, then recommends a restaurant in London in step 5. The context window is long, but the agent's attention isn't perfect. Earlier decisions get fuzzy, and the plan stops being coherent.

5. Compounding Failures

This is the killer. A small mistake early on — say, the agent misreads the budget as $5,000 instead of $500 — doesn't just affect one step. It cascades. The hotel is too expensive. The restaurant is too fancy. The hiking gear rental gets skipped because the budget's already blown. By step 7, the entire itinerary is garbage, and the root cause is buried six steps back.

The Reliability Tax: When "Almost Perfect" Isn't Good Enough

Let's talk numbers, because this is where intuition fails us.

Say your agent is 95% accurate at each individual step. That sounds great, right? You'd ship that. Your PM would celebrate that.

Now do the math for a 10-step task:

0.95¹⁰ ≈ 0.5987

Your "95% accurate" agent succeeds less than 60% of the time on a 10-step plan. That's a coin flip. For a travel itinerary.

Here's what that looks like as your agent takes on more complex tasks:

Steps	Per-Step Accuracy	System Success Rate
5	95%	77.4%
10	95%	59.9%
15	95%	46.3%
20	95%	35.8%
5	99%	95.1%
10	99%	90.4%
20	99%	81.8%

Read that bottom row again. Even at 99% per-step accuracy — which is incredibly hard to achieve — a 20-step agent fails nearly 1 in 5 times.

Almost perfect at the step level turns into mostly broken at the system level.

This is the reliability tax. You pay it whether you know about it or not. And the instinct — the thing everyone does first — is to blame the model. "We need GPT-5." Or to blame the prompt. "Let me add 47 more lines to the system prompt."

But the real issue isn't the model or the prompt. It's system complexity and basic probability. You can't prompt-engineer your way out of compound probability.

The Fix: Stop Treating Agents Like Magic

The solution isn't a better model. It's a better architecture. Stop treating your agent as a magic black box and start treating it as what it actually is: a non-deterministic software component that needs the same engineering discipline as any other distributed system.

Two mindset shifts make the biggest difference.

Mindset Shift 1: Selective Autonomy

The instinct with agents is to go full autopilot. "Let the AI handle everything!" That's like removing the pilot from a plane because autopilot exists.

Autopilot is incredible — for cruising at 35,000 feet. But you want a human pilot for takeoff, landing, and when the engine catches fire. Same with agents.

Don't let the agent do everything autonomously. Insert human approval steps at high-stakes decision points. Before the agent books a $400 flight? Human confirms. Before it commits to a restaurant reservation? Human confirms.

Here's the beautiful part: each human checkpoint resets the error probability. Instead of one 10-step chain with a 60% success rate, you get three 3-step chains with a human verification between them. Each chain has ~85% accuracy, and the human catches the failures in between. Your effective reliability goes way up — not because the model got smarter, but because you designed the system better.

This is selective autonomy. Let the agent handle what it's good at (searching, comparing, summarizing) and keep humans in the loop for what matters (confirming, approving, deciding).

Mindset Shift 2: Trace-Level Observability

When your agent breaks in production, your logs say something helpful like:

ERROR: Agent failed to complete task

Thanks. Very useful.

Traditional logging tells you something bad happened. But with a multi-step agent, you need to know:

What happened — which tool was called, what arguments were passed, what came back
Where time went — did step 3 take 200ms or 20 seconds?
Why it failed — was it the model's reasoning, the tool's response, or the orchestration logic?

This is where traces come in. Not logs. Traces.

A trace captures the full execution path of your agent: every reasoning step, every tool call, every input and output. It's the difference between "the patient is sick" and a full medical chart with vitals, lab results, and imaging.

Build trace-level observability from day one. Instrument every tool call. Capture the agent's chain-of-thought at each decision point. When (not if) something breaks in production, you'll know exactly where to look.

Here's what you want to capture in a trace:

Agent reasoning — the model's chain-of-thought before each action
Tool selection — which tool was chosen and why
Tool input/output — the exact request and response
Latency — how long each step took
Token usage — how much context was consumed at each step
Outcome — success, partial failure, or error

Without this, you're debugging a distributed system with console.log. Good luck.

The Gap Between Demo and Production

The gap between a demo that works and a product that works isn't more features. It's not a bigger model. It's not a fancier prompt.

It's discipline and structure.

It's acknowledging that your agent is a distributed system subject to compound probability, and engineering accordingly. It's inserting human checkpoints where they matter. It's building observability that tells you the full story, not just the punchline.

The travel agent that worked on stage can work in production. But only if you stop treating it like magic and start treating it like software.

Takeaways

Here's what you should do this week:

Map your agent's failure modes. Walk through each step and ask: "What happens when this tool fails? Returns partial data? Times out?" If you can't answer, you have a problem.
Calculate your reliability tax. Count your agent's steps. Do the math. If you're at 10+ steps with no human checkpoints, your success rate is probably lower than you think.
Add human-in-the-loop checkpoints at high-stakes decision points. Start with the most expensive or irreversible actions.
Instrument traces, not just logs. Capture the full execution path — reasoning, tool calls, latency, outputs. Make it queryable.
Stop blaming the model. The model is one component. The system is the product. Engineer the system.

In the next post, we'll tackle one of the biggest culprits behind agent failures: retrieval. Specifically, why classic RAG makes everything worse — and how Agentic RAG fixes it.

Have you experienced the reliability tax with your agents? Share your thoughts in the comments below!

Using LlamaIndex.TS to Orchestrate MCP Servers

Wassim Chegham — Mon, 07 Jul 2025 15:49:59 +0000

In this post, we’ll demonstrate how to orchestrate Model Context Protocol (MCP) servers using llamaindex.TS in a real-world TypeScript application. We’ll use the Azure AI Travel Agents project as our base, focusing on best practices for secure, scalable, and maintainable orchestration. Feel free to star the repo to get notified with the latest changes.

If you are interested in an overview of the Azure AI Travel Agents project, please read our announcement blog!

Why llamaindex.TS and MCP?

llamaindex.TS provides a modular, composable framework for building LLM-powered applications in TypeScript.
MCP enables tool interoperability and streaming, making it ideal for orchestrating multiple AI services.

Project Structure

The Llamaindex.TS orchestrator lives in src/api/src/orchestrator/llamaindex, with provider modules for different LLM backends and MCP clients. We currently support:

Azure OpenAI
Docker Models
Azure AI Foundry Local
Github Model
Ollama

Feel free to explore the code base and suggest more providers.

Setting Up the MCP Client with Streamable HTTP

To interact with MCP servers, without using Llamaindex.TS, we can write a custom implementation using the StreamableHTTPClientTransport for efficient, authenticated, and streaming communication.

// filepath: src/api/src/mcp/mcp-http-client.ts
import EventEmitter from 'node:events';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

export class MCPClient extends EventEmitter {
  private client: Client;
  private transport: StreamableHTTPClientTransport;

  constructor(serverName: string, serverUrl: string, accessToken?: string) {
    this.transport = new StreamableHTTPClientTransport({
      url: serverUrl,
      headers: accessToken ? { Authorization: `Bearer ${accessToken}` } : {},
    });
    this.client = new Client(serverName, this.transport);
  }

  async connect() {
    await this.client.initialize();
  }

  async listTools() {
    return this.client.listTools();
  }

  async callTool(name: string, toolArgs: any) {
    return this.client.callTool(name, toolArgs);
  }

  async close() {
    await this.client.closeGracefully();
  }
}

Best Practice: Always pass the Authorization header for secure access, as shown above.

Calling manually an MCP Tool from the Orchestrator

Suppose you want to get destination recommendations from the MCP server:

import { MCPClient } from '../../mcp/mcp-http-client';

const DESTINATION_SERVER_URL = process.env.MCP_DESTINATION_RECOMMENDATION_URL!;
const ACCESS_TOKEN = process.env.MCP_DESTINATION_RECOMMENDATION_ACCESS_TOKEN;

const mcpClient = new MCPClient('destination-recommendation', DESTINATION_SERVER_URL, ACCESS_TOKEN);

await mcpClient.connect();

const tools = await mcpClient.listTools();
console.log('Available tools:', tools);

const result = await mcpClient.callTool('getDestinationsByPreferences', {
  activity: 'CULTURAL',
  budget: 'MODERATE',
  season: 'SUMMER',
  familyFriendly: true,
});
console.log('Recommended destinations:', result);

await mcpClient.close();

Tip: Always close the MCP client gracefully to release resources.

Orchestrating LLMs and MCP Tools with Llamaindex.TS

The mcp client from @llamaindex/tools makes it easy to connect to MCP servers and retrieve tool definitions dynamically. Below is a sample from the project’s orchestrator setup, showing how to use mcp to fetch tools and create agents for each MCP server.

Here is an example of what an mcpServerConfig object might look like:

const mcpServerConfig = {
  url: "http://localhost:5007", // MCP server endpoint
  accessToken: process.env.MCP_ECHO_PING_ACCESS_TOKEN, // Secure token from env
  name: "echo-ping", // Logical name for the server
};

You can then use this config with the mcp client:

import { mcp } from "@llamaindex/tools";
import { agent, multiAgent, ToolCallLLM } from "llamaindex";

// ...existing code...

const mcpServerConfig = mcpToolsConfig["echo-ping"].config;
const tools = await mcp(mcpServerConfig).tools();
const echoAgent = agent({
  name: "EchoAgent",
  systemPrompt:
    "Echo back the received input. Do not respond with anything else. Always call the tools.",
  tools,
  llm,
  verbose,
});
agentsList.push(echoAgent);
handoffTargets.push(echoAgent);
toolsList.push(...tools);

// ...other code...

const travelAgent = agent({
  name: "TravelAgent",
  systemPrompt:
    "Acts as a triage agent to determine the best course of action for the user's query. If you cannot handle the query, please pass it to the next agent. If you can handle the query, please do so.",
  tools: [...toolsList],
  canHandoffTo: handoffTargets
    .map((target) => target.getAgents().map((agent) => agent.name))
    .flat(),
  llm,
  verbose,
});
agentsList.push(travelAgent);

// Create the multi-agent workflow
return multiAgent({
  agents: agentsList,
  rootAgent: travelAgent,
  verbose,
});

You can repeat this pattern to compose a multi-agent workflow where each agent is powered by tools discovered at runtime from the MCP server. See project for a full example.

You can then use this LLM instance to orchestrate calls to MCP tools, such as itinerary planning or destination recommendation.

Security Considerations

Always use access tokens and secure headers.
Never hardcode secrets; use environment variables and secret managers.

Join the Community:

We encourage you to join our Azure AI Foundry Developer Community to share your experiences, ask questions, and get support:

Join our Discord community for real-time discussions and support.
Visit our Azure AI Foundry Developer Forum to ask questions and share your knowledge.

Conclusion

By combining llamaindex.TS with MCP’s Streamable HTTP transport, you can orchestrate powerful, secure, and scalable AI workflows in TypeScript. The Azure AI Travel Agents project provides a robust template for building your own orchestrator.

References:

DeepSeek Extension for GitHub Copilot in VS Code 🚀

Wassim Chegham — Thu, 13 Feb 2025 11:36:49 +0000

tl;dr: Run DeepSeek models in your GitHub Copilot Chat 🚀

DeepSeek has been getting a lot of buzz lately, and with a little setup, you can start using it today in GitHub Copilot within VS Code. In this post, I’ll walk you through how to install and run a VS Code extension I built, so you can take advantage of DeepSeek right on your machine. With this extension, you can use @deepseek to explore the deepseek-coder model. It’s powered by Ollama, enabling seamless, fully offline interactions with DeepSeek models—giving you a local coding assistant that prioritizes privacy and performance.

In a future post I'll walk you through the extension code and explain how to call models hosted locally using Ollama. Feel free to subscribe to get notified.

Features and Benefits

Open-Source and Extendable

As an open-source project, the DeepSeek for GitHub Copilot extension is fully customizable. Advanced users can modify and extend its functionality, build from source, tweak configurations, and even integrate additional AI capabilities.

Local AI Processing

With the DeepSeek for GitHub Copilot extension, all interactions are processed locally on your machine, ensuring complete data privacy and eliminating latency issues. This makes it an ideal solution for developers working on sensitive projects or in restricted environments.

Seamless Integration with GitHub Copilot Chat

The extension integrates natively with GitHub Copilot Chat, allowing you to invoke DeepSeek models effortlessly. If you're already familiar with GitHub Copilot, you'll find the workflow intuitive and easy to use. You can simply type @deepseek followed by your question to get started.

Powered by Ollama

Ollama, a lightweight AI model runtime, powers the execution of DeepSeek models. It simplifies model management by handling downloads and execution, so you can focus on coding.

Customizable Model Selection

You can configure the extension to use different DeepSeek models through a simple setting adjustment. This flexibility allows you to choose the right model size and capability for your hardware. Please note that running bigger models might not work on your local system. You can take advantage of Azure's infrastructure to run bigger models.

Installation Guide

Installing and Running Ollama

DeepSeek for GitHub Copilot requires Ollama to function properly. Ollama is an AI model runtime that allows you to run and manage large language models efficiently on your local machine.

Install Ollama: Download the installer, install, and start Ollama from the Ollama website.
Install from Visual Studio Code Marketplace: The simplest way to get started is by installing the extension directly from the Visual Studio Code Marketplace.
- Open Visual Studio Code.
- Navigate to the Extensions panel (Ctrl + Shift + X).
- Search for DeepSeek for GitHub Copilot and click Install.
Using the Extension: Once installed, using the extension is straightforward:
- Open the GitHub Copilot Chat panel.
- Type @deepseek followed by your prompt to interact with the model.
- Note: On the first run, the extension will automatically download the DeepSeek model. This may take a few minutes, depending on your internet connection.

Configuration and Customization

DeepSeek for GitHub Copilot allows users to configure the AI model through Visual Studio Code settings.

To change the DeepSeek model, update the settings.json file:

{ "deepseek.model.name": "deepseek-coder:1.3b" }

A list of available models can be found on the Ollama website.

Limitations and Workarounds

Current Limitations

The extension does not have access to your files in this version, meaning it cannot provide context-aware completions. This is due to the fact that DeepSeek models don't support Function Calling.
Limited to local machine performance—larger models may require more RAM and CPU power.

Workarounds

To provide context for completions, manually copy-paste the relevant code into the chat.
Optimize performance by selecting smaller DeepSeek models (such as deepseek-coder:1.3b) if you experience lag.

System Requirements

To run DeepSeek for GitHub Copilot Chat, ensure you have the following:

Visual Studio Code (latest version recommended)
Ollama app installed and running (Download from ollama.com)
Sufficient system resources
- Minimum: 8GB RAM, multi-core CPU
- Recommended: 16GB RAM, GPU acceleration (if available)

Conclusion

The DeepSeek for GitHub Copilot Chat extension provides an excellent way for delivering privacy, low-latency responses, and offline capabilities.

🔗 Get Started Today: Install the DeepSeek for GitHub Copilot Chat extension and supercharge your GitHub Copilot Chat experience with AI—entirely offline! 🚀

■ Wassim Chegham (https://wassim.dev)

Building a RAG app with LlamaIndex.ts and Azure OpenAI: Getting started!

Wassim Chegham — Tue, 10 Sep 2024 09:22:33 +0000

As AI continues to shape the way we work and interact with technology, many businesses are looking for ways to leverage their own data within intelligent applications. If you've used tools like ChatGPT or Azure OpenAI, you're already familiar with how generative AI can improve processes and enhance user experiences. However, for truly customized and relevant responses, your applications need to incorporate your proprietary data.

This is where Retrieval-Augmented Generation (RAG) comes in, providing a structured approach to integrating data retrieval with AI-powered responses. With frameworks like LlamaIndex, you can easily build this capability into your solutions, unlocking the full potential of your business data.

Want to quickly run and explore the app? Click here.

What is RAG - Retrieval-Augmented Generation?

Retrieval-Augmented Generation (RAG) is a neural network framework that enhances AI text generation by including a retrieval component to access relevant information and integrate your own data. It consists of two main parts:

Retriever: A dense retriever model (e.g., based on BERT) that searches a large corpus of documents to find relevant passages or information related to a given query.
Generator: A sequence-to-sequence model (e.g., based on BART or T5) that takes the query and the retrieved text as input and generates a coherent, contextually enriched response.

The retriever finds relevant documents, and the generator uses them to create more accurate and informative responses. This combination allows the RAG model to leverage external knowledge effectively, improving the quality and relevance of the generated text.

How does LlamaIndex implement RAG?

To implement a RAG system using LlamaIndex, follow these general steps:

Data Ingestion:

Load your documents into LlamaIndex.ts using a document loader such as SimpleDirectoryReader, which helps in importing data from various sources like PDFs, APIs, or SQL databases.
Break down large documents into smaller, manageable chunks using the SentenceSplitter.

Index Creation:

Create a vector index of these document chunks using VectorStoreIndex, allowing efficient similarity searches based on embeddings.
Optionally, for complex datasets, use recursive retrieval techniques to manage hierarchically structured data and retrieve relevant sections based on user queries.

Query Engine Setup:

Convert the vector index into a query engine using asQueryEngine with parameters such as similarityTopK to define how many top documents should be retrieved.
For more advanced setups, create a multi-agent system where each agent is responsible for specific documents, and a top-level agent coordinates the overall retrieval process.

Retrieval and Generation:

Implement the RAG pipeline by defining an objective function that retrieves relevant document chunks based on user queries.
Use the RetrieverQueryEngine to perform the actual retrieval and query processing, with optional post-processing steps like re-ranking the retrieved documents using tools such as CohereRerank.

For a practical example, we have provided a sample application to demonstrate a complete RAG implementation using Azure OpenAI.

Practical RAG Sample Application

We'll now focus on building a RAG application using LlamaIndex.ts (the TypeScipt implementation of LlamaIndex) and Azure OpenAI, and deploy on it as a serverless Web Apps on Azure Container Apps.

Requirements to Run the Sample

Azure Developer CLI (azd): A command-line tool to easily deploy your entire app, including backend, frontend, and databases.
Azure Account: You'll need an Azure account to deploy the application. Get a free Azure account with some credits to get started.

You will find the getting started project on GitHub. We recommend you to fork this template so you can freely edit it when needed:

High-Level Architecture

The getting started project application is built based on the following architecture:

Azure OpenAI: The AI provider that processes the user's queries.
LlamaIndex.ts: The framework that helps ingest, transform, and vectorize content (PDFs) and create a search index.
Azure Container Apps: The container environment where the serverless application is hosted.
Azure Managed Identity: Ensures top-notch security and eliminates the need for handling credentials and API keys.

For more details on what resources are deployed, check the infra folder available in all our samples.

Example User Workflows

The sample application contains logic for two workflows:

Data Ingestion: Data is fetched, vectorized, and search indexes are created. If you want to add more files like PDFs or Word files, this is where you should add them.
```
  npm run generate
```
Serving Prompt Requests: The app receives user prompts, sends them to Azure OpenAI, and augments these prompts using the vector index as a retriever.

Running the Sample

Before running the sample, ensure you have provisioned the necessary Azure resources.

To run the GitHub template in GitHub Codespace, simply click

In your Codespaces instance, sign into your Azure account, from your terminal:

azd auth login

Provision, package, and deploy the sample application to Azure using a single command:

azd up

To run and try the application locally, install the npm dependencies and run the app:

npm install
npm run dev

The app will run on port 3000 in your Codespaces instance or at http://localhost:3000 in your browser.

Conclusion

This guide demonstrated how to build a serverless RAG (Retrieval-Augmented Generation) application using LlamaIndex.ts and Azure OpenAI, deployed on Microsoft Azure. By following this guide, you can leverage Azure's infrastructure and LlamaIndex's capabilities to create powerful AI applications that provide contextually enriched responses based on your data.

We’re excited to see what you build with this getting started application. Feel free to fork it and like the GitHub repository to receive the latest updates and features.

Azure Static Web Apps CLI is now GA 🚀

Wassim Chegham — Wed, 25 May 2022 19:28:10 +0000

What is Azure Static Web Apps?

Azure Static Web Apps is a service that's perfect for your full stack as well as static application projects. Yes, you heard that correctly. Regardless if you are dealing with:

A static resume site with vanilla HTML, CSS and JavaScript
SPA application with Angular, React, Vue, etc.
Static site generators like Gatsby, Next, etc.

Azure Static Web Apps is there for you and enables you to deploy your files to Azure. In order words, Azure Static Web Apps if the perfect choice if you are looking for:

FREE Web hosting for static content like HTML, CSS, JavaScript, and images.
Integrated API support provided by Azure Functions with the option to link an existing Azure Functions app using a standard account.
First-class GitHub and Azure DevOps integration where repository changes trigger builds and deployments.
Globally distributed static content, putting content closer to your users.
Free SSL certificates, which are automatically renewed.
Custom domains to provide branded customizations to your app.
Seamless security model with a reverse-proxy when calling APIs, which requires no CORS configuration.
Authentication provider integrations with Azure Active Directory, GitHub, and Twitter.
Customizable authorization role definition and assignments.
Back-end routing rules enabling full control over the content and routes you serve.
Generated staging versions powered by pull requests enabling preview versions of your site before publishing.

What is Azure Static Web Apps CLI?

It's the CLI companion for Azure Static Web Apps that you use from your local dev machine. The SWA CLI offers tons of features, such as:

Work on your JAMstack app locally
Built-in framework detection
Serverless support
Authentication & Authorization
Login to Azure
Deploy & Ship from the CLI

Check it the documentation website 👍
Have fun!

Feel free to reach out on Twitter at @manekinekko if you want to get started with Azure Static Web Apps. You can also follow my work at wassim.dev.

Understanding Git Internals

Wassim Chegham — Sun, 20 Feb 2022 21:58:01 +0000

Let's explore some common Git commands, and dive into Git internals to understand what happens when you run Git commands.

But first, let's talk about Git itself.

What is Git?

Put simply, Git is an open source distributed version control system. It was designed by Linus Torvalds, creator of the Linux kernel, to manage the source code of the kernel. Git was designed from the start to be as fast and efficient as possible.

Git's Principles

In other version control systems such as CVS, Subversion, and ClearCase, the server is centralized — there's a clear separation between the server and clients.

When developers work on projects that use these systems, they first send a checkout request to the server, then retrieve a snapshot of the current version — usually the most recent one. Everyone has to go through the central server in order to work on the same project, sending commits or creating branches.

With Git, things are different. When we want to work on a project that uses Git, we clone it locally, on to our machine. In other words, Git copies all project files to our local drive, then we can work on the project. All operations run locally on our machine. We don't even need a network connection, except to synchronize with other team members, when pushing our changes or pulling new changes.

That's what makes Git so quick.

With Git, we can:

commit changes.
change and create branches.
merge or rebase branches.
retrieve a diff or apply a patch.
recover different versions of the same file.
access the change history of any file.

And we can do most of this without even being connected to the Internet. Amazing, right?

Let's talk about some of the very basic Git commands when it comes to staging and committing changes to Git.

A brief intro to Git basic commands

When we access a folder that contains the source code of an application we are working on, but doesn't use Git, and run git status. Git will respond that the current directory is not a Git repository:

That's because we haven't initialized Git in this project. We need to first run git init in the root directory in order to initialize a new Git repository.

As we can see from the screenshot, we created an empty Git repository, and we are currently on its default branch — usually called main.
We can also notice that Git creates a .git/ folder at the root of the project. This hidden directory is Git's internal database. If you wish to make a backup of your project's Git history, simply make a copy of this directory.

Let's run git status again to see what's the status of our new project:

Git tells us that we haven't added anything to our commit. What Git means here is that we haven't revisioned any content yet. In Git, we can do this in 2 steps:

mark the change to be committed using git add.
commit the change to Git using git commit.

Let's add the content of the current root directory with the git add . command:

The next step is to commit these files using the command git commit -m "my first commit":

Let's change the title of our app in src/index.html and then run the command git diff:

Git shows what changes are waiting to be committed. We can view those changes using the git status. Once we are sure about our changes, we can commit them using the commands git add . followed by git commit -m "add thundr emoji". Or, we can combine these two commands into one using git commit -am "add thundr emoji" (note the -am options):

This was a brief intro to some of the basic Git commands.

You can learn more about Git in this Git tutorial.

Now let's look at how Git does all this.

Git Objects

When we create a local repository with git init (or git clone), Git initializes its database, and saves it in a hidden directory called .git/:

If we examine this folder, we'll find several subfolders and files. The most interesting ones are:

HEAD: this file contains the path to the reference of the current branch.
config: the repository configuration file.
objects/: this is the directory that contains all files in our repository, their content is encoded and compressed.
refs/heads/: this directory contains one file per branch. Each file is named after a branch, and its content is the SHA-1 of the last commit.

When we create or edit files and run git add ., Git adds a snapshot of the files to its database. It retrieves the current content of the edited files, then computes a hash using a SHA-1 algorithm, and creates an entry in its database for this specific change. The key of this entry is the SHA-1 hash, and its value is the raw contents of the file. Yes, the whole content!



.git/objects/
➜ tree -L 2
.
├── 61
│   └── cef767aa6b95d09a46848c9305d51a7d2ffbdf
├── c4
│   └── 581986199f973ea6b006a7a754486db97104c5
├── ...
├── f5
│   ├── 31992d6edce8355d131c31723398305ee08364
│   └── 6ff47022c7a46eac3aee615d6d9150338524dc
└── ...

Git uses a technique called Content Addressable Storage to store the content of files, as objects, inside the .git/objects/folder. Basically, Git uses the first 2 characters of the object's name as a subfolder name, i.e. objects/xx/, add the remaining 38 characters are used as the file name, i.e. objects/xx/yy.

Note that when referring or inspecting the content of these files and folders, we can simply use the first 8 bits of the SHA-1 hash. Those are enough!

Tree objects

Git uses a simplified UNIX-filesystem-like format to store tree its content. Content is stored as tree and blob objects. Trees objects is similar to UNIX directory entries and blob objects are more or less inodes or file contents. A single tree object contains one or more entries, each of which is the SHA-1 hash of a blob or subtree with its associated mode, type, and filename.

We can inspect the current branch in Git using git ls-tree and print a list of its latest stored objects. A branch's name is considered to be a top-level tree:



@manekinekko/thundr
➜ git ls-tree main
100644 blob 4f9ac26980c156a3d525267010d5f78144b43519    .browserslistrc
100644 blob 0711527ef9d5c117396e6c03290a76658e6384ed    .gitignore
040000 tree 572a53f73bb332280d19f2f7cb0bcac8b32faab5    .vscode
100644 blob 7c582e3fcc8e8d02e8e018eb43959020c2aef847    README.md
100644 blob a1486ac82746b7019361a1758f00dc6fd7a29efd    angular.json
100644 blob c6f92b3680a069987a4c1236ec12c7b377eda1ea    package.json
040000 tree 61cef767aa6b95d09a46848c9305d51a7d2ffbdf    src
100644 blob 82d91dc4a4de57f380b66c59cdd16ff6cd5798e4    tsconfig.app.json
100644 blob f531992d6edce8355d131c31723398305ee08364    tsconfig.json

Notice that the src subdirectory is a tree that points to another tree:



040000 tree 61cef767aa6b95d09a46848c9305d51a7d2ffbdf    src

We can inspect the src tree using its SHA-1 hash:



@manekinekko/thundr
➜ git ls-tree 61cef767aa6b95d09a46848c9305d51a7d2ffbdf
040000 tree dbfd18df3078aaf0f03edff8c237e4248a84759c    app
040000 tree d564d0bc3dd917926892c55e3706cc116d5b165e    assets
040000 tree 5825478d74b5576b0f8330bdf5179b3ec6503fb8    environments
100644 blob 997406ad22c29aae95893fb3d666c30258a09537    favicon.ico
100644 blob c4581986199f973ea6b006a7a754486db97104c5    index.html
100644 blob c7b673cf44b388e9989fe908b78d7d73cd2e1409    main.ts
100644 blob 429bb9ef2d3400363c014fa434775b0f482f6bea    polyfills.ts
100644 blob 90d4ee0072ce3fc41812f8af910219f9eea3c3de    styles.css

Tree objects list one or multiple blobs and sub-trees, with their mode/permissions, the type, the SHA-1 hash, and the file/folder name.

Looking at the index.html entry, we notice that the content is stored are a blob:



100644 blob c4581986199f973ea6b006a7a754486db97104c5    index.html

Blob objects

For blobs, we can read their content using the git-cat command:



@manekinekko/thundr 
➜ git cat-file -p c4581986199f973ea6b006a7a754486db97104c5
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Thundr</title>
  <base href="/">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="icon" type="image/x-icon" href="favicon.ico">
</head>
<body>
  <app-root></app-root>
</body>
</html>

Let's update the content of the src/index.html file, and run again a git add .. Git performs the same process as before. It creates a new entry in its database, and because the file content changed, the SHA-1 hash has also changed. When we do a git commit, Git recreates a new tree structure with a new SHA-1 hash:



@manekinekko/thundr
➜ git ls-tree main
...
040000 tree 2d56d5d1aa7fc5f2b4133f5c19088625a2a508db    src

@manekinekko/thundr
➜ git ls-tree 2d56d5d1aa7fc5f2b4133f5c19088625a2a508db
...
100644 blob 83a8d59dbac0603a0b108fadb20af24cb575ecca    index.html

Note that both SHA-1 hashes of src tree and index.html blob have changed because Git created a new tree structure that stores the new file content.

We can inspect again the content of the new stored blob and see the change we made (we added a thunder ⚡️ emoji in the title):



@manekinekko/thundr
git cat-file -p 83a8d59dbac0603a0b108fadb20af24cb575ecca
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Thundr ⚡️</title>
  <base href="/">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="icon" type="image/x-icon" href="favicon.ico">
</head>
<body>
  <app-root></app-root>
</body>
</html>

Next, let's rename that file to, e.g., src/index-2.html, and then commit that changes again. Interestingly, Git does not create a new entry in the database for this file because the content — and hence the SHA-1 hash — have not changed. However, the SHA-1 of the src tree is now different because Git created a new tree structure:



@manekinekko/thundr
➜ git ls-tree main | grep src
040000 tree c561e2cc7ad896d6880f47df384b19ddb0c602e6    src

@manekinekko/thundr
➜ git ls-tree c561e2cc | grep index-2.html
100644 blob 83a8d59dbac0603a0b108fadb20af24cb575ecca    index-2.html

As you can see, the SHA-1 hashes of both file names index.html and index-2.html are the same, and that's because their content is identical!



100644 blob 83a8d59dbac0603a0b108fadb20af24cb575ecca    index.html
100644 blob 83a8d59dbac0603a0b108fadb20af24cb575ecca    index-2.html

In order to track who saved the snapshots and where they are saved (which exact tree), Git stores this information in Commit objects.

Commit objects

A commit object keeps track of:

the hash of the top-level tree where the file snapshot is located
the hash of the parent commit (if any).
the author/committer's name extracted from the user.name and user.email configuration settings.
the timestamp of the commit.
the GPG signature of the commit (if any).
a blank line.
the commit message.

Git stores commit object as blobs. We can inspect the content of a commit object using the git cat-file command:



@manekinekko/thundr
➜ git cat-file -p cc5e291471deb4f264cbad64d8a6570ca1487e83
tree 9ac02461fe7c94c834d28efa54952e8953002ef0
author Wassim Chegham <github@wassim.dev> 1645222639 +0100
committer Wassim Chegham <github@wassim.dev> 1645222639 +0100
gpgsig -----BEGIN PGP SIGNATURE-----

 iQIzBAA...
 -----END PGP SIGNATURE-----

my first commit

Here's what's actually happening in Git's internal database:

Note that in this diagram, we are using the first 8 bits of the SHA-1 hashes to identify Tree, Blob and Commit objects. Those are enough!

As you may have guessed, Git does not really care about file names. It cares more about their content. Even if we copy a file, Git will not create a new entry in its database. It's just a matter of content and SHA-1 hashes.

And if you're wondering what does Git do when we run a git push? Git computes the delta between the two files, compresses that diff, and sends it to the server. Yes, Git does not send the whole file's content.

Voilà!

That was it! Now we know what Git does behind the shadow when we create, edit, commit, and push files.

Follow me on Twitter at @manekinekko for more content!

50+ FREE content for every developer!

Wassim Chegham — Wed, 18 Aug 2021 13:59:41 +0000

Here is a list of 50+ FREE resources for developers. It includes free learning content for:

✅ Git & GitHub
✅ Programming
✅ Python
✅ Go
✅ Rust
✅ JavaScript & Typescript
✅ Node.js
✅ AI/ML
✅ Docker & Kubernetes (k8s)
✅ Blockchain & Ethereum
✅ Quantum computing

Enjoy!

Introduction to GitHub

Learn to use key GitHub features, including issues, notifications, branches, commits, and pull requests.

Introduction to version control with Git

Git is the leading version control tool, and it's essential for developers. Learn how to use Git to track your own changes and collaborate with others.

Contribute to an open-source project on GitHub

Learn how to use GitHub to find open-source projects and tasks to contribute to. Discover how to create pull requests and communicate with project maintainers effectively to get your changes accepted...

Introduction to GitHub in Visual Studio Code

Learn to use the GitHub integration in Visual Studio Code, including authentication, publishing repos, and viewing your repo timeline.

Create and publish custom GitHub actions

Learn how to write your own GitHub actions and create custom workflows. Learn best practices for documenting your action, and how to publish your action to the GitHub Marketplace.

Create and host web sites by using GitHub Pages

Learn how to host your personal, organization, and project sites for free with GitHub Pages.

Implement a code workflow in your build pipeline by using Git and GitHub

Learn how to collaborate with others and merge only the highest quality code.

Introduction to programming

Learn about programming languages and the tools that developers use to create software.

Web Development for Beginners

Learn the basics of web development, including programming languages and tools, and web accessibility.

Build a simple website using HTML, CSS, and JavaScript

Get started with web development by learning how to use HTML, CSS, and JavaScript to build a website and to use developer tools in the browser to check your work.

JavaScript variables and data types

Learn about the types of variables and their data types, along with how you can use them in JavaScript programming.

JavaScript arrays and loops

Learn about the structural format and uses of arrays in JavaScript, and how loops can assist you with repetitive tasks involving the data within arrays.

Create modular code by using functions in JavaScript

Functions are the building blocks for any application you'll create. You can create named, reusable sections of code with functions to help make it more readable and maintainable.

Learn the basics of web accessibility

There are various tools and reports at your disposal that can highlight issues that need to be addressed. There are also standards like ARIA tags that will make your app usable by all.

Publish an Angular, React, Svelte, or Vue JavaScript app to the cloud

Automatically deploy and update a static web application from a GitHub repository.

Publish a serverless API with your JAMStack app

Publish an Angular, React, Svelte, or Vue JavaScript app and API with Azure Static Web Apps and Azure Functions. Deploy your code from GitHub to a staging site using preview URLs.

Authenticate users in your JAMStack app

Use Azure Static Web Apps and Azure Functions to authenticate users.

Get started with Vue

Vue.js is a progressive web framework that allows developers to get up and running quickly, with just the addition of a script tag. You can use it to create large scalable applications.

Develop web applications with Visual Studio Code

Learn how to develop apps with Visual Studio Code, and use its features to create and test a very simple web application.

Introduction to WebXR with Babylon.js

In this learning module, we'll introduce you to the core concepts of building Mixed Reality experiences with Babylon.js. We'll create a simple WebXR app that can be run cross-platform.

Build JavaScript applications with Node.js

Node.js provides a large set of built-in APIs that help you build various types of applications, command-line apps, web apps, and more...

Create a new Node.js project and work with dependencies

Use dependencies from the npm registry to develop Node.js applications faster. Learn how to manage dependencies for your project.

Build a web API with Node.js and Express

Use Express for Node.js to build RESTful APIs. Create and configure middleware to add things like logging and authentication/authorization.

Explore the art world by using RESTful APIs

Learn about how to build a basic API, how to query APIs, and authentication strategies in Python and JavaScript while discovering unique art by using museum APIs.

Define generics in TypeScript

Generics are code templates that you can define and reuse throughout your codebase. They provide a way to tell functions, classes, or interfaces what type you want to use when you call it.

Organize code using TypeScript namespaces

TypeScript provides two ways to organize code - namespaces and modules. This module explains how to organize TypeScript code using namespaces.

Declare variable types in TypeScript

Get an introduction to the types of space exploration problems that Python and data science can influence.

Introduction to Python for space exploration

Get an introduction to the types of space exploration problems that Python and data science can influence.

Set up your Python beginner development environment with Visual Studio Code

Get started with learning Python by installing and configuring the tools you'll need to build real applications.

Write basic Python in Notebooks

Learn the basics of Python using interactive Notebooks. Learn about some basic concepts of the Python programming language, using NASA as context to apply them. Actual engineers at NASA use these ideas everyday when working on projects.

Crack the code and reveal a secret with Python and Visual Studio Code

Get a glimpse into the popular Python programming language with this introductory lesson that requires no coding experience.

Use control flows in Go

Learn how to write programs in the Go way by using fundamental control flows like if/else, switches, and for as well as another set of keywords.

Write and test a program in Go

Learn step by step how to write a Go program, how to structure the files, how to compile the files, how to run the program, and how to test the program.

Use data types and structs, arrays, slices, and maps in Go

Learn about structs, arrays, slices, and maps. Understand the difference between them and when to use one type over the other.

Implement error handling and logging in Go

Understand how to handle errors and log helpful information in your Go programs.

What is Rust

A quick introduction to Rust language features and how Rust compares with other programming languages.

Take your first steps with Rust

Interested in learning a new programming language that's growing in use and popularity? Start here! Lay the foundation of knowledge you need to build fast and effective programs in Rust.

Understand common concepts in Rust

Learn the basics of Rust. Explore variables, data types, structs, enums, functions, indexing, hash maps, and flow control.

Set up the Rust development environment

Learn how to set up the Rust development environment, write a program, and use the Cargo build system.

Introduction to Docker containers

Describes the benefits of using Docker containers as a containerization platform. Discuss the infrastructure provided by the Docker platform.

Use a Docker container as a development environment with Visual Studio Code

Describes the benefits of using Docker containers as a containerization platform. Discuss the infrastructure provided by the Docker platform.

Introduction to Azure Kubernetes Service

Determine the types of business problems that can be solved using Kubernetes. Describe the benefits of container orchestration with features like deployment management, automatic updates, and self-healing.

Get started with AI

With AI, we can build solutions that seemed like science fiction a short time ago; enabling incredible advances in health care, financial management, environmental protection, and other areas to make a better world for everyone.

Build a machine learning model

In this free course, you focus on a local analysis of your data by using scikit-learn, and use a decision tree classifier to gain knowledge from raw weather and rocket launch data.

Introduction to PyTorch

Learn how to build machine learning models with PyTorch.

PyTorch Fundamentals

Learn the fundamentals of deep learning with PyTorch! This beginner-friendly free course will introduce key concepts to building machine learning models in multiple domains include speech, vision, and natural language processing.

Introduction to Computer Vision with PyTorch

Get an introduction to Computer Vision using one of the most popular deep learning frameworks, PyTorch! Learn about image classification tasks and convolutional neural networks.

Connect and deploy to Ethereum networks

Learn about and use Ethereum networks for development, testing, and production.

Introduction to blockchain

Discover how blockchain protocols enable trust. Learn to assess scenarios for when to use blockchain and decide if it's right for your solution.

Quantum computing foundations

7+ hours of FREE content about fundamental concepts of quantum computing.

Create your first Q# program by using the Quantum Development Kit

Get started with Q# programming by building a quantum random number generator.

Run algorithms on quantum hardware by using Azure Quantum

Get started with quantum computing on Azure Quantum and learn how to create and run Q# quantum programs on quantum computers in the cloud.

Have fun!

Feel free to reach out on Twitter at @manekinekko. You can also follow my work at wassim.dev.

10 Things To Know About Azure Static Web Apps 🎉

Wassim Chegham — Mon, 05 Jul 2021 13:35:13 +0000

Azure Static Web Apps allows any developer to build modern web
applications that are automatically published from changes made in the git repository, and much more...

Here are 10 things to know to get started with Azure Static Web Apps!

What's Azure Static Web Apps?

// Detect dark theme var iframe = document.getElementById('tweet-1377940310672695296-939'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1377940310672695296&theme=dark" }

What contents can be deployed to Azure Static Web Apps?

// Detect dark theme var iframe = document.getElementById('tweet-1377940315856908288-993'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1377940315856908288&theme=dark" }

Does Azure Static Web Apps support serverless APIs?

// Detect dark theme var iframe = document.getElementById('tweet-1377940320701284353-534'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1377940320701284353&theme=dark" }

How does Azure Static Web Apps work?

// Detect dark theme var iframe = document.getElementById('tweet-1377940326783025154-521'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1377940326783025154&theme=dark" }

What devtools does Azure Static Web Apps support?

// Detect dark theme var iframe = document.getElementById('tweet-1377940332554375170-384'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1377940332554375170&theme=dark" }

How about custom domain names?

// Detect dark theme var iframe = document.getElementById('tweet-1377940337000386563-171'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1377940337000386563&theme=dark" }

How to configure an Azure Static Web Apps app?

// Detect dark theme var iframe = document.getElementById('tweet-1377940343178559489-133'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1377940343178559489&theme=dark" }

What about local dev?

// Detect dark theme var iframe = document.getElementById('tweet-1377940351168708608-280'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1377940351168708608&theme=dark" }

Does Azure Static Web Apps support PR changes preview?

// Detect dark theme var iframe = document.getElementById('tweet-1377940357112070151-773'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1377940357112070151&theme=dark" }

How to secure apps with Azure Static Web Apps?

// Detect dark theme var iframe = document.getElementById('tweet-1377940363546071044-194'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1377940363546071044&theme=dark" }

Resources!

Deploy your favorite framework

Have fun!

Feel free to reach out on Twitter at @manekinekko if you want to get started with Azure Static Web Apps. You can also follow my work at wassim.dev.

The Subtle Art of Being A Developer Advocate | What is a Developer Advocate?

Wassim Chegham — Wed, 21 Apr 2021 10:32:00 +0000

A few years ago I wrote this article called "What the heck is a developer advocate?" which tried to help people in the tech industry understand what this role entails. Yet, I still get tons of questions on Twitter about this role.

What the heck is a Developer Advocate?

Wassim Chegham ・ Jun 1 '19

#devrel #discuss #career #writing

This article is also available in other languages

🇯🇵 Japanese

In this post, I am going to try to demystify the role of a Developer Advocate by giving, this time, concrete examples of tasks and activities I do on my day-to-day job working as a Senior Developer Advocate at Microsoft, and as someone who's been doing developer advocacy since 2015.

Disclaimer:

Views expressed in this post are my own and do not represent my employer nor my colleagues.

Let's first shed some light on the difference between a Developer Advocate and a Technology Evangelist.

Developer Advocate and Technology Evangelist

There is a certain confusion between Developer Advocacy and Technology Evangelism. Let's look at both terms' definitions.

According to Wikipedia, the term "tech evangelist" was invented by Apple as part of their initiative to persuade developers to create apps for Macintosh. The verb "persuade" is very important because it implies that an Evangelist would try to convince developers to adopt a certain technology without necessarily listening, or caring about their needs or opinion.

This is exactly the opposite of what Advocacy is all about!

"Advocacy" is an old concept that comes from the Medieval Latin word "advocare" which means "to add a voice". The term "advocate" comes from Old French word "avocat" which means "a lawyer". So, an Advocate literarily means someone who "pleads a case or a cause", who "argues that something needs to be changed or improved".

Applied to the tech industry, these two terms may seem quite similar but the subtle difference lies in the fact that a Tech. Evangelist role is done one-way only (outbound), and a Developer Advocate role is considered two-way (outbound and inbound). In other words, a Tech Evangelist would typically be interested in convincing developers that certain technology is what they need. A Developer Advocate would typically be interested in listening to developers' needs and providing them with the most adequate help. A Developer Advocate also collects developers' feedback and advocates for them internally.

This is why the two titles should be used wisely.

However, I want to take a step back to highlight that beyond the theoretical definition, it turns out that in practice there are always some exceptions to what the job titles may entail. I know some of my friends whose job title was Tech Evangelist, but the work they did was more of a Developer Advocate (and vice-versa). What really matters is not the job title but rather what you do to help developers be successful.

Developer Advocates and Marketers

Whenever you ask a Developer Advocate to define their role, each one of them will give you a different answer, which is confusing. That's common. But, have you ever wondered why? The main reason for this is that many companies tend to hire Developer Advocates to do different kinds of tasks, from sales to communication and, most commonly, Marketing. Why Marketing? Because companies usually spend between 5 to 12% of their revenue on Marketing, and when they need to reach to more developers, they usually would hire someone as a "Developer Advocate" (or any other variation of this title) who reports to marketing (or business unit) and is driven by marketing and sales KPIs (Key Performance Indicators). Most importantly, in this situation, this role is usually led outside of the product engineering team, which might be problematic (more on this below).

Don't get me wrong, there is nothing bad with companies using marketing and sales to reach out to developers, but doing this under the Developer Advocacy titles umbrella isn't doing anyone a favor. Either way, this usually turns out to be a bad move because not all developers are great at marketing (or sales) and end up not performing well. Developers have excellent ingenuity and creativity but some of us may lack basic business marketing skills. Why do you think most successful startups are founded by at least 2 people? If I were good at Marketing or Sales I would have done a better job promoting my own open-source projects, yet you've never heard about xlayers.dev. Do you?

When reaching to developers, Marketing teams should collaborate with Developer Advocates to help them tailor the message for developers. Why? Because Developer Advocates are, before anything else, developers themselves and speak the same language as other developers.

In many other cases, companies simply ignore the true meaning behind Advocacy and end up making their own definition, based on their business needs. That's why almost no Developer Advocate understands what their role is or should be. I hope this article would help somehow!

Developer Advocates and Developer Relations

Put simply, Developer Relations is the umbrella term for the teams including Developer Advocates, Community Managers, and any team whose responsibility is to create and foster communities of developers. Some larger companies, as we do at Microsoft, also include teams responsible for documentation, events, and social media.

So, a Developer Advocacy team is a tiny subset of Developer Relations.

What's my role at Microsoft?

As Developer Advocates, we may not agree on what we do or should be doing, but we all agree on one common definition:

"Our role is to act as the bridge between internal engineering teams and our developer community. We also advocate for developers internally".

Before I describe the work I do at Microsoft, let me give you some context: I was hired because of my JavaScript skills and my close relationship with the JavaScript developer community. I currently work as part of the JavaScript advocacy team. Our team belongs to the Developer Relation organization which is part of the Azure Engineering department at Microsoft.

My day-to-day job is to advocate for JavaScript developers internally at Microsoft, act as their voice during product team meetings or internal studies. Externally, I support and gather JavaScript developers' feedback so we can improve our products and services. Basically, I help JavaScript developers be successful using Microsoft Clouds, services, and open-source developer tools.

You've probably seen that Microsoft is raising the bar for its products and to achieve this, the company is investing in Developers and open-source. That's why our Developer Relations team's mission is to empower developers to achieve more. Our larger Developer Advocacy team (or Cloud Developer Advocacy, as we refer to it internally because we are also helping DevOps teams) is composed of multiple sub-teams focusing on different developer communities such as Rust, Java, Python...etc, but also audiences like students, academia, and startups.

The mission of the Cloud Developer Advocacy team is to win the hearts and minds of Developers through authenticity, community, and technical engagement.

What my typical day looks like as a Developer Advocate?

The tasks I am going to disclose below are the activities "I" regularly do. My team members may or may not do the "exact" same activities.

Creating content

I participate in writing technical documentation and content in different formats used by engineers worldwide. This can be as simple as updating existing documentation or creating full documentation like the Azure Static Web Apps documentation that my team and I collaborated on with the Microsoft documentation team.

Other content also includes creating and hosting workshops for developers, coding challenges as well as snackable content that I regularly publish on Twitter.

Here are a couple of recent examples:

// Detect dark theme var iframe = document.getElementById('tweet-1377940304712585217-576'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1377940304712585217&theme=dark" }

And this one:

// Detect dark theme var iframe = document.getElementById('tweet-1281704000572858375-695'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1281704000572858375&theme=dark" }

Public speaking

Probably one of the highly visible activities that most Developer Advocates are notorious for is public events. That's also part of my work, giving technical talks, and keynotes at international conferences and events. Basically going where the developers are. This also includes live streamings, podcasts, and similar types of mediums.

Building tools in the open

Besides the work I do for my company, I am also an active member of the open-source community, and most of the work I do for my employer is done in the Open as well. This means that my job is also to help developers be successful using the tools that help them use and integrate Azure with their products and applications. My recent tools include https://www.hexa.run, the Nest.JS libraries for Azure CosmosDB, and Azure Storage. You can check my other open-source work at wassim.dev.

Product feedback

Continuously improving the products and services that developers use is one of our team's core missions. I spend the majority of my time interacting with developers and engineers through social media, or at online or onsite events. I get tons of requests from developers who are asking questions, reporting issues, or asking for feature requests. I always try to help them first, if I am familiar with the product. For major issues or popular feature requests, I create a work item on our internal dashboard and collaborate closely with the product team to improve the experience based on the feedback gathered from the community.

This is really where, as a Developer Advocate, I can advocate for JavaScript developers and act as their voice internally. A recent example of this is with the Azure Static Web Apps product where I spent the last year and a half contributing to the product and helping the engineering team designing part of the service, providing critical feedback, trying early access features, and implementing the CLI developer tool.

Shipping products

One other aspect of being a Developer Advocate that many people probably ignore is that as Developer Advocates, some of us also contribute to creating and shipping products, either for internal or external use, or both. For the last 6 months, I had the opportunity to create, lead and ship the official Azure Static Web Apps CLI to allow developers to run and debug their apps locally.

I think that's something that every Developer Advocate should be doing because it's essential to understand how a product or a service is designed, implemented, know its strengths and weaknesses. That a knowledge that we will have to have if we need to better help developers.

Being the Customer Zero

A good amount of my time is spent improving Azure products and services, and working with Azure engineering teams across the company to try out new features, provide feedback about JavaScript developers' expectations. The products I've worked on during the last 2 years were: Azure Functions, Azure Storage, Azure Cosmos DB, Azure IoT, Azure Static Web Apps, GitHub Codespaces, and npm. Acting as "customer zero" is a really great way to have a tremendous impact on a product before it gets released. One example of this is Azure Static Web Apps: my team and I are working closely with the engineering team to help provide the best developer experience for the Web developers community who will be using this service.

Constantly learning

Since JavaScript is widely used in many different areas, the technical stacks that I usually focus on include Node.js, TypeScript, Serverless, IoT architectures, databases, and hosting. I also must be honest, I've also been fascinated by the Rust programming language and I am planning to start learning it in the near future! Luckily my colleagues on the Rust Developer Advocacy team have built this 5 hours free guide about Rust for beginners. It looks like a good start for me!

Creating and improving official docs

As a Developer Advocate, I also spend some time creating comprehensive technical guides for many Microsoft Clouds services. One of the latest guides that my team and I worked on for 4 months is the Node.js Learn Path. The good thing about our official documentation is that is open and anyone can help improve it. We also regularly participate in this and send Pull Requests to improve and update the docs at http://docs.microsoft.com.

Helping others grow

Another aspect of my job – well it's not part of my job description per se – but it's really important to me: that's helping people around me grow and be successful. As someone from a minority group, who's succeeded in the tech industry, I genuinely care about diversity and inclusion. So helping others grow professionally and personally is part of who I am.

I do internal mentoring through an official mentorship program at Microsoft. Externally, I am mentoring people from the community who are new to programming and want to switch careers, and also people who want to start contributing to open-source. I obviously can't disclose all the details but I basically help and advise my mentees about programming, tech, and career growth.

Business and OKRs

Let me just be clear, every company's goal is to do business. Your company isn't simply paying you to work on open-source, or travel to events. It's investing money in you and is expecting an ROI (Return on investment). But we all know that the ROI of a community and relationship building is not that easy to measure or quantify.

We are continuously reviewing and updating our team's OKRs (Objectives & Key Results), strategy, and planning to align with the company's broader strategy while giving everyone on the team the freedom to connect with developers in authentic ways, have meaningful conversations, help them solve their problems, and being their advocate.

Final thoughts

Engineers' main responsibilities are to own, design, implement, and ship products, and for those who want to share their experience with the developer community, they are able to do it. Developer Advocates are not different than engineers except that their responsibilities are not working full time on products but help the engineering teams reach out and listen to developers' needs in order to create the best experience for everyone.

Developer Advocates are engineers who love to learn in the open.

That’s my story. If you like or agree with what you've just read, our team is hiring. Check out our page https://aka.ms/awesomejobs ❤️

Bonus: The Developer Advocate Iceberg

Feel free to reach out on Twitter at @manekinekko if you are still curious about Developer Advocacy. You can also follow my work at wassim.dev.

Assets used in this blog are licensed under the Adobe Standard License.

Introducing: Open Web Docs!

Wassim Chegham — Fri, 29 Jan 2021 21:06:49 +0000

Open Web Docs is a new collective project between Google, Microsoft, Mozilla, Coil, W3C, Samsung, and Igalia, to support the creation and maintenance of strategic web platform documentation.

Open Web Docs is dedicated to supporting browser-agnostic, community-driven, and high-quality web developer documentation. This new initiative is not a new documentation site, instead, Open Web Docs is committed to improving existing platforms through many different community contributions.

// Detect dark theme var iframe = document.getElementById('tweet-1353748877111918593-977'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1353748877111918593&theme=dark" }

Open Web Docs collaborators are supported by sponsors like Coil, Google and Microsoft, Igalia, and many other donors on Open Collective.

Open Web Docs long term roadmap will be published soon. However, the initial goals are focused on supporting MDN's recent infrastructure transition and contributing to core web technology documentation, browser compatibility data, and JavaScript documentation on MDN Web Docs.

You can learn more or join the adventure at the Open Web Docs collective page, on GitHub, or by following @OpenWebDocs for more exciting updates.

Build a DIY teleprompter for under $20 in less than 20min

Wassim Chegham — Tue, 27 Oct 2020 15:16:11 +0000

I am not really good at memorising scripts while recording videos of me talking to a camera. I usually spend hours recording multiple shots just to get 2 min of a video done right!

I tweeted about this recently:

// Detect dark theme var iframe = document.getElementById('tweet-1318153290249625602-184'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1318153290249625602&theme=dark" }

After publishing this tweet, my friend Alexis responded:

// Detect dark theme var iframe = document.getElementById('tweet-1318154652572147714-656'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1318154652572147714&theme=dark" }

He actually knows me well, because that what exactly I had in mind. I like to build stuff! So let's build a cheap teleprompter, for under $20, in 20 minutes or less.

By the way, here is the final result (in a video):

// Detect dark theme var iframe = document.getElementById('tweet-1319251368666947585-885'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1319251368666947585&theme=dark" }

What's a teleprompter?

According to Wikipedia: "A teleprompter, also known as an autocue, is a display device that prompts the person speaking with an electronic visual text of a speech or script."

Because a picture is worth a thousand words, I made a simple drawing explaining how a teleprompter works:

Components you will need

x2 wooden pictures frames with clear glass

From your local hardware store, buy 2 wooden picture frames. Make sure the frames are in wood and the glazing is a clear glass (not plastic). The backing board should be a solid wood (but this is not mandatory). Also, the picture frames should be large enough to hold your monitor/tablet/phone or any device that you will use as a display. Mines were large enough to hold an iPad Pro. But you can choose any other format.

x3 pairs of solid brass butt hinges

You will also need 2 or 3 pairs of solid brass butt hinges that we will use to hold the 2 frames together. My frames are 24x30 cm (9x11"), so I used 3 pairs of 25mm hinges.

Make sure the screws that come with the hinges are not too long so they don't pass all the way through the frames!

A dark piece of sheet

We will need a dark piece of sheet to protect the teleprompter glass against any reflections coming from our light sources.

The rest...

Next, you will need:

A piece of small wood or a wooden stick.
A black aerosol spray paint can.
Your usual camera setup.
A device with a screen. This could be a tablet, a phone or an external monitor connected to a computer.
A teleprompter app (with "mirror" support).

How-to...

1- Carefully disassemble the picture frames. Keep only 1 glazing panel and 1 baking board (and the 2 frames, obviously!). You can get rid of all the other components or use then as spare parts.

2- After you removed the glass panel, put it in a secure place, we will use it later. Now, hold the 2 frames together "like a closed book" and place the hinges on one of the sides. Make sure to place frame A on top of frame B, with both frames facing down (see figure):

WHY? Inside the frame B, we will place our screen/tablet which will sit on the baking board. Frame A will be placed on top of frame B, with the glass facing down, and tilted at 45 degrees, like an open book.

3- Once you marked where the hinges are going to be placed, drill very tiny holes that will hold the screws.

4- Then, tightly screw all 3 hinges.

5- If some of the components are in white or any other clear color, paint them all in black so that all components (except the glass) are dark. This would help absorbe any lighting coming from our light sources.

Note: I painted both back panels just to in case I needed a spare one!

6- Once all components are painted and dried, place the glazing panel back on frame A, and the back panel on frame B.

7- We are almost done. Using a small stick of wood (or any other item that you have on hand). Frame A should be tilted at 45 degrees, but feel free to adjust to your convenience.

8- If you have any light sources placed behind the camera, you would see reflections on the glazing panel on frame A.

9- To avoid this, place a dark piece of sheet between the camera and the back of frame A.

10- Lastly, place your screen/tablet/monitor inside frame B with the screen facing up, and bump up the brightness. Open your teleprompter app and adjust the text size. Make also sure to turn on the "mirror" mode, or you can practice reading reverse text (😂)!

Note: you can skip steps 2-4 if you can buy an already hinged picture frame with glass front!

Congratulations!

You just built your DIY teleprompter! Congratulations!

Please share your creations and show us how is your teleprompter look like.

Follow me at @manekinekko for more hacks and DIY tutorials.