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

# Mave Agent

> AI research agent with comprehensive multi-source analysis

Mave is Mavera's AI-powered research agent. Unlike the Responses API, which answers questions from a single persona's perspective, Mave **conducts research** — searching the web, pulling news articles, querying SEO data, and synthesizing findings into cited, validated reports.

Every Mave response includes **sources with URLs**, a **confidence score**, and a **hallucination risk assessment**. It's designed for questions where you need facts, not just opinions.

<Info>
  Mave uses a **5-phase orchestration process**: triage, planning, research, execution, and validation. This is why responses take longer (5–30 seconds) but are significantly more grounded than standard chat.
</Info>

## How It Works

```mermaid theme={"dark"}
flowchart TD
    Q[Your Query] --> T[Phase 1: Triage]
    T -->|Classify complexity| P[Phase 2: Planning]
    P -->|Select tools & personas| R[Phase 3: Research]

    R --> WS[Web Search]
    R --> NS[News Search]
    R --> SEO[SEO Data]
    R --> KB[Knowledge Base]

    WS --> E[Phase 4: Execution]
    NS --> E
    SEO --> E
    KB --> E

    E -->|Generate response with citations| V[Phase 5: Validation]
    V -->|Reality check & confidence score| Done[Final Response]

    style T fill:#f8fafc,stroke:#64748b
    style P fill:#f8fafc,stroke:#64748b
    style R fill:#f8fafc,stroke:#64748b
    style E fill:#f8fafc,stroke:#64748b
    style V fill:#f8fafc,stroke:#64748b
```

<Steps>
  <Step title="Triage">
    Mave analyzes your query complexity and determines if clarification is needed. Queries are classified as **Simple**, **Moderate**, **Complex**, or **Strategic** — each triggering a different depth of research.
  </Step>

  <Step title="Planning">
    Mave creates an execution strategy: which personas to consult, what data sources to query, what search terms to use, and how to structure the final output.
  </Step>

  <Step title="Research">
    Mave executes tool calls in parallel — web search, news search, SEO data, and knowledge base queries — to gather comprehensive information from multiple angles.
  </Step>

  <Step title="Execution">
    Mave synthesizes all research into a coherent response, incorporating persona perspectives and inline citations to source material.
  </Step>

  <Step title="Validation">
    Mave performs a reality check: assessing accuracy, flagging unsupported claims, evaluating hallucination risk, and producing a confidence score.
  </Step>
</Steps>

## Basic Usage

<CodeGroup>
  ```python Python theme={"dark"}
  import requests

  response = requests.post(
      "https://app.mavera.io/api/v1/mave/chat",
      headers={
          "Authorization": "Bearer mvra_live_your_key_here",
          "Content-Type": "application/json"
      },
      json={
          "message": "Analyze the competitive landscape for electric vehicles in Europe"
      }
  )

  result = response.json()
  print(f"Thread ID: {result['thread_id']}")
  print(f"\n{result['content']}")

  print("\n--- Sources ---")
  for source in result["sources"]:
      print(f"  [{source['title']}]({source['url']})")

  print(f"\nConfidence: {result['validation']['confidence_score']}")
  print(f"Hallucination risk: {result['validation']['hallucination_risk']}")
  print(f"Credits used: {result['usage']['credits_used']}")
  ```

  ```javascript JavaScript theme={"dark"}
  const response = await fetch("https://app.mavera.io/api/v1/mave/chat", {
    method: "POST",
    headers: {
      Authorization: "Bearer mvra_live_your_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message: "Analyze the competitive landscape for electric vehicles in Europe",
    }),
  });

  const result = await response.json();
  console.log(`Thread ID: ${result.thread_id}`);
  console.log(result.content);

  console.log("\n--- Sources ---");
  result.sources.forEach((source) => {
    console.log(`  [${source.title}](${source.url})`);
  });

  console.log(`\nConfidence: ${result.validation.confidence_score}`);
  console.log(`Hallucination risk: ${result.validation.hallucination_risk}`);
  ```

  ```bash cURL theme={"dark"}
  curl -X POST https://app.mavera.io/api/v1/mave/chat \
    -H "Authorization: Bearer mvra_live_your_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "message": "Analyze the competitive landscape for electric vehicles in Europe"
    }'
  ```
