Seng/chat prototype

.cursor/rules/overview.mdc

@@ -10,4 +10,8 @@ This is the technical documentation for the Agentuity Cloud, which covers:
 - Examples, tutorials, samples (/content/Examples)
 - And the different SDKs (/content/SDKs)
 
-This doc app is a NextJS app built on top of Fumadocs (https://fumadocs.vercel.app/docs/ui).
+This doc app is a NextJS app built on top of Fumadocs (https://fumadocs.vercel.app/docs/ui).
+
+This project also contains the agent the powers RAG and Tutorials. Those agents live in `/agent-docs` directory.
+To run the agent server locally, go into that directory with `cd agent-docs` and then start the agent with `agentuity dev`.
+To run the NextJS app, do `npm run dev` in the root of this repository. You will want to start these two apps in separate repositories.

.cursor/rules/tutorials-structure.mdc

@@ -0,0 +1,69 @@
+### Rule: tutorials-structure
+
+Purpose: Define how tutorials are authored and rendered so docs and runnable code stay in sync.
+
+### Structure
+- Narrative pages: `content/Tutorial/<tutorial-id>/step-<n>.mdx`
+- Section navigation: `content/Tutorial/meta.json` (list MDX page slugs in order)
+- Runnable example project: `examples/<tutorial-id>/` (full project; exclude `node_modules/`, `.uv/`)
+- Tutorial code snippets: must be imported from files via `<CodeFromFiles />`
+- Other, non-project examples: use regular fenced code blocks in MDX
+
+### MDX authoring
+- Each step MDX must use frontmatter:
+  - `title`, `description` (recommended: `stepNumber`, `next`, `prev`)
+- Import real code from the example project using repo-root-relative paths via `<CodeFromFiles />`:
+
+```mdx
+---
+title: Step 1 — Getting Started
+description: Intro step
+---
+
+<!-- Single snippet -->
+<CodeFromFiles snippets={[{ path: "/examples/javascript-sdk/src/agent.ts", lang: "ts", title: "agent.ts" }]} />
+
+<!-- Line range -->
+<CodeFromFiles snippets={[{ path: "/examples/javascript-sdk/src/agent.ts", lang: "ts", from: 12, to: 48, title: "Handler section" }]} />
+
+<!-- Multi-language tabs -->
+<CodeFromFiles snippets={[
+  { path: "/examples/javascript-sdk/src/agent.ts", lang: "ts", title: "TypeScript" },
+  { path: "/examples/javascript-sdk-python/src/agent.py", lang: "python", title: "Python" },
+]} title="Agent comparison" />
+```
+
+### `<CodeFromFiles />` component
+- Available in MDX via the docs page components map
+- Props:
+  - `snippets`: array of `{ path, lang?, from?, to?, title? }`
+    - `path`: repo-root-relative (must start with `/`), validated and read server-side
+    - `lang`: language for highlighting (auto-inferred if omitted)
+    - `from`, `to`: 1-based line range (inclusive)
+    - `title`: label per tab
+  - `title` (optional): heading displayed above the tabs
+- Renders using shared `CodeBlock` styling and `Tabs` for multiple snippets
+
+### Example project conventions (`examples/<tutorial-id>/`)
+- Include: `package.json`, `tsconfig.json`, `src/**`, optional `README.md`, optional lockfile
+- Exclude: `node_modules/`
+- Optional hygiene:
+  - Add `examples/**` to `.eslintignore` if you don’t want repo-wide linting on example sources
+  - Add `examples/**` to root `tsconfig.json` `exclude` if you don’t want repo-wide type-checks
+- Should be runnable in a sandbox (StackBlitz/CodeSandbox) via `package.json` scripts
+
+### Rendering pipeline
+- Fumadocs loads MDX via `lib/source.ts` and `app/(docs)/[[...slug]]/page.tsx`
+- `<CodeFromFiles />` reads files at build/server time and renders with `CodeBlock`
+
+
+### Agent compatibility (optional)
+- Step API: `GET /api/tutorials/:id/steps/:stepNumber` returns `{ mdx, snippets }`.
+- The chat UI replaces each `<CodeFromFiles />` occurrence with one or more fenced code blocks by consuming entries from `snippets` in order.
+
+### Quality gates (recommended)
+- CI verifies:
+  - All `content/Tutorial/**.mdx` pages referenced by `content/Tutorial/meta.json` build without errors
+  - All `<CodeFromFiles snippets={[...]}/>` references resolve to existing files
+  - Optional: the example project type-checks (`tsc --noEmit`) or passes a smoke test
+

.env.example

@@ -1,6 +1,7 @@
 # Agent Configuration
 AGENT_BASE_URL=http://127.0.0.1:3500
-AGENT_ID=agent_9ccc5545e93644bd9d7954e632a55a61
+AGENT_QA_ID=agent_9ccc5545e93644bd9d7954e632a55a61
+AGENT_PULSE_ID=agent_ddcb59aa4473f1323be5d9f5fb62b74e
 
-# Alternative: You can also set the full URL instead of BASE_URL + ID
-# AGENT_FULL_URL=http://127.0.0.1:3500/agent_9ccc5545e93644bd9d7954e632a55a61
+# API key can be found in agent-docs .env AGENTUITY_SDK_KEY
+AGENTUITY_API_KEY=

.gitignore

@@ -26,6 +26,7 @@ yarn-error.log*
 .env*.local
 .env.local
 .env.production
+.env
 .vercel
 next-env.d.ts
 .open-next

agent-docs/agentuity.yaml

@@ -78,3 +78,6 @@ agents:
   - id: agent_9ccc5545e93644bd9d7954e632a55a61
     name: doc-qa
     description: Agent that can answer questions based on dev docs as the knowledge base
+  - id: agent_ddcb59aa4473f1323be5d9f5fb62b74e
+    name: agent-pulse
+    description: Agentuity web app agent that converses with users for generate conversation and structured docs tutorials.

agent-docs/package.json

@@ -40,4 +40,4 @@
 		}
 	},
 	"module": "index.ts"
