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

# Test Documentation

> Reference page demonstrating AGENTS.md documentation standards

This page demonstrates the AGENTS.md documentation template — agent-centric examples, Mintlify components, and standard diagrams.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    name="Doc Tester",
    instructions="Summarise documentation standards in one paragraph.",
)
agent.start("What makes good agent documentation?")
```

The user reads a reference page; the hero example and diagram show how feature docs should open with Agent code and a user flow.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Documentation Workflow"
        SDK[📦 SDK Source] --> Agent[🤖 Agent Example]
        Agent --> Page[📄 Feature Page]
        Page --> Review[✅ AGENTS.md Checklist]
    end

    classDef sdk fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef page fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef review fill:#10B981,stroke:#7C90A0,color:#fff

    class SDK sdk
    class Agent agent
    class Page page
    class Review review
```

## Quick Start

<Steps>
  <Step title="Agent-Centric Intro">
    Every page opens with a minimal `Agent(...)` example before the hero diagram.

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(name="Example", instructions="Demonstrate the feature.")
    agent.start("Hello")
    ```
  </Step>

  <Step title="Mintlify Structure">
    Wrap Quick Start in Steps, Best Practices in AccordionGroup, and Related links in CardGroup (cols=2).

    ```mdx theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    <Steps>
      <Step title="Simple Usage">...</Step>
      <Step title="With Configuration">...</Step>
    </Steps>
    ```
  </Step>
</Steps>

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant Author
    participant SDK
    participant Page
    participant Reader

    Author->>SDK: Read source code
    SDK-->>Author: APIs and defaults
    Author->>Page: Write agent-centric docs
    Page-->>Reader: Copy-paste examples
```

| Component               | Purpose               | Output                   |
| ----------------------- | --------------------- | ------------------------ |
| **SDK source**          | Ground truth for APIs | Accurate examples        |
| **Agent example**       | Simplest usage path   | Quick Start code         |
| **Mintlify components** | Consistent layout     | Steps, Accordions, Cards |

***

## Opting an Example Out of the Guard

The SDK's session-docs guard executes every self-contained Python example in `praisonaiagents/session/README.md`; drop `<!-- praisonai: skip=true -->` on the line above a fence to opt an example out.

````mdx theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
<!-- praisonai: skip=true -->
```python
from praisonaiagents.session import DefaultSessionStore

store = DefaultSessionStore(session_dir="/custom/path/sessions")
```
````

The directive is an HTML comment placed within five lines above the fence. Accepted spellings are case-insensitive: `skip=true`, `skip=1`, `skip=yes`.

### When to use it

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Q{Can it run hermetically?} -->|Yes| Run[Let the guard run it]
    Q -->|No| Why{Why not?}
    Why -->|Absolute path / secret / server| Skip[Add skip=true directive]
    Why -->|It's a fragment| Drop[Leave it — free-name filter drops it]

    classDef question fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef run fill:#10B981,stroke:#7C90A0,color:#fff
    classDef skip fill:#8B0000,stroke:#7C90A0,color:#fff

    class Q,Why question
    class Run,Drop run
    class Skip skip
```

Use the directive when an example:

* writes to an absolute path outside the temp dir,
* reads a live secret or credential,
* starts a long-running server or opens a socket.

For a deliberate fragment, prefer letting the free-name filter drop it — no directive needed.

### When not to use it

* "It doesn't run in my env" is not a reason. If the example is real, make it hermetic.
* Don't use it to hide a broken example. The guard exists so the docs stay honest.

<Note>
  The executor lives at `src/praisonai-agents/tests/unit/session/test_session_docs_examples.py`, introduced in [PraisonAI PR #4179](https://github.com/MervinPraison/PraisonAI/pull/4179).
</Note>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Start with Agent(...)">
    Top of every page: a minimal agent example showing the feature in use — not subsystem imports or config-only snippets.
  </Accordion>

  <Accordion title="Use standard diagram colours">
    Hero Mermaid diagrams use `#8B0000` for agents, `#189AB4` for tools/processes, and white text on coloured fills.
  </Accordion>

  <Accordion title="Keep examples runnable">
    Include all imports, use `os.getenv()` for secrets, and avoid placeholder strings like `"your-api-key"`.
  </Accordion>

  <Accordion title="One sentence per section intro">
    Each section gets a single sentence explaining what follows — no preamble phrases from AGENTS.md §6.3.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Templates" icon="file-code" href="/docs/features/templates">
    Customise agent prompts and response formatting
  </Card>

  <Card title="Telemetry" icon="chart-line" href="/docs/features/telemetry">
    Anonymous usage metrics for agent runs
  </Card>
</CardGroup>