> ## Documentation Index
> Fetch the complete documentation index at: https://amd-gaia.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Build and run GAIA C++ agents — full agent loop and MCP integration

**The GAIA C++ agent framework.** Drop AI agent capabilities into any C++ project — three lines of CMake, zero manual dependencies, any OpenAI-compatible LLM backend.

* **Native performance** — compiled binary, no interpreter overhead
* **Easy integration** — add to any CMake project via FetchContent, git submodule, or find\_package ([Integration Guide](/docs/cpp/integration))
* **Any LLM backend** — works with [Lemonade](https://lemonade-server.ai), llama.cpp, Ollama, vLLM, OpenAI, or any OpenAI-compatible server ([details](/docs/cpp/integration#using-alternative-llm-backends))
* **Full MCP support** — connects to any MCP server via stdio transport
* **Full agent loop** — planning, tool execution, error recovery, multi-step plans

<Info>
  **Source Code:** [`cpp/`](https://github.com/amd/gaia/tree/main/cpp) in the GAIA repository. The C++ framework focuses on the core agent loop and tool execution. Specialized agents (Code, Docker, Jira, Blender), the REST API server, RAG, and audio are available in the [Python SDK](/docs/quickstart).
</Info>

***

<Info>
  **First time here?** Complete the [C++ Setup](/docs/cpp/setup) guide first to install CMake, a C++17 compiler, and [Lemonade Server](https://lemonade-server.ai).
</Info>

## Build

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/amd/gaia.git
    cd gaia/cpp
    ```
  </Step>

  <Step title="Configure and build">
    <Tabs>
      <Tab title="Windows (MSVC)">
        ```bat theme={null}
        cmake -B build -G "Visual Studio 17 2022" -A x64
        ```

        ```bat theme={null}
        cmake --build build --config Release
        ```

        Binaries land in `build\Release\`.
      </Tab>

      <Tab title="Windows (Ninja)">
        ```bat theme={null}
        cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
        ```

        ```bat theme={null}
        cmake --build build
        ```
      </Tab>

      <Tab title="Linux">
        ```bash theme={null}
        cmake -B build -DCMAKE_BUILD_TYPE=Release
        ```

        ```bash theme={null}
        cmake --build build
        ```

        Binaries land in `build/`.
      </Tab>
    </Tabs>

    All dependencies (nlohmann/json, cpp-httplib, Google Test) are fetched automatically by CMake — no manual installs required.
  </Step>

  <Step title="Start an LLM server">
    The agent connects to any OpenAI-compatible LLM server at `http://localhost:13305/api/v1` by default. The recommended backend is [Lemonade Server](https://lemonade-server.ai) (optimized for AMD hardware):

    ```bash theme={null}
    lemonade-server serve
    ```

    <Note>
      **Not using Lemonade?** Any OpenAI-compatible server works — llama.cpp, Ollama, vLLM, or a cloud endpoint. Just set `AgentConfig::baseUrl` and `AgentConfig::modelId`. See the [Integration Guide](/docs/cpp/integration#using-alternative-llm-backends) for configuration examples.
    </Note>
  </Step>

  <Step title="Run a demo agent">
    Both demo agents are Windows-only (they use PowerShell for system interaction).

    **[Windows System Health Agent](/docs/cpp/health-agent)** (requires `uvx` for the MCP server):

    ```bat theme={null}
    build\Release\health_agent.exe
    ```

    The agent connects to the Windows MCP server, gathers CPU/memory/disk/GPU metrics via PowerShell, and presents results in the console or writes a full report to Notepad.

    **[Wi-Fi Troubleshooter](/docs/cpp/wifi-agent)** (no extra dependencies, run as admin for fix tools):

    ```bat theme={null}
    build\Release\wifi_agent.exe
    ```

    Select GPU or NPU backend, then try "Full network diagnostic" or ask a specific question. The agent reasons about each result and adapts its approach in real-time.

    **Vision-Language (VLM) demo** (cross-platform — requires a VLM model such as `Qwen3-VL-4B-Instruct-GGUF` loaded on the server):

    ```bash theme={null}
    ./build/vlm_agent path/to/image.png "Describe this image."
    ```

    See [API Reference: Vision Language Models](/docs/cpp/api-reference#vision-language-models-vlm) for the `gaia::Image` and `processQuery(..., images)` APIs.

    Type `quit` to exit.
  </Step>
</Steps>

## Running Tests

Verify your build with the unit test suite (no LLM server required):

<Tabs>
  <Tab title="Windows">
    ```bat theme={null}
    build\Release\tests_mock.exe --gtest_color=yes
    ```
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    ./build/tests_mock --gtest_color=yes
    ```
  </Tab>
</Tabs>

See the [Testing Guide](/docs/cpp/testing) for the full test suite — unit tests (20 modules), integration tests (LLM, MCP, Wi-Fi, Health, VLM), CI pipeline, and how to add new tests.

## Next Steps

<CardGroup cols={2}>
  <Card title="System Health Agent" icon="desktop" href="/docs/cpp/health-agent">
    MCP-based system diagnostics — CPU, memory, disk, GPU via PowerShell
  </Card>

  <Card title="Wi-Fi Troubleshooter" icon="wifi" href="/docs/cpp/wifi-agent">
    Full network diagnostic and auto-fix using registered C++ tools
  </Card>

  <Card title="Framework Overview" icon="book" href="/docs/cpp/overview">
    Architecture, agent execution flow, how tools work, and project structure
  </Card>

  <Card title="Integration Guide" icon="puzzle-piece" href="/docs/cpp/integration">
    Add gaia\_core to your own CMake project via FetchContent, find\_package, or shared library
  </Card>

  <Card title="Testing Guide" icon="flask-vial" href="/docs/cpp/testing">
    Unit tests, integration tests, CI pipeline, and adding new tests
  </Card>

  <Card title="API Reference" icon="book-open" href="/docs/cpp/api-reference">
    Error handling, thread safety, security, deployment, and complete class API
  </Card>

  <Card title="Custom Agent" icon="sliders" href="/docs/cpp/custom-agent">
    Custom prompts, typed tools, MCP servers, output capture, and AgentConfig tuning
  </Card>
</CardGroup>

***

<small style="color: #666;">
  **License**

  Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.

  SPDX-License-Identifier: MIT
</small>