-}
+}

agent-docs/src/agents/agent-pulse/README.md

@@ -0,0 +1,102 @@
+# Pulse Agent
+
+A conversational AI agent for tutorial management built with OpenAI and structured responses.
+
+## Overview
+
+Pulse is a friendly AI assistant that helps users discover, start, and navigate through tutorials. It uses OpenAI's GPT-4o-mini with structured response generation to provide both conversational responses and actionable instructions.
+
+## Architecture
+
+### Core Components
+
+- **`index.ts`**: Main agent logic using `generateObject` for structured responses
+- **`chat-helpers.ts`**: Conversation history management
+- **`tutorial-helpers.ts`**: Tutorial content fetching and formatting
+- **`tutorial.ts`**: Tutorial API integration
+
+### Response Structure
+
+The agent uses `generateObject` to return structured responses with two parts:
+
+```typescript
+{
+  message: string,      // Conversational response for the user
+  actionable?: {        // Optional action for the program to execute
+    type: 'start_tutorial' | 'next_step' | 'previous_step' | 'get_tutorials' | 'none',
+    tutorialId?: string,
+    step?: number
+  }
+}
+```
+
+### How It Works
+
+1. **User Input**: Agent receives user message and conversation history
+2. **LLM Processing**: OpenAI generates structured response with message and optional actionable object
+3. **Action Execution**: Program intercepts actionable objects and executes them:
+   - `get_tutorials`: Fetches available tutorial list
+   - `start_tutorial`: Fetches real tutorial content from API
+   - `next_step`/`previous_step`: Navigate through tutorial steps (TODO)
+4. **Response**: Returns conversational message plus any additional data (tutorial content, tutorial list, etc.)
+
+## Key Features
+
+- **Structured Responses**: Clean separation between conversation and actions
+- **Real Tutorial Content**: No hallucinated content - all tutorial data comes from actual APIs
+- **Context Awareness**: Maintains conversation history for natural references
+- **Extensible Actions**: Easy to add new action types (next step, hints, etc.)
+- **Debug Logging**: Comprehensive logging for troubleshooting
+
+## Example Interactions
+
+### Starting a Tutorial
+**User**: "I want to learn the JavaScript SDK"
+
+**LLM Response**:
+```json
+{
+  "message": "I'd be happy to help you start the JavaScript SDK tutorial!",
+  "actionable": {
+    "type": "start_tutorial",
+    "tutorialId": "javascript-sdk"
+  }
+}
+```
+
+**Final Response**:
+```json
+{
+  "response": "I'd be happy to help you start the JavaScript SDK tutorial!",
+  "tutorialData": {
+    "type": "tutorial_step",
+    "tutorialId": "javascript-sdk",
+    "tutorialTitle": "JavaScript SDK Tutorial",
+    "currentStep": 1,
+    "stepContent": "Welcome to the JavaScript SDK tutorial...",
+    "codeBlock": {...}
+  },
+  "conversationHistory": [...]
+}
+```
+
+### General Conversation
+**User**: "What's the difference between TypeScript and JavaScript?"
+
+**LLM Response**:
+```json
+{
+  "message": "TypeScript is a superset of JavaScript that adds static type checking...",
+  "actionable": {
+    "type": "none"
+  }
+}
+```
+
+## Benefits
+
+- **Reliable**: No parsing or tool interception needed
+- **Extensible**: Easy to add new action types
+- **Clean**: Clear separation between conversation and actions  
+- **Debuggable**: Can see exactly what the LLM wants to do
+- **No Hallucination**: Tutorial content comes from real APIs, not LLM generation

agent-docs/src/agents/agent-pulse/context/builder.ts

@@ -0,0 +1,54 @@
+import type { AgentContext } from "@agentuity/sdk";
+
+export async function buildSystemPrompt(tutorialContext: string, ctx: AgentContext): Promise<string> {
+  try {
+    const systemPrompt = `=== ROLE ===
+You are Pulse, an AI assistant designed to help developers learn and navigate the Agentuity platform through interactive tutorials and clear guidance. Your primary goal is to assist users with understanding and using the Agentuity SDK effectively. When a user's query is vague, unclear, or lacks specific intent, subtly suggest relevant interactive tutorial to guide them toward learning the platform. For clear, specific questions related to the Agentuity SDK or other topics, provide direct, accurate, and concise answers without mentioning tutorials unless relevant. Always maintain a friendly and approachable tone to encourage engagement.
+
+Your role is to ensure user have a smooth tutorial experience!
+
+When user is asking to move to the next tutorial, simply increment the step for them.
+
+=== PERSONALITY ===
+- Friendly and encouraging with light humour  
+- Patient with learners at all levels  
+- Clear and concise in explanations  
+- Enthusiastic about teaching and problem-solving
+
+=== Available Tools or Functions ===
+You have access to various tools you can use -- use when appropriate!
+1. Tutorial management  
+   - startTutorialAtStep: Starting the user off at a specific step of a tutorial.
+2. General assistance
+   - askDocsAgentTool: retrieve Agentuity documentation snippets
+
+=== TOOL-USAGE RULES (must follow) ===
+- startTutorialById must only be used when user select a tutorial. If the user starts a new tutorial, the step number should be set to one. Valid step is between 1 and totalSteps of the specific tutorial.
+- Treat askDocsAgentTool as a search helper; ignore results you judge irrelevant.
+
+=== RESPONSE STYLE (format guidelines) ===
+- Begin with a short answer, then elaborate if necessary.
+- Add brief comments to complex code; skip obvious lines.
+- End with a question when further clarification could help the user.
+
+=== SAFETY & BOUNDARIES ===
+- If asked for private data or secrets, refuse.  
+- If the user requests actions outside your capabilities, apologise and explain.  
+- Keep every response < 400 words
+
+Generate a response to the user query accordingly and try to be helpful
+
+=== CONTEXT ===
+${tutorialContext}
+
+=== END OF PROMPT ===
+
+Stream your reasoning steps clearly.`;
+
+    ctx.logger.debug("Built system prompt with tutorial context");
+    return systemPrompt;
+  } catch (error) {
+    ctx.logger.error("Failed to build system prompt: %s", error instanceof Error ? error.message : String(error));
+    throw error; // Re-throw for centralized handling
+  }
+}