</CodeGroup>

## Multi-Turn Threads

Every Mave response returns a `thread_id`. Pass it back in subsequent requests to maintain conversation context. Mave remembers the full research history within a thread, so follow-up questions can reference earlier findings without re-doing the research.

<CodeGroup>
  ```python Python theme={"dark"}
  headers = {
      "Authorization": "Bearer mvra_live_your_key_here",
      "Content-Type": "application/json"
  }

  response1 = requests.post(
      "https://app.mavera.io/api/v1/mave/chat",
      headers=headers,
      json={"message": "Analyze the EV market in Europe"}
  )
  thread_id = response1.json()["thread_id"]
  print(response1.json()["content"])

  response2 = requests.post(
      "https://app.mavera.io/api/v1/mave/chat",
      headers=headers,
      json={
          "message": "What about Tesla's market share specifically?",
          "thread_id": thread_id
      }
  )
  print(response2.json()["content"])

  response3 = requests.post(
      "https://app.mavera.io/api/v1/mave/chat",
      headers=headers,
      json={
          "message": "Compare that with BYD's growth trajectory",
          "thread_id": thread_id
      }
  )
  print(response3.json()["content"])
  ```

  ```javascript JavaScript theme={"dark"}
  const headers = {
    Authorization: "Bearer mvra_live_your_key_here",
    "Content-Type": "application/json",
  };

  const res1 = await fetch("https://app.mavera.io/api/v1/mave/chat", {
    method: "POST",
    headers,
    body: JSON.stringify({ message: "Analyze the EV market in Europe" }),
  });
  const { thread_id: threadId, content: content1 } = await res1.json();
  console.log(content1);

  const res2 = await fetch("https://app.mavera.io/api/v1/mave/chat", {
    method: "POST",
    headers,
    body: JSON.stringify({
      message: "What about Tesla's market share specifically?",
      thread_id: threadId,
    }),
  });
  console.log((await res2.json()).content);

  const res3 = await fetch("https://app.mavera.io/api/v1/mave/chat", {
    method: "POST",
    headers,
    body: JSON.stringify({
      message: "Compare that with BYD's growth trajectory",
      thread_id: threadId,
    }),
  });
  console.log((await res3.json()).content);
  ```
</CodeGroup>

<Tip>
  Follow-up messages in the same thread are cheaper because Mave can reuse earlier research context. Start new threads only when changing topics entirely.
</Tip>

## Streaming

Enable streaming for real-time display of Mave's response as it generates.

<CodeGroup>
  ```python Python theme={"dark"}
  import httpx
  import json

  with httpx.stream(
      "POST",
      "https://app.mavera.io/api/v1/mave/chat",
      headers={"Authorization": "Bearer mvra_live_your_key_here"},
      json={"message": "What are the latest AI trends in healthcare?", "stream": True}
  ) as response:
      for line in response.iter_lines():
          if line.startswith("data: "):
              data = json.loads(line[6:])
              if data.get("type") == "content":
                  print(data["content"], end="", flush=True)
              elif data.get("type") == "sources":
                  print("\n\n--- Sources ---")
                  for source in data["sources"]:
                      print(f"  {source['title']}: {source['url']}")
              elif data.get("type") == "validation":
                  print(f"\nConfidence: {data['confidence_score']}")
              elif data.get("type") == "done":
                  print(f"\nCredits used: {data['usage']['credits_used']}")
  ```

  ```javascript JavaScript theme={"dark"}
  const response = await fetch("https://app.mavera.io/api/v1/mave/chat", {
    method: "POST",
    headers: {
      Authorization: "Bearer mvra_live_your_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message: "What are the latest AI trends in healthcare?",
      stream: true,
    }),
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const lines = decoder.decode(value).split("\n");
    for (const line of lines) {
      if (line.startsWith("data: ")) {
        const data = JSON.parse(line.slice(6));
        if (data.type === "content") {
          process.stdout.write(data.content);
        } else if (data.type === "sources") {
          console.log("\n\n--- Sources ---");
          data.sources.forEach((s) => console.log(`  ${s.title}: ${s.url}`));
        } else if (data.type === "validation") {
          console.log(`\nConfidence: ${data.confidence_score}`);
        }
      }
    }
  }
  ```
