docs: document configurable agent server readiness timeout (PRAISONAI_SERVER_READY_TIMEOUT)

[MervinPraison]

Context

Upstream change: MervinPraison/PraisonAI PR #1655 ("fix: check agent server readiness timeout return value (fixes #1631)") — merged into main on 2026-05-13.

• PR: fix: check agent server readiness timeout return value (fixes #1631) PraisonAI#1655
• Upstream issue fixed: [Reliability] Agent server readiness timeout fires silently — return value not checked PraisonAI#1631
• Head SHA: 60b45407962488a916d399122e3362858958f19c
• Source file changed: praisonaiagents/agents/agents.py (method _AgentServerRegistry.start_server_if_needed)
• New test file: praisonaiagents/tests/unit/agents/test_server_registry_timeout.py

What changed in the SDK (user-facing)

When you call Agent.launch(...) or AgentTeam.launch(...) (or run praisonai serve agents), the SDK starts a FastAPI server in a background thread and waits for it to become ready before returning. Previously that wait used a hard-coded 5-second timeout and silently ignored a timeout — if the server never became ready, the caller had no way to know.

PR #1655 makes two user-visible improvements:

1. The readiness timeout is now configurable via a new environment variable:

   • Name: PRAISONAI_SERVER_READY_TIMEOUT
   • Type: float (seconds)
   • Default: 5.0
   • Invalid values (e.g. "abc") fall back to 5.0 and log a WARNING: "Invalid PRAISONAI_SERVER_READY_TIMEOUT value. Using default 5.0s."

2. A diagnostic WARNING is logged when the server does not become ready within the timeout:

   Agent server on port <port> did not become ready within <timeout>s.
   Proceeding, but some features may not work correctly. Check server logs for startup errors.
   

   Behaviour is otherwise unchanged — .launch() still returns True and execution proceeds. This is purely additional observability for a previously silent failure mode.

Exact SDK snippet (ground truth)

# praisonaiagents/agents/agents.py — _AgentServerRegistry.start_server_if_needed
try:
    timeout = float(os.environ.get("PRAISONAI_SERVER_READY_TIMEOUT", "5.0"))
except ValueError:
    logger.warning("Invalid PRAISONAI_SERVER_READY_TIMEOUT value. Using default 5.0s.")
    timeout = 5.0
became_ready = ready_event.wait(timeout=timeout)

if not became_ready:
    logger.warning(
        "Agent server on port %s did not become ready within %.1fs. "
        "Proceeding, but some features may not work correctly. "
        "Check server logs for startup errors.",
        port,
        timeout,
    )

Decision: update existing pages (no new page)

Per AGENTS.md, we don't create dedicated pages for single env vars / trivial config knobs. Three existing pages currently hard-code the phrase "5s timeout" and must be updated. We should also add the env var to the troubleshooting / configuration tables.

Pages that MUST be updated

1. docs/deploy/servers/agents.mdx

Current text (Note block, ~line 73):

Server readiness is signalled deterministically (no fixed sleep); .launch() returns only after the port is accepting connections (5s timeout).

Required change: Replace (5s timeout) with text that reflects that the timeout is configurable, e.g.:

Server readiness is signalled deterministically (no fixed sleep); .launch() returns only after the port is accepting connections. The wait defaults to 5 seconds and is configurable via the PRAISONAI_SERVER_READY_TIMEOUT environment variable. If the server doesn't become ready in time, .launch() still returns and a warning is logged — check server logs for startup errors.

Also update the ## Troubleshooting table to add a row:

Issue	Fix
Agent server slow to start / "did not become ready" warning	Set PRAISONAI_SERVER_READY_TIMEOUT=10 (seconds) before launching, or check server logs for the underlying startup error.

Optional but recommended: add a short subsection ### Environment Variables near ## CLI Commands:

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PRAISONAI_SERVER_READY_TIMEOUT` | `5.0` | Seconds to wait for the FastAPI server to become ready after `.launch()` / `praisonai serve agents`. A warning is logged if exceeded; startup continues. |

Plus one user-friendly code example:

# Give the server more time on slow machines
export PRAISONAI_SERVER_READY_TIMEOUT=15
praisonai serve agents --port 8000

2. docs/features/agent-api-launch.mdx

Current text (Note block, after Example 4):

Server readiness is signalled deterministically (no fixed sleep); .launch() returns only after the port is accepting connections (5s timeout).

Required change: Same as page 1 — soften "(5s timeout)" to "default 5s, configurable via PRAISONAI_SERVER_READY_TIMEOUT".

Also add a new accordion in the ## Troubleshooting <AccordionGroup>:

<Accordion title="Server slow to start / readiness warning in logs">
  If you see `Agent server on port N did not become ready within 5.0s` in the logs, the FastAPI server took longer than the default 5s to come up. This is usually safe (`.launch()` still returns and the server keeps starting), but you can raise the wait:

  ```bash
  export PRAISONAI_SERVER_READY_TIMEOUT=15  # seconds

Common causes: slow imports, cold-start on resource-constrained machines, blocking startup hooks.

**Also extend the `## Launch Parameters` section with a short "Environment variables" subsection** (do not invent a `timeout=` keyword arg — it doesn't exist in the SDK; control is via env var only):

```markdown
### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PRAISONAI_SERVER_READY_TIMEOUT` | `5.0` | Seconds `.launch()` waits for the HTTP server to be ready. On timeout, a warning is logged and execution continues. |

3. docs/features/thread-safety.mdx

Current text (### Multi-team HTTP launch section):

Server readiness is signalled deterministically (no fixed sleep); .launch() returns only after the port is accepting connections (5s timeout).

Required change: Replace (5s timeout) with:

default 5s wait, configurable via the PRAISONAI_SERVER_READY_TIMEOUT environment variable; a warning is logged on timeout instead of silently proceeding

No other changes needed on this page.

Pages to grep for stale references (sanity sweep)

Before submitting the PR, grep the whole docs/ tree for any of:

• 5s timeout
• 5.0s timeout
• timeout=5.0 (in prose, not code)
• ready_event.wait

and update wording where appropriate.

Style / formatting requirements (per AGENTS.md)

• ✅ Keep wording user-focused and beginner-friendly — readers shouldn't need to know what ready_event or _AgentServerRegistry is.
• ✅ Do NOT put any of these changes in docs/concepts/ (that folder is human-only).
• ✅ Use Mintlify components (<Note>, <AccordionGroup>, etc.) consistent with the rest of each page.
• ✅ Active voice, one-sentence section intros, no forbidden phrases ("In this section…", "As you can see…", "It's important to note that…").
• ✅ Every code example should run as-is — no placeholder values.
• ✅ Match SDK ground truth exactly: variable name PRAISONAI_SERVER_READY_TIMEOUT, default 5.0, type float, no equivalent constructor / kwarg exists.
• ❌ Do not create a new dedicated page for this env var.
• ❌ Do not edit docs.json "Concepts" group entries.
• ❌ Do not invent a timeout keyword argument on .launch() — it doesn't exist.

Suggested user-flow diagram (optional, only if it improves clarity)

If you add a diagram to agent-api-launch.mdx, follow the AGENTS.md color scheme:

sequenceDiagram
    participant User
    participant Launch as .launch()
    participant Server as FastAPI server
    User->>Launch: agent.launch(port=8000)
    Launch->>Server: start in background thread
    Note over Launch,Server: waits up to<br/>PRAISONAI_SERVER_READY_TIMEOUT (5s default)
    alt ready in time
        Server-->>Launch: ready
        Launch-->>User: returns True
    else timed out
        Launch-->>User: returns True + WARNING logged
        Server-->>User: server may still come up shortly after
    end

Loading

Acceptance criteria for the follow-up PR

• docs/deploy/servers/agents.mdx no longer hard-codes "5s timeout"; env var is documented.
• docs/features/agent-api-launch.mdx Note block updated, troubleshooting accordion added, env var table added.
• docs/features/thread-safety.mdx ### Multi-team HTTP launch updated.
• No new file added under docs/concepts/.
• docs.json left untouched (no new nav entries needed).
• PR opened as draft against main from a feature branch.

References

• Upstream PR: fix: check agent server readiness timeout return value (fixes #1631) PraisonAI#1655
• Upstream issue: [Reliability] Agent server readiness timeout fires silently — return value not checked PraisonAI#1631
• SDK source: praisonaiagents/agents/agents.py → _AgentServerRegistry.start_server_if_needed
• Tests (for behavioural reference): praisonaiagents/tests/unit/agents/test_server_registry_timeout.py

[MervinPraison]

🤖 Auto-triaging with Claude. Analyzing issue and implementing a fix...

Claude will:

1. Classify this issue
2. Search codebase for root cause
3. Implement a minimal fix following AGENTS.md
4. Create a PR with the changes

[MervinPraison]

Claude finished @MervinPraison's task —— View job • claude/issue-347-20260513-0606 • [Create PR ➔](https://github.com/MervinPraison/PraisonAIDocs/compare/main...claude/issue-347-20260513-0606?quick_pull=1&title=Issue%20%23347%3A%20Changes%20from%20Claude&body=This%20PR%20addresses%20issue%20%23347%0A%0AGenerated%20with%20%5BClaude%20Code%5D(https%3A%2F%2Fclaude.ai%2Fcode)

---

Documentation Update Complete ✅

I've successfully updated the documentation to reflect the new configurable PRAISONAI_SERVER_READY_TIMEOUT environment variable.

Tasks Completed:

• Setup git identity and auth
• Read AGENTS.md for documentation standards
• Read all three files that need updates
• Update docs/deploy/servers/agents.mdx (remove hard-coded "5s timeout", add env var docs)
• Update docs/features/agent-api-launch.mdx (update Note block, add troubleshooting, add env var table)
• Update docs/features/thread-safety.mdx (update Multi-team HTTP launch section)
• Verify all changes follow AGENTS.md guidelines
• Commit and push changes
• Create pull request

Changes Made

docs/deploy/servers/agents.mdx:

• Replaced hard-coded "5s timeout" with configurable timeout description
• Added Environment Variables section documenting PRAISONAI_SERVER_READY_TIMEOUT
• Added troubleshooting entry for slow server startup scenarios
• Included code example showing custom timeout usage

docs/features/agent-api-launch.mdx:

• Updated Note block to reflect configurable timeout
• Added Environment Variables subsection under Launch Parameters
• Added new troubleshooting accordion for slow server startup scenarios

docs/features/thread-safety.mdx:

• Updated Multi-team HTTP launch section description with configurable timeout

All updates follow the AGENTS.md standards and maintain the user-friendly, beginner-focused tone. The documentation now accurately reflects that the server readiness timeout is configurable via the PRAISONAI_SERVER_READY_TIMEOUT environment variable (default: 5.0 seconds).

Pull Request Created

#348 - docs: document configurable agent server readiness timeout (PRAISONAI_SERVER_READY_TIMEOUT)

--- | Branch: claude/issue-347-20260513-0606