diff --git a/ai-agents.mdx b/ai-agents.mdx index 9fd72c62..4e05e4d2 100644 --- a/ai-agents.mdx +++ b/ai-agents.mdx @@ -58,9 +58,11 @@ With model-agnostic flexibility, CometChat AI Agents let you upgrade your AI sta } href="/ai-agents/mastra" horizontal /> - } horizontal>Coming Soon - } horizontal>Coming Soon - } horizontal>Coming Soon + {/* } horizontal>Coming Soon */} + } href="/ai-agents/agno" horizontal /> + {/* } horizontal>Coming Soon */} + } href="/ai-agents/vercel" horizontal /> + } href="/ai-agents/ag2" horizontal />

More providers coming…

diff --git a/ai-agents/agno-knowledge-agent.mdx b/ai-agents/agno-knowledge-agent.mdx new file mode 100644 index 00000000..33b9ed8f --- /dev/null +++ b/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/`. +* 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/`. +- **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 + + + + git clone https://github.com/cometchat/ai-agent-agno-examples.git, then inside the repo run:
python3 -m venv .venv && source .venv/bin/activate && pip install -e . + + + Create .env (or export env vars) with at least OPENAI_API_KEY. Optional overrides: OPENAI_BASE_URL, KNOWLEDGE_OPENAI_MODEL, KNOWLEDGE_STORAGE_PATH, KNOWLEDGE_CHROMA_PATH. + + + Launch FastAPI with uvicorn knowledge_agent.main:app --host 0.0.0.0 --port 8000 --reload. The app exposes health, ingestion, search, generate, and `/stream` endpoints (newline-delimited JSON). + + + +*** + +## 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: .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. diff --git a/ai-agents/agno-product-hunt-agent.mdx b/ai-agents/agno-product-hunt-agent.mdx new file mode 100644 index 00000000..f534fc43 --- /dev/null +++ b/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 + + + + From your workspace: git clone https://github.com/cometchat/ai-agent-agno-examples.git. Inside the repo: python3 -m venv .venv && source .venv/bin/activate && pip install -e . + + + Create .env with OPENAI_API_KEY. Add PRODUCTHUNT_API_TOKEN for GraphQL access. Optional knobs: PRODUCTHUNT_DEFAULT_TIMEZONE, OPENAI_BASE_URL, PRODUCT_OPENAI_MODEL. + + + Start FastAPI: uvicorn product_hunt_agent.main:app --host 0.0.0.0 --port 8001 --reload. Health check: GET /healthz; streaming lives at POST /stream. + + + +*** + +## 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. diff --git a/ai-agents/agno.mdx b/ai-agents/agno.mdx new file mode 100644 index 00000000..cbd446ba --- /dev/null +++ b/ai-agents/agno.mdx @@ -0,0 +1,191 @@ +--- +title: "Create an AI Agent with Agno" +sidebarTitle: "Create AI Agent" +description: "Connect an Agno agent to CometChat, customize it with UI Kit Builder, and ship it as React UI Kit code or a Chat Widget." +--- + +## What you’ll build + +- An **Agno** agent served with **FastAPI** that streams responses and exposes tools. +- The same agent **connected to CometChat** through Agent ID + Deployment URL routing. +- A **customized chat experience** using **UI Kit Builder**. +- An export to **React UI Kit code** _or_ **Chat Widget** for integration. + +--- + +## Prerequisites + +- A CometChat account and an app: **[Create App](https://app.cometchat.com/apps)** +- An Agno agent endpoint (see Step 6 for the example services). +- Python 3.10+ with `pip`, plus access to an OpenAI-compatible model (`OPENAI_API_KEY`). + +--- + +## Step 1 - Create your CometChat app + + + + Sign in at app.cometchat.com. Create a new app or open an existing one. + + + Note your App ID, Region, and Auth Key (needed if you export the Chat Widget later). + + + +--- + +## Step 2 - Connect your Agno Agent + +Navigate to **AI Agent → Get Started** and then **AI Agents → Add Agent**. + + + + Select **Agno**. + + + Provide: +
    +
  • Name and optional Icon
    • +
  • (Optional) Greeting and Introductory Message
    • +
  • (Optional) Suggested messages
    • +
+ + + Paste/define: +
    +
  • Agent ID — a unique handle that matches how you route traffic (e.g., support).
    • +
  • Deployment URL — the public HTTPS endpoint exposed by your Agno service.
    • +
  • (Optional) Headers — JSON auth headers that your FastAPI deployment expects.
    • +