</CodeGroup>

**SSE event types:**

| Event Type   | Content                                              |
| ------------ | ---------------------------------------------------- |
| `content`    | Text chunk of the response                           |
| `sources`    | Array of source objects with title, URL, and snippet |
| `validation` | Confidence score and hallucination risk              |
| `done`       | Final event with usage data                          |

## Sources and Citations

Every Mave response includes a `sources` array with the materials it used during research.

```json theme={"dark"}
{
  "sources": [
    {
      "title": "European EV Sales Report 2024",
      "url": "https://example.com/report",
      "snippet": "EV adoption in Europe grew 25% year-over-year, with Norway leading at 82% market share...",
      "source_type": "web"
    },
    {
      "title": "Tesla Q4 2024 Earnings Call",
      "url": "https://example.com/earnings",
      "snippet": "European deliveries increased 18% compared to Q3...",
      "source_type": "news"
    }
  ]
}
```

Source types include `web` (general web search), `news` (news articles), `seo` (SEO/domain data), and `knowledge_base` (your custom knowledge).

<Warning>
  Always verify critical citations by visiting the source URLs. While Mave's validation phase reduces hallucination, no AI system produces perfectly accurate output 100% of the time.
</Warning>

## CircleMind Knowledge Base

CircleMind is Mavera's knowledge base layer. When configured, Mave automatically searches your custom knowledge alongside public web data, grounding responses in your proprietary information.

### How It Works

1. **Upload documents** to your CircleMind knowledge base (PDFs, docs, text files)
2. **Mave automatically queries** your knowledge base during the Research phase
3. **Results are blended** with web and news data, with source attribution

### Querying with Knowledge Base

```python theme={"dark"}
response = requests.post(
    "https://app.mavera.io/api/v1/mave/chat",
    headers={"Authorization": "Bearer mvra_live_your_key_here"},
    json={
        "message": "What does our internal research say about customer churn in Q3?",
        "use_knowledge_base": True
    }
)

for source in response.json()["sources"]:
    if source["source_type"] == "knowledge_base":
        print(f"Internal source: {source['title']}")
```

<Info>
  CircleMind knowledge base queries are included in Mave's credit cost — no additional charge per knowledge base lookup. See [CircleMind docs](/features/circlemind) for setup instructions.
</Info>

## Data Sources

Mave can access multiple data sources during the Research phase:

| Source             | Provider   | Data                                         | When Used                       |
| ------------------ | ---------- | -------------------------------------------- | ------------------------------- |
| **Web Search**     | Tavily     | Real-time web pages, articles, documentation | Most queries                    |
| **News Search**    | Perigon    | Recent news articles, press releases         | Current events, market updates  |
| **SEO Data**       | SEMrush    | Domain metrics, traffic, keyword rankings    | Competitive analysis            |
| **Knowledge Base** | CircleMind | Your uploaded documents                      | When `use_knowledge_base: true` |

## Thread Management

### List Threads

<CodeGroup>
  ```python Python theme={"dark"}
  response = requests.get(
      "https://app.mavera.io/api/v1/mave/threads",
      headers={"Authorization": "Bearer mvra_live_your_key_here"}
  )

  for thread in response.json()["data"]:
      print(f"{thread['id']} — {thread['title']} — {thread['message_count']} messages")
  ```

  ```bash cURL theme={"dark"}
  curl https://app.mavera.io/api/v1/mave/threads \
    -H "Authorization: Bearer mvra_live_your_key_here"
  ```
</CodeGroup>

### Get Thread Details

```bash theme={"dark"}
curl https://app.mavera.io/api/v1/mave/threads/mave_thread_abc123 \
  -H "Authorization: Bearer mvra_live_your_key_here"
```

### Delete Thread

```bash theme={"dark"}
curl -X DELETE https://app.mavera.io/api/v1/mave/threads/mave_thread_abc123 \
  -H "Authorization: Bearer mvra_live_your_key_here"
```

## Response Format

