adds documentation for agno

ai-agents.mdx

@@ -58,9 +58,11 @@ With model-agnostic flexibility, CometChat AI Agents let you upgrade your AI sta
 
       <CardGroup cols={4} className="mt-4">
         <Card title="Mastra" icon={<img src="/docs/images/icons/mastra.svg" alt="Mastra" />} href="/ai-agents/mastra" horizontal />
-        <Card title="LangGraph" icon={<img src="/docs/images/icons/lang-graph.svg" alt="LangGraph" />} horizontal>Coming Soon</Card>
-        <Card title="Agno" icon={<img src="/docs/images/icons/agno.svg" alt="Agno" />} horizontal>Coming Soon</Card>
-        <Card title="CrewAI Flows" icon={<img src="/docs/images/icons/crew-ai.svg" alt="CrewAI Flows" />} horizontal>Coming Soon</Card>
+        {/* <Card title="LangGraph" icon={<img src="/docs/images/icons/lang-graph.svg" alt="LangGraph" />} horizontal>Coming Soon</Card> */}
+        <Card title="Agno" icon={<img src="/docs/images/icons/agno.svg" alt="Agno" />} href="/ai-agents/agno" horizontal />
+        {/* <Card title="CrewAI Flows" icon={<img src="/docs/images/icons/crew-ai.svg" alt="CrewAI Flows" />} horizontal>Coming Soon</Card> */}
+        <Card title="Vercel" icon={<img src="/docs/images/icons/vercel.svg" alt="Vercel" />} href="/ai-agents/vercel" horizontal />
+        <Card title="AG2" icon={<img src="/docs/images/icons/ag2.svg" alt="AG2" />} href="/ai-agents/ag2" horizontal />
       </CardGroup>
       <p className="text-gray-500 text-sm mt-3">More providers coming…</p>
     </Step>

ai-agents/agno-knowledge-agent.mdx

@@ -0,0 +1,160 @@
+---
+title: "Build Your Knowledge Agent with Agno"
+sidebarTitle: "Knowledge Agent"
+description: "Spin up an Agno-powered knowledge agent with FastAPI, ingest docs into namespaces, and stream grounded answers (with citations) into CometChat."
+---
+
+Imagine a FastAPI service that ingests your documentation, stores it in a vector database, and streams Agno agent responses with citations that CometChat can consume in real time.
+
+***
+
+## What You'll Build
+
+* An **Agno** agent that joins conversations as a documentation expert.
+* An ingestion pipeline that writes markdown artifacts into `knowledge_agent/data/knowledge/<namespace>`.
+* Retrieval and answering logic that always cites the sources it used.
+* A `/stream` endpoint that outputs newline-delimited JSON events so CometChat can subscribe without changes.
+
+***
+
+## Prerequisites
+
+* Python 3.10 or newer (3.11 recommended).
+* `OPENAI_API_KEY` with access to GPT-4o or any compatible model.
+* Optional: alternate OpenAI base URL or model IDs if you self-host OpenAI-compatible APIs.
+* curl or an API client (Hoppscotch, Postman) to call the FastAPI endpoints.
+
+***
+
+## Quick links
+
+- Repo root: [ai-agent-agno-examples](https://github.com/cometchat/ai-agent-agno-examples)
+- Project folder: [`knowledge_agent/`](https://github.com/cometchat/ai-agent-agno-examples/tree/main/knowledge_agent)
+- Server guide: [`README.md#knowledge-agent`](https://github.com/cometchat/ai-agent-agno-examples#knowledge-agent)
+- API reference: [`knowledge_agent/main.py`](https://github.com/cometchat/ai-agent-agno-examples/blob/main/knowledge_agent/main.py)
+- Knowledge helpers: [`knowledge_agent/knowledge_manager.py`](https://github.com/cometchat/ai-agent-agno-examples/blob/main/knowledge_agent/knowledge_manager.py)
+
+***
+
+## How it works
+
+This example recreates the Vercel knowledge base workflow using Agno:
+
+- **Ingest** — `collect_documents` accepts URLs, markdown, plain text, uploads, or multipart forms. Sources are deduplicated by a SHA-256 hash and normalized into markdown.
+- **Store** — `KnowledgeManager` keeps one `ChromaDb` collection per namespace, with metadata persisted under `knowledge_agent/data/knowledge/<namespace>`.
+- **Retrieve** — Searches hit the vector DB via Agno's `Knowledge` class, returning ranked snippets and the metadata used for citations.
+- **Answer** — `create_agent` enables `search_knowledge` and `add_knowledge_to_context`, forcing every response to cite sources via the system prompt.
+- **Stream** — `/stream` emits newline-delimited JSON events (`text_delta`, `tool_*`, `text_done`, `done`, `error`) that match CometChat’s Bring Your Own Agent expectations. Every event echoes the caller’s `thread_id` and `run_id`.
+
+***
+
+## Setup
+
+<Steps>
+  <Step title="Clone & install">
+    <code>git clone https://github.com/cometchat/ai-agent-agno-examples.git</code>, then inside the repo run:<br/><code>python3 -m venv .venv && source .venv/bin/activate && pip install -e .</code>
+  </Step>
+  <Step title="Configure environment">
+    Create <code>.env</code> (or export env vars) with at least <code>OPENAI_API_KEY</code>. Optional overrides: <code>OPENAI_BASE_URL</code>, <code>KNOWLEDGE_OPENAI_MODEL</code>, <code>KNOWLEDGE_STORAGE_PATH</code>, <code>KNOWLEDGE_CHROMA_PATH</code>.
+  </Step>
+  <Step title="Start the server">
+    Launch FastAPI with <code>uvicorn knowledge_agent.main:app --host 0.0.0.0 --port 8000 --reload</code>. The app exposes health, ingestion, search, generate, and `/stream` endpoints (newline-delimited JSON).
+  </Step>
+</Steps>
+
+***
+
+## Project Structure
+
+- FastAPI & wiring
+  - [`knowledge_agent/main.py`](https://github.com/cometchat/ai-agent-agno-examples/blob/main/knowledge_agent/main.py)
+  - [`knowledge_agent/schemas.py`](https://github.com/cometchat/ai-agent-agno-examples/blob/main/knowledge_agent/schemas.py)
+  - [`knowledge_agent/config.py`](https://github.com/cometchat/ai-agent-agno-examples/blob/main/knowledge_agent/config.py)
+- Knowledge + ingestion
+  - [`knowledge_agent/knowledge_manager.py`](https://github.com/cometchat/ai-agent-agno-examples/blob/main/knowledge_agent/knowledge_manager.py)
+  - [`knowledge_agent/ingestion.py`](https://github.com/cometchat/ai-agent-agno-examples/blob/main/knowledge_agent/ingestion.py)
+  - [`knowledge_agent/data/`](https://github.com/cometchat/ai-agent-agno-examples/tree/main/knowledge_agent/data)
+- Constants & helpers
+  - [`KnowledgeAgentSettings`](https://github.com/cometchat/ai-agent-agno-examples/blob/main/knowledge_agent/config.py#L7)
+  - [`collect_documents`](https://github.com/cometchat/ai-agent-agno-examples/blob/main/knowledge_agent/ingestion.py#L147)
+  - [`KnowledgeManager.create_agent`](https://github.com/cometchat/ai-agent-agno-examples/blob/main/knowledge_agent/knowledge_manager.py#L101)
+
+***
+
+## Step 1 - Configure the Knowledge Agent
+
+`KnowledgeManager.create_agent` builds an Agno agent bound to the current namespace:
+
+- Uses `OpenAIChat` with `OPENAI_API_KEY`, optional custom base URL, and temperature from settings.
+- Enables `search_knowledge=True` and `add_knowledge_to_context=True` so retrieved snippets feed the model.
+- Injects a system prompt that demands a knowledge search before every reply and enforces the `"Sources: <file>.md"` footer.
+- Reuses the namespace-specific `ChromaDb` collection initialised in `_get_namespace`.
+
+***
+
+## Step 2 - Ingest Knowledge
+
+`POST /api/tools/ingest` accepts JSON or multipart payloads. Highlights:
+
+- Up to 30 sources per call, 6 MB per file, 200 kB per inline text/markdown.
+- URLs, PDFs, HTML pages, plain text, and uploads are normalized to markdown with metadata and timestamps.
+- Duplicate hashes are skipped with a `"duplicate-content"` reason; existing files return `"already-ingested"`.
+- Responses provide `saved`, `skipped`, `errors`, and the resolved namespace.
+
+Example JSON payload:
+
+```bash
+curl -X POST http://localhost:8000/api/tools/ingest \
+  -H "Content-Type: application/json" \
+  -d '{
+        "namespace": "default",
+        "sources": [
+          { "type": "url", "value": "https://docs.agno.com/concepts/agents/overview" },
+          { "type": "markdown", "title": "Playbook", "value": "# Notes\n\nAgno rocks!" }
+        ]
+      }'
+```
+
+***
+
+## Step 3 - Search & Validate
+
+`POST /api/tools/searchDocs` lets you confirm retrieval before opening the agent to users:
+
+- Required body: `{"query": "How do I add tools?"}` with optional `namespace` and `max_results`.
+- Returns ranked snippets with metadata (hashes, distances converted to scores).
+- Empty queries immediately return an error so the UI can prompt the operator.
+
+***
+
+## Step 4 - Chat & Stream
+
+- `POST /api/agents/knowledge/generate` handles non-streaming responses.
+- `POST /stream` streams newline-delimited JSON events that include tool calls, intermediate reasoning, text deltas, and completion markers.
+
+Streaming example (newline-delimited JSON):
+
+```bash
+curl -N http://localhost:8000/stream \
+  -H "Content-Type: application/json" \
+  -d '{
+        "thread_id": "thread_1",
+        "run_id": "run_001",
+        "messages": [
+          { "role": "user", "content": "Summarize the agent lifecycle." }
+        ]
+      }'
+```
+
+Each line is a JSON object with a `type` field such as `text_delta`, `tool_call_start`, `tool_result`, `text_done`, or `done`. `thread_id` and `run_id` are echoed back so CometChat can correlate partial events.
+
+***
+
+## Step 5 - Connect to CometChat
+
+- Deploy the FastAPI service behind HTTPS (e.g., Fly.io, Render, Railway, or your own Kubernetes cluster).
+- Add auth headers or gateway middleware if you need to validate incoming requests from CometChat.
+- In the CometChat dashboard, point the Agno agent’s **Deployment URL** at the `/stream` endpoint; use **Headers** for bearer tokens or basic auth if required.
+- Provide `namespace` (or `toolParams.namespace` from CometChat) when you need to target non-default knowledge stores; the service normalizes values before lookup.
+
+With that, you have a fully grounded Agno agent that streams CometChat-compatible events into your UI.

ai-agents/agno-product-hunt-agent.mdx

@@ -0,0 +1,154 @@
+---
+title: "Launch a Product Hunt Agent with Agno"
+sidebarTitle: "Product Hunt Agent"
+description: "Build an Agno Product Hunt assistant that queries live launch data, triggers celebrations, and streams into CometChat."
+---
+
+An Agno agent can double as a launch strategist—fetching Product Hunt rankings, answering questions, and firing confetti when it is time to celebrate.
+
+***
+
+## What You'll Build
+
+* A **FastAPI** service that wraps an Agno agent with Product Hunt tools.
+* Tooling for Algolia search, GraphQL leaderboards, natural timeframe parsing, and confetti payloads.
+* `/api/chat` and `/stream` endpoints that share CometChat-compatible newline-delimited JSON payloads.
+* Optional Product Hunt GraphQL integration (falls back gracefully when no token is provided).
+
+***
+
+## Prerequisites
+
+* Python 3.10 or newer.
+* `OPENAI_API_KEY` with GPT-4o (or similar) access.
+* Optional `PRODUCTHUNT_API_TOKEN` for live leaderboard queries.
+* curl or an API client to verify endpoints.
+
+***
+
+## Quick links
+
+- Repo root: [ai-agent-agno-examples](https://github.com/cometchat/ai-agent-agno-examples)
+- Project folder: [`product_hunt_agent/`](https://github.com/cometchat/ai-agent-agno-examples/tree/main/product_hunt_agent)
+- Server entrypoint: [`product_hunt_agent/main.py`](https://github.com/cometchat/ai-agent-agno-examples/blob/main/product_hunt_agent/main.py)
+- Agent builder: [`product_hunt_agent/agent_builder.py`](https://github.com/cometchat/ai-agent-agno-examples/blob/main/product_hunt_agent/agent_builder.py)
+- Services & queries: [`product_hunt_agent/services.py`](https://github.com/cometchat/ai-agent-agno-examples/blob/main/product_hunt_agent/services.py)
+
+***
+
+## How it works
+
+- **Agent** — `create_product_hunt_agent` configures an `OpenAIChat` model, system prompt, and five tools (`getTopProducts`, `getTopProductsThisWeek`, `getTopProductsByTimeframe`, `searchProducts`, `triggerConfetti`).
+- **Data** — `services.py` wraps Product Hunt’s GraphQL API (with token), Algolia search, timezone-aware timeframe parsing, and safe fallbacks when the API token is missing.
+- **API** — FastAPI routes in `main.py` expose REST endpoints for ranked lists and search, plus `/api/chat` and `/stream` for conversations and newline-delimited event streaming.
+- **Parity** — The streaming payload mirrors CometChat’s Bring Your Own Agent format (`text_delta`, `tool_*`, `text_done`, `done`, `error`), so existing UI logic can be reused.
+
+***
+
+## Setup
+
+<Steps>
+  <Step title="Clone & install">
+    From your workspace: <code>git clone https://github.com/cometchat/ai-agent-agno-examples.git</code>. Inside the repo: <code>python3 -m venv .venv && source .venv/bin/activate && pip install -e .</code>
+  </Step>
+  <Step title="Configure environment">
+    Create <code>.env</code> with <code>OPENAI_API_KEY</code>. Add <code>PRODUCTHUNT_API_TOKEN</code> for GraphQL access. Optional knobs: <code>PRODUCTHUNT_DEFAULT_TIMEZONE</code>, <code>OPENAI_BASE_URL</code>, <code>PRODUCT_OPENAI_MODEL</code>.
+  </Step>
+  <Step title="Run the server">
+    Start FastAPI: <code>uvicorn product_hunt_agent.main:app --host 0.0.0.0 --port 8001 --reload</code>. Health check: <code>GET /healthz</code>; streaming lives at <code>POST /stream</code>.
+  </Step>
+</Steps>
+
+***
+
+## Project Structure
+
+- FastAPI routes & schemas
+  - [`product_hunt_agent/main.py`](https://github.com/cometchat/ai-agent-agno-examples/blob/main/product_hunt_agent/main.py)
+  - [`product_hunt_agent/schemas.py`](https://github.com/cometchat/ai-agent-agno-examples/blob/main/product_hunt_agent/schemas.py)
+  - [`product_hunt_agent/config.py`](https://github.com/cometchat/ai-agent-agno-examples/blob/main/product_hunt_agent/config.py)
+- Agent behavior
+  - [`product_hunt_agent/agent_builder.py`](https://github.com/cometchat/ai-agent-agno-examples/blob/main/product_hunt_agent/agent_builder.py)
+- Product Hunt services
+  - [`get_top_products_by_votes`](https://github.com/cometchat/ai-agent-agno-examples/blob/main/product_hunt_agent/services.py#L72)
+  - [`get_top_products_by_timeframe`](https://github.com/cometchat/ai-agent-agno-examples/blob/main/product_hunt_agent/services.py#L123)
+  - [`search_products`](https://github.com/cometchat/ai-agent-agno-examples/blob/main/product_hunt_agent/services.py#L201)
+
+***
+
+## Step 1 - Configure Settings
+
+`ProductHuntSettings` centralizes configuration (API keys, timeouts, default timezone). The FastAPI app loads it once and injects it via `Depends`, so each route reuses the same validated settings.
+
+***
+
+## Step 2 - Understand the Agent Tools
+
+`agent_builder.py` clamps incoming arguments, calls service helpers, and returns structured dictionaries the UI can render. Highlights:
+
+- `getTopProducts` — All-time votes.
+- `getTopProductsThisWeek` — Rolling window controlled by `days`.
+- `getTopProductsByTimeframe` — Natural language inputs such as `yesterday`, `last-week`, or ISO dates.
+- `searchProducts` — Uses Product Hunt’s public Algolia index (no token required).
+- `triggerConfetti` — Returns payloads that UI Kit Builder variants can pass to your frontend celebration handler.
+
+The system prompt instructs the agent to cite sources and explain data gaps whenever a tool returns empty results.
+
+***
+
+## Step 3 - Product Hunt Data Services
+
+`services.py` wraps the external APIs with resilient defaults:
+
+- `parse_timeframe` translates natural strings into UTC ranges using `pendulum`.
+- `fetch_graphql` only runs when `PRODUCTHUNT_API_TOKEN` is present; otherwise, helper functions return empty lists so the agent can respond gracefully.
+- `search_products` hits the public Algolia index (`Post_production`) with rate-limit friendly defaults.
+
+***
+
+## Step 4 - Test the API
+
+List top launches from the past week:
+
+```bash
+curl "http://localhost:8001/api/top-week?limit=5&days=7"
+```
+
+Ask the agent a question (non-streaming):
+
+```bash
+curl -X POST http://localhost:8001/api/chat \
+  -H "Content-Type: application/json" \
+  -d '{
+        "messages": [
+          { "role": "user", "content": "What should I highlight in my launch post?" }
+        ]
+      }'
+```
+
+Stream responses (newline-delimited JSON):
+
+```bash
+curl -N http://localhost:8001/stream \
+  -H "Content-Type: application/json" \
+  -d '{
+        "thread_id": "launch-room",
+        "run_id": "run-457",
+        "messages": [
+          { "role": "user", "content": "Show me the top launches last week." }
+        ]
+      }'
+```
+
+Each line is a JSON object with `type` (e.g., `text_delta`, `tool_call_start`, `tool_result`, `text_done`, `done`) plus the echoed `thread_id` and `run_id`.
+
+***
+
+## Step 5 - Connect to CometChat
+
+- Deploy the service behind HTTPS and protect it with auth headers (use the agent’s **Headers** field when registering in CometChat).
+- Point the Agno agent variant at your `/stream` endpoint; reuse the same **Agent ID** from UI Kit Builder.
+- When the agent triggers `triggerConfetti`, listen for the tool event in your frontend to launch celebratory animations.
+- Echo `thread_id` and `run_id` in every streamed line so CometChat can correlate partial tool events and message chunks.
+
+You now have an Agno Product Hunt agent ready to ship inside CometChat-powered experiences.