+ + + Click Save, then ensure the agent’s toggle is ON in the AI Agents list. + + + +> **Tip:** The Agno examples stream newline-delimited JSON events using CometChat’s Bring Your Own Agent format. Keep the **Agent ID** and **Deployment URL** stable so you don’t need to reconnect. + +CometChat includes `thread_id`, `run_id`, the recent `messages`, and optional `namespace` (or `toolParams.namespace`) in every `/stream` request. Echo those IDs back in each event so UI Kit Builder variants can stitch partial responses correctly. + +--- + +## Step 3 - Define Frontend Actions (Optional) + + + + Go to AI Agent → Actions and click Add to create a frontend action your agent can call (e.g., “Open Product,” “Start Demo,” “Book Slot”). + + + Include: +
    +
  • Display Name — Shown to users (e.g., “Open Product Page”).
    • +
  • Execution Text — How the agent describes running it (e.g., “Opening product details for the user.”).
    • +
  • Name — A unique, code-friendly key (e.g., open_product).
    • +
  • Description — What the tool does and when to use it.
    • +
  • Parameters — JSON Schema describing inputs (the agent will fill these).
    • +
+ + + Example parameters JSON: + +```json +{ + "type": "object", + "required": ["productId"], + "properties": { + "productId": { + "type": "string", + "description": "The internal product ID to open" + }, + "utm": { + "type": "string", + "description": "Optional tracking code" + } + } +} +``` + + + At runtime, listen for tool calls and execute them client-side (e.g., route changes, modals, highlights). + + + +--- + +## Step 4 - Customize in UI Kit Builder + + From AI Agents click the variant (or Get Started) to enter UI Kit Builder. + Select Customize and Deploy. + Update theme, layout, and features; confirm the Agno agent is attached. + Use live preview to validate responses & any tool triggers. + + + + + + +--- + +## Step 5 - Export & Integrate + +Choose how you’ll ship the experience (Widget or React UI Kit export). + + + } description="Embed / script" href="/widget/ai-agents" horizontal /> + } href="https://www.cometchat.com/docs/ui-kit/react/ai-assistant-chat" horizontal>Pre Built UI Components + + +> The Agno agent from Step 2 is included automatically in exported variants—no extra code needed for basic conversations. + + + Pick Chat Widget (fastest) or export React UI Kit for code-level customization. + Open UI Kit Builder → Get Embedded Code → copy script + credentials. + Export the variant as code (UI Kit) if you need deep theming or custom logic. + Preview: the Agno agent should appear without extra config. + + +--- + +## Step 6 - Deploy & Secure (Reference) + + +Need an Agno backend? Use these reference projects to define, expose, and deploy FastAPI services that stream directly into CometChat. + + + + + + Clone the examples, install dependencies, and start the FastAPI server: + +```bash +git clone https://github.com/cometchat/ai-agent-agno-examples.git +cd ai-agent-agno-examples +python3 -m venv .venv +source .venv/bin/activate +pip install -e . +uvicorn knowledge_agent.main:app --host 0.0.0.0 --port 8000 --reload +``` + + Key points: + + - `knowledge_agent/main.py` exposes `/api/tools/ingest`, `/api/tools/searchDocs`, `/api/agents/knowledge/generate`, and `/stream` (newline-delimited JSON with `text_delta`, `tool_*`, `text_done`, `done`, `error`). + - `KnowledgeManager` creates an Agno agent bound to a per-namespace vector store and enforces retrieval-before-answer behavior with citations. + - Configure secrets via `.env` (`OPENAI_API_KEY`, optional `KNOWLEDGE_*` overrides). The example persists markdown under `knowledge_agent/data/knowledge/`. + + + + Launch the Product Hunt assistant on another port: + +```bash +uvicorn product_hunt_agent.main:app --host 0.0.0.0 --port 8001 --reload +``` + + Highlights: + + - `/api/top`, `/api/top-week`, `/api/top-range`, and `/api/search` surface Algolia + GraphQL data for Product Hunt launches. + - `/api/chat` and `/stream` share the same newline-delimited event schema as the knowledge agent, so CometChat receives consistent payloads (`text_delta`, `tool_*`, `text_done`, `done`). + - Provide `PRODUCTHUNT_API_TOKEN` for live data (the agent falls back gracefully when it’s absent) and customize tool prompts in `agent_builder.py`. + + + +> Deploy behind HTTPS and secure with auth headers or gateway middleware before pointing CometChat at the `/stream` endpoint. diff --git a/docs.json b/docs.json index 45abb3f3..4bb51e1b 100644 --- a/docs.json +++ b/docs.json @@ -303,6 +303,25 @@ } ] }, + { + "dropdown": "Agno", + "icon": "/images/icons/agno.svg", + "pages": [ + "/ai-agents/agno", + { + "group": "Guides", + "pages": [ + "/ai-agents/agno-knowledge-agent" + ] + }, + { + "group": "Tutorials", + "pages": [ + "/ai-agents/agno-product-hunt-agent" + ] + } + ] + }, { "dropdown": "Vercel AI", "icon": "/images/icons/vercel.png", @@ -5522,4 +5541,4 @@ "redirect": true } } -} \ No newline at end of file +}