```json theme={"dark"}
{
  "thread_id": "mave_thread_abc123",
  "message_id": "msg_xyz789",
  "content": "## Electric Vehicle Market Analysis\n\nBased on my research across multiple sources...",
  "sources": [
    {
      "title": "European EV Sales Report 2024",
      "url": "https://example.com/report",
      "snippet": "EV adoption in Europe grew 25% year-over-year...",
      "source_type": "web"
    }
  ],
  "personas_used": [
    {
      "id": "persona_123",
      "name": "Industry Analyst"
    }
  ],
  "validation": {
    "passed": true,
    "confidence_score": 0.89,
    "hallucination_risk": "low",
    "unsupported_claims": []
  },
  "usage": {
    "credits_used": 35
  }
}
```

### Validation Object

The `validation` field provides transparency into Mave's self-assessment:

| Field                | Type         | Description                                        |
| -------------------- | ------------ | -------------------------------------------------- |
| `passed`             | boolean      | Whether the response passed the reality check      |
| `confidence_score`   | number (0–1) | Overall confidence in the accuracy of the response |
| `hallucination_risk` | string       | `"low"`, `"medium"`, or `"high"`                   |
| `unsupported_claims` | array        | Statements that couldn't be verified by sources    |

## When to Use Mave vs Chat

| Need                              | Use **Chat** | Use **Mave**  |
| --------------------------------- | ------------ | ------------- |
| Persona perspective on a topic    | Yes          | —             |
| Real-time web data with citations | —            | Yes           |
| Quick conversational interaction  | Yes          | —             |
| Multi-source research report      | —            | Yes           |
| Structured JSON output            | Yes          | —             |
| Fact-checked analysis             | —            | Yes           |
| Tool calling / function calling   | Yes          | —             |
| Knowledge base integration        | —            | Yes           |
| Cost per query                    | 1–5 credits  | 10–75 credits |
| Response time                     | \< 3 seconds | 5–30 seconds  |

<Tip>
  **Combine both:** Use Mave to research a topic, then use Chat with a specific persona to explore how that audience would react to the findings. This gives you both factual grounding and audience perspective.
</Tip>

## Credit Usage

Mave queries are more expensive than Chat because they involve multiple research phases and data source calls.

| Query Complexity | Typical Cost  | Example                                                             |
| ---------------- | ------------- | ------------------------------------------------------------------- |
| Simple           | 10–15 credits | "What is the population of France?"                                 |
| Moderate         | 20–30 credits | "Summarize recent AI regulation in the EU"                          |
| Complex          | 30–50 credits | "Compare market strategies of top 5 EV brands in Europe"            |
| Strategic        | 40–75 credits | "Full competitive landscape analysis for fintech in Southeast Asia" |

Follow-up messages in the same thread typically cost 30–50% less than the initial query.

## Best Practices

<AccordionGroup>
  <Accordion title="Be specific in your queries">
    Clear, specific questions lead to better research. "Analyze Tesla's market position in Germany in 2024" produces a more focused, useful report than "Tell me about Tesla."
  </Accordion>

  <Accordion title="Use threads for follow-ups">
    Continue conversations in the same thread to maintain context and reduce redundant research. Mave can reference earlier findings in follow-up responses.
  </Accordion>

  <Accordion title="Check the validation results">
    Review `validation.confidence_score` and `validation.hallucination_risk` before relying on the output for important decisions. Scores below 0.7 warrant additional verification.
  </Accordion>

  <Accordion title="Enable streaming for long queries">
    Complex and strategic queries can take 15–30 seconds. Streaming lets you display progress to users in real time instead of showing a loading spinner.
  </Accordion>

  <Accordion title="Use knowledge base for proprietary data">
    When your question involves internal data, enable CircleMind to blend your proprietary knowledge with public web research.
  </Accordion>

  <Accordion title="Use Chat for persona opinions, Mave for facts">
    Don't use Mave when you just need a persona's perspective — that's what Chat is for. Use Mave when you need researched, cited, fact-checked information.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart: Mave" icon="rocket" href="/quickstart-mave">
    First Mave query in 5 minutes
  </Card>

  <Card title="Mave Research Report" icon="book" href="/tutorials/mave-research-report">
    Build a full report from a Mave session
  </Card>

  <Card title="CircleMind" icon="brain" href="/features/circlemind">
    Set up your knowledge base
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/mave-agent/send-message-to-mave">
    Full API specification
  </Card>
</CardGroup>