Merge pull request #424 from ag-ui-protocol/feature/landing-page-overview

New landing page

easier access
new intro text and feature explanations
diagrams and dojo video
feature overview
framework links updated
Some technical content moved from this page to Core Architecture

Author: johnprg

docs/ag_ui.md

@@ -0,0 +1,91 @@
+# AG‑UI: The Agent–User Interaction Protocol
+
+*A horizontal standard to bring AI agents into user‑facing frontend applications.*
+
+AG‑UI is the boundary layer where agents and users meet. It standardizes how agent state, UI intents, and user interactions flow between your model/agent runtime and your app’s frontend—so you can ship reliable, debuggable, user‑friendly agentic features fast.
+
+---
+
+## Built with the ecosystem
+
+**First‑party partnerships & integrations**
+
+> **Logo strip goes here** (e.g., LangGraph • CrewAI • Autogen 2 • LlamaIndex • Mastra • Pydantic AI • Vercel AI SDK • Next.js)
+
+Short blurb: *AG‑UI works across leading agent frameworks and frontend stacks, with shared vocabulary and primitives that keep your UX consistent as your agents evolve.*
+
+---
+
+## Building blocks (today & upcoming)
+
+- **Streaming chat** — Token‑level and tool‑event streaming for responsive UIs.
+- **Static generative UI** — Render model output into stable, typed components.
+- **Declarative generative UI** — Let agents propose UI trees; app decides what to mount.
+- **Frontend tools** — Safe, typed tool calls that bridge agent logic to app actions.
+- **Interrupts & human‑in‑the‑loop** — Pause, approve, edit, or steer mid‑flow.
+- **In‑chat + in‑app interactions** — Chat commands alongside regular app controls.
+- **Attachments & multimodality** — Files, images, audio, and structured payloads.
+- **Thinking steps** — Expose summaries/redactions of chain‑of‑thought artifacts to users, safely.
+- **Sub‑agent calls** — Orchestrate nested agents and delegate specialized tasks.
+- **Agent steering** — Guardrails, policies, and UX affordances to keep agents on track.
+
+> **CTA to deeper docs** → *See the full capability map in the docs.*
+
+---
+
+## Design patterns
+
+Explore reusable interaction patterns for agentic UX:
+
+- **Link‑out:** [AI‑UI Design Patterns →](/patterns) *(placeholder URL)*
+
+---
+
+## Why AG‑UI
+
+**Agentic apps break the classic request/response contract.** Agents run for longer, stream work as they go, and make nondeterministic choices that can affect your UI and state. AG‑UI defines a clean, observable boundary so frontends remain predictable while agents stay flexible.
+
+### What’s hard about user‑facing agents
+
+- Agents are **long‑running** and **stream** intermediate work—often across multi‑turn sessions.
+- Agents are **nondeterministic** and can **control UI** in ways that must be supervised.
+- Apps must mix **structured + unstructured IO** (text, voice, tool calls, state updates).
+- Agents need **composition**: agents **call sub‑agents**, often non-deterministically.
+
+With AG‑UI, these become deliberate, well‑typed interactions rather than ad‑hoc wiring.
+
+---
+
+## Deeper proof (docs, demos, code)
+
+| Framework / Platform    | What works today                       | Docs      | Demo      |
+| ----------------------- | -------------------------------------- | --------- | --------- |
+| LangGraph               | Streams, tools, interrupts, sub‑agents | [Docs](#) | [Demo](#) |
+| CrewAI                  | Tools, action routing, steering        | [Docs](#) | [Demo](#) |
+| Autogen 2               | Multi‑agent orchestration, messaging   | [Docs](#) | [Demo](#) |
+| LlamaIndex              | Query/agent routing, UI intents        | [Docs](#) | [Demo](#) |
+| OpenAI Realtime         | Live stream, events, attachments       | [Docs](#) | [Demo](#) |
+| Vercel AI SDK / Next.js | Edge streaming, SSR hydration          | [Docs](#) | [Demo](#) |
+
+> **Note:** Replace placeholders with actual URLs to docs and demos.
+
+---
+
+## Quick links
+
+- **Get started** → */docs/getting-started* (placeholder)
+- **Concepts** → */docs/concepts/agent-ui-boundary* (placeholder)
+- **Reference** → */docs/reference* (placeholder)
+- **Patterns** → */patterns* (placeholder)
+
+---
+
+## Optional section: How AG‑UI fits
+
+- **Protocol**: Events, intents, and payload schemas shared by agents & apps.
+- **Runtime adapters**: Bindings for popular agent frameworks.
+- **Frontend kit**: Lightweight client + components to handle streaming & interrupts.
+- **Observability hooks**: Surface interaction timelines for debugging & learning.
+
+*(Include a simple diagram later: Agent(s) ⇄ AG‑UI Boundary ⇄ App UI/State)*
+

docs/concepts/architecture.mdx

@@ -8,7 +8,35 @@ architecture that enables seamless, efficient communication between front-end
 applications and AI agents. This document covers the core architectural
 components and concepts.
 
-## Overview
+## Design Principles
+
+AG-UI is designed to be lightweight and minimally opinionated, making it easy to
+integrate with a wide range of agent implementations. The protocol's flexibility
+comes from its simple requirements:
+
+1. **Event-Driven Communication**: Agents need to emit any of the 16
+   standardized event types during execution, creating a stream of updates that
+   clients can process.
+
+2. **Bidirectional Interaction**: Agents accept input from users, enabling
+   collaborative workflows where humans and AI work together seamlessly.
+
+The protocol includes a built-in middleware layer that maximizes compatibility
+in two key ways:
+
+- **Flexible Event Structure**: Events don't need to match AG-UI's format
+  exactly—they just need to be AG-UI-compatible. This allows existing agent
+  frameworks to adapt their native event formats with minimal effort.
+
+- **Transport Agnostic**: AG-UI doesn't mandate how events are delivered,
+  supporting various transport mechanisms including Server-Sent Events (SSE),
+  webhooks, WebSockets, and more. This flexibility lets developers choose the
+  transport that best fits their architecture.
+
+This pragmatic approach makes AG-UI easy to adopt without requiring major
+changes to existing agent implementations or frontend applications.
+
+## Architectural Overview
 
 AG-UI follows a client-server architecture that standardizes communication
 between agents and applications: