docs(get-started): add Route your first LLM request tutorial

src/components/TableOfContents.astro

@@ -96,6 +96,24 @@ const feedbackUrl = `https://github.com/${GITHUB_REPO}/issues/new?title=${encode
 
     if (!tocLinks.length || !headings.length) return;
 
+    // Handle TOC clicks ourselves: the view-transitions router intercepts
+    // same-page hash links and resets scroll, so prevent that and scroll to the
+    // heading manually, offsetting for the fixed header.
+    var HEADER_OFFSET = 80;
+    tocLinks.forEach(function(link) {
+      if (link._tocClickBound) return;
+      link._tocClickBound = true;
+      link.addEventListener('click', function(e) {
+        var id = link.getAttribute('data-heading');
+        var target = id ? document.getElementById(id) : null;
+        if (!target) return;
+        e.preventDefault();
+        var top = target.getBoundingClientRect().top + window.pageYOffset - HEADER_OFFSET;
+        window.scrollTo({ top: top, behavior: 'smooth' });
+        if (history.replaceState) history.replaceState(null, '', '#' + id);
+      });
+    });
+
     function updateActiveLink() {
       var currentId = '';
 

src/components/docs/Card.astro

@@ -16,6 +16,7 @@ const iconPaths: Record<string, string> = {
   lightning: 'M13 10V3L4 14h7v7l9-11h-7z',
   database: 'M4 7v10c0 2.21 3.582 4 8 4s8-1.79 8-4V7M4 7c0 2.21 3.582 4 8 4s8-1.79 8-4M4 7c0-2.21 3.582-4 8-4s8 1.79 8 4m0 5c0 2.21-3.582 4-8 4s-8-1.79-8-4',
   shield: 'M9 12l2 2 4-4m5.618-4.016A11.955 11.955 0 0112 2.944a11.955 11.955 0 01-8.618 3.04A12.02 12.02 0 003 9c0 5.591 3.824 10.29 9 11.622 5.176-1.332 9-6.03 9-11.622 0-1.042-.133-2.052-.382-3.016z',
+  server: 'M5 12h14M5 12a2 2 0 01-2-2V6a2 2 0 012-2h14a2 2 0 012 2v4a2 2 0 01-2 2M5 12a2 2 0 00-2 2v4a2 2 0 002 2h14a2 2 0 002-2v-4a2 2 0 00-2-2m-2-4h.01M17 16h.01',
   // Charts & Analytics (Mintlify: chart-mixed, chart-line)
   'chart-mixed': 'M9 19v-6a2 2 0 00-2-2H5a2 2 0 00-2 2v6a2 2 0 002 2h2a2 2 0 002-2zm0 0V9a2 2 0 012-2h2a2 2 0 012 2v10m-6 0a2 2 0 002 2h2a2 2 0 002-2m0 0V5a2 2 0 012-2h2a2 2 0 012 2v14a2 2 0 01-2 2h-2a2 2 0 01-2-2z',
   'chart-line': 'M7 12l3-3 3 3 4-4M8 21l4-4 4 4M3 4h18M4 4v16',

src/pages/docs/get-started/add-your-first-agent-definition.mdx

@@ -0,0 +1,83 @@
+---
+title: "Add your first agent definition"
+description: "Create your first voice agent definition in Future AGI Simulate so you can run simulations against your agent"
+---
+
+An agent definition tells Future AGI which agent you're testing and how to reach it. This page walks you through creating your first **voice** agent definition in **Simulate**, so you can start running simulations against it
+
+Any voice agent can be simulated as long as it's reachable by a **phone number**. **Vapi** and **Retell** are natively supported, so you can sync the agent's name and prompt straight from them
+
+<Note>
+Building a **chat** agent? Chat simulations run through the **SDK**, not this form. See [Chat Simulation Using SDK](/docs/simulation/features/simulation-using-sdk)
+</Note>
+
+Every definition is versioned, so once you save it you can run tests against a specific version, compare versions, or roll back
+
+## Prerequisites
+
+- A Future AGI account
+- A **voice agent reachable via a phone number**
+- If the agent is on **Vapi** or **Retell**: its **Assistant ID** and provider **API key** (these also enable **Sync**)
+
+## 1. Open Agent Definition
+
+In the dashboard, open **Simulate** from the sidebar, select **Agent Definition**, and click **Start agent testing**:
+
+![Welcome to Agent Simulation screen with the Start Agent Testing button in Future AGI Simulate](/images/docs/get-started/add-your-first-agent-definition/agent-simulation-welcome.png)
+
+This opens the **Create new agent definition** wizard, which has three steps: **Basic Info**, **Configuration**, and **Behaviour**
+
+## 2. Add the basic information
+
+On the **Basic Info** step, fill in the basics:
+
+| Field | What you enter |
+|-------|----------------|
+| **Agent Type** | **Voice** |
+| **Agent Name** | A unique, descriptive name (also used as the observability project name) |
+| **Language** | One or more languages your agent uses (e.g. English) |
+
+![Basic Info step of the wizard with agent type, agent name, and language fields](/images/docs/get-started/add-your-first-agent-definition/basic-information.png)
+
+## 3. Configure and connect your agent
+
+On the **Configuration** step, choose the provider and set how Future AGI reaches your agent
+
+Under **Agent Configuration**, **Vapi** and **Retell** are natively supported: select the provider and enter the **Assistant ID** and **API Key**. With those set, use **Sync from provider** to pull the agent's name and system prompt into the form automatically. The right-hand panel lists exactly where to find each value in your provider
+
+Then set **Contact Information**, since voice agents are reached by phone: enter the **country code** and **contact number**, then choose the **connection type**:
+
+- **Inbound**: the agent receives calls
+- **Outbound**: the agent places calls (requires the Assistant ID and API Key above)
+
+![Configuration step showing provider, authentication, and contact information fields](/images/docs/get-started/add-your-first-agent-definition/agent-configuration.png)
+
+<Note>
+For **Outbound** agents, both the **Assistant ID** and **API Key** are required. Otherwise saving fails with a validation error
+</Note>
+
+## 4. Define behavior and save
+
+On the **Behaviour** step, set how your agent thinks and responds. Add the **system prompt** and, if needed, attach a **Knowledge Base** so evals can check the agent's answers against your real content: FAQs, SOPs, or product docs
+
+Review the **Summary** panel, enter a **commit message** (e.g. "Initial support agent"), and click **Create agent definition**. Future AGI stores this as version **v1**, a snapshot you can run tests against, compare, or roll back to later:
+
+![Behaviour step with the system prompt, knowledge base, commit message, and the configuration summary panel](/images/docs/get-started/add-your-first-agent-definition/behaviour-and-summary.png)
+
+## Verify
+
+Your agent now appears in the **Agent Definition** list. Open it to see version **v1** and its configuration
+
+Congratulations! You've created your first agent definition!🎉
+
+## Troubleshooting
+
+Save not going through? Try checking these:
+
+- **Validation error**: for **Outbound** agents, both the **Assistant ID** and **API Key** are required
+- **Sync failed**: double-check the API key and Assistant ID match your Vapi or Retell agent
+
+## Next steps
+
+- [Create a scenario](/docs/simulation/concepts/scenarios) for the conversation you want to test
+- [Run your first simulation](/docs/simulation) against this agent

src/pages/docs/get-started/create-your-first-prompt.mdx

@@ -0,0 +1,72 @@
+---
+title: "Create your first prompt"
+description: "Create and run your first prompt in the Future AGI Prompt Workbench, with versioning and variables built in"
+---
+
+A prompt is the instruction you give a model, and getting it right is one of the highest-leverage things you can do for an AI product. The **Prompt Workbench** gives every prompt a versioned home, so you can edit it, compare versions, and reuse it across datasets, simulations, experiments, and the SDK. This page walks you through creating and running your first prompt from scratch
+
+## Prerequisites
+
+- A Future AGI account
+- At least one model provider configured (Dashboard → **Settings → AI Providers**) so you can run the prompt
+
+## 1. Open Prompts and create one
+
+In the dashboard, under **Build** in the left nav, click **Prompts**, then **Create prompt** and choose **Start from scratch** (the other options are *Generate with AI* and *Start with a template*):
+
+![Creating a new prompt from the Prompts section](/images/docs/get-started/create-your-first-prompt/create-prompt.png)
+
+## 2. Name it and write the prompt
+
+The prompt opens as **Untitled-1**: click the title to rename it (e.g. **Acme Support Assistant**). The editor then has two fields: **System** (optional) shapes the model's overall behavior, and **User** is the message that drives the response. Here's a ready-to-use example. Copy each block into the matching field:
+
+**System**
+
+```text
+You are a customer support assistant for Acme, a company that makes project-management software.
+Answer the customer's question clearly and accurately, in a friendly and professional tone.
+Keep your reply under 120 words. If you are unsure of the answer, say so honestly and point the
+customer to help@acme.com instead of guessing.
+```
+
+**User**
+
+```text
+How do I reset my password?
+```
+
+![Renaming the prompt and writing the System and User messages](/images/docs/get-started/create-your-first-prompt/write-prompt.png)
+
+## 3. Pick a model and tune parameters
+
+With the prompt open, click **Select Model** and choose the model it runs on:
+
+![Choosing a model from the Select Model dropdown](/images/docs/get-started/create-your-first-prompt/select-model.png)
+
+Optionally, open **Params** to tune **temperature**, **max tokens**, **top P**, and more:
+
+![Tuning model parameters in the Params panel](/images/docs/get-started/create-your-first-prompt/parameters.png)
+
+## 4. Run it and save a version
+
+Click **Run Prompt** in the top-right corner, and the model's response appears in the **Output** panel. Saving the prompt creates a new **version** every time, so you can compare versions, roll back, deploy a specific one via labels, and reuse the prompt across the rest of the platform:
+
+![Running the prompt and viewing the model's response](/images/docs/get-started/create-your-first-prompt/run-prompt.png)
+
+## Verify
+
+Your prompt now appears in the **Prompts** list with its first version, and the **Output** panel shows the model's latest response
+
+Congratulations! You've created your first prompt!🎉
+
+## Troubleshooting
+
+Not getting a response? Try checking these:
+
+- **"API key not configured"**: add a model provider key under **Settings → AI Providers**, then run again
+- **Empty output**: check that the **User** field isn't blank before running
+
+## Next steps
+
+- [Run the prompt over a dataset](/docs/dataset/features/run-prompt) to test it at scale
+- [Fetch the prompt from your app via the SDK](/docs/prompt/features/sdk)

src/pages/docs/get-started/route-your-first-llm-request.mdx

@@ -0,0 +1,152 @@
+---
+title: "Route your first LLM request"
+description: "Route your first LLM call through Agent Command Center by changing two lines in the OpenAI SDK"
+---
+
+Routing your LLM requests through Future AGI is as simple as changing two lines in the OpenAI SDK. This page guides you on how to get started with **Agent Command Center**, the gateway that adds routing, caching, guardrails, and cost tracking to every request
+
+We recommend pointing your existing OpenAI SDK at the gateway, as it's the quickest way to get set up, keeps your code unchanged, and works with any OpenAI-compatible client
+
+You can switch providers later without touching your code, too
+
+## Prerequisites
+
+- A Future AGI account
+- Python 3.11
+
+## 1. Create your API key
+
+Create an Agent Command Center API key in **Dashboard → Settings → API Keys** and copy the value that starts with `sk-agentcc-`:
+
+<div style={{ display: 'flex', gap: '1rem', alignItems: 'flex-start', margin: '1.5rem 0' }}>
+  <img src="/images/docs/get-started/route-your-first-llm-request/add_api_key_modal.png" alt="Add API key modal in Agent Command Center" style={{ flex: 1, minWidth: 0, maxWidth: 'none', margin: 0 }} />
+  <img src="/images/docs/get-started/route-your-first-llm-request/api_key_added.png" alt="API key added in Agent Command Center" style={{ flex: 1, minWidth: 0, maxWidth: 'none', margin: 0 }} />
+</div>
+
+## 2. Add a provider
+
+The gateway routes each request to a provider you've connected, so add at least one
+
+- Open **Agent Command Center → [Providers](/docs/command-center/features/providers)** to see your connected providers:
+
+![Providers list in Agent Command Center](/images/docs/get-started/route-your-first-llm-request/list_provider.png)
+
+- Click **Add provider**, choose a provider, and paste its API key. Then select which of its models to expose through the gateway:
+
+<div style={{ display: 'flex', gap: '1rem', alignItems: 'flex-start', margin: '1.5rem 0' }}>
+  <img src="/images/docs/get-started/route-your-first-llm-request/add_provider_modal.png" alt="Add provider modal in Agent Command Center" style={{ flex: 1, minWidth: 0, maxWidth: 'none', margin: 0 }} />
+  <img src="/images/docs/get-started/route-your-first-llm-request/list_models_of_provider.png" alt="Choosing the provider's models in Agent Command Center" style={{ flex: 1, minWidth: 0, maxWidth: 'none', margin: 0 }} />
+</div>
+
+- Save it, and your provider appears in the list, ready to route requests to:
+
+![Provider added to Agent Command Center](/images/docs/get-started/route-your-first-llm-request/provider_added.png)
+
+## 3. Install the OpenAI SDK
+
+<CodeGroup titles={["Python", "JS/TS"]}>
+
+```bash Python
+pip install openai
+```
+
+```bash JS/TS
+npm install openai
+```
+
+</CodeGroup>
+
+## 4. Set your gateway key
+
+Set your Agent Command Center key in your terminal:
+
+```bash
+export AGENTCC_API_KEY="sk-agentcc-your-api-key-here"
+```
+
+## 5. Point the SDK at the gateway
+
+Change two lines, `base_url` and `api_key`, then send a request:
+
+<CodeGroup titles={["Python", "JS/TS"]}>
+
+```python Python
+import os
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="https://gateway.futureagi.com/v1",   # 1. point at the gateway
+    api_key=os.environ["AGENTCC_API_KEY"],          # 2. use your sk-agentcc- key
+)
+
+response = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "How does Future AGI's agentcc gateway reduce LLM call cost by 80%?"}],
+)
+print(response.choices[0].message.content)
+```
+
+```typescript JS/TS
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  baseURL: "https://gateway.futureagi.com/v1",   // 1. point at the gateway
+  apiKey: process.env.AGENTCC_API_KEY,            // 2. use your sk-agentcc- key
+});
+
+const response = await client.chat.completions.create({
+  model: "gpt-4o-mini",
+  messages: [{ role: "user", content: "What is the capital of France?" }],
+});
+console.log(response.choices[0].message.content);
+```
+
+</CodeGroup>
+
+## 6. Run it
+
+```bash
+python gateway.py
+```
+
+You will see the model's reply, and the request is now flowing through Agent Command Center
+
+## Verify
+
+Open your [Future AGI dashboard](https://app.futureagi.com) and go to Agent Command Center. Your request appears there with its provider, latency, and cost:
+
+For a programmatic check, every response also carries `x-agentcc-*` headers:
+
+```python
+resp = client.chat.completions.with_raw_response.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+print("Provider:", resp.headers.get("x-agentcc-provider"))
+print("Latency: ", resp.headers.get("x-agentcc-latency-ms"), "ms")
+print("Cost:    $", resp.headers.get("x-agentcc-cost"))
+```
+
+Congratulations! You've successfully routed your first request!🎉
+
+## Troubleshooting
+
+Not seeing a response? Try checking these:
+
+- **Authentication error**: confirm your key starts with `sk-agentcc-` (Settings → API Keys)
+- **Model or provider error**: make sure that provider is configured in Agent Command Center → Providers
+- **Wrong base URL**: it must be `https://gateway.futureagi.com/v1`
+
+## Bonus
+
+Change the model name and the gateway translates to each provider's format:
+
+```python
+client.chat.completions.create(model="claude-sonnet-4-6", messages=[{"role": "user", "content": "Hello"}])
+client.chat.completions.create(model="gemini-2.0-flash", messages=[{"role": "user", "content": "Hello"}])
+```
+
+## Next steps
+
+- [Set up routing and fallbacks](/docs/command-center/features/routing)
+- [Add guardrails](/docs/command-center/features/guardrails)

src/pages/docs/get-started/send-your-first-trace.mdx

@@ -130,7 +130,9 @@ Open the latest trace and confirm you can see:
 
 Congratulations! You've successfully sent your first trace!🎉
 
-## Not seeing your trace?
+## Troubleshooting
+
+Not seeing your traces? Try checking these:
 
 - **Authentication error**: re-check `FI_API_KEY` and `FI_SECRET_KEY` against Dashboard → Build → Keys
 - **No trace in Tracing**: let the script finish. Traces flush as the program exits, so don't stop it early