[AGX1-97] /linear AGX1-97 Add a troubleshooting section to the README.

[danielmillerp]

Automated PR from SWE Destroyer agent.

Prompt: /linear AGX1-97 Add a troubleshooting section to the README.md with common issues and fixes

Summary

• Adds a ## Troubleshooting section to README.md covering common issues users encounter
• Covers authentication errors, installation problems, connection/timeout issues, rate limiting, debug logging, agent debugging with VS Code, and type checking tips
• Each issue includes a clear description and working code examples

Test plan

• Review the new Troubleshooting section for accuracy against the existing SDK behavior
• Verify all code examples in the section are syntactically correct
• Confirm the section renders correctly on GitHub

🤖 Generated with Claude Code

Greptile Summary

Adds a comprehensive Troubleshooting section to README.md covering authentication errors, installation issues, connection/timeout problems, rate limiting, debug logging, agent debugging with VS Code, and type checking tips. All code examples are syntactically correct and reference valid SDK exports, environment variables, and CLI flags.

• The new content is technically accurate — imports, error class names, env vars (AGENTEX_SDK_API_KEY, AGENTEX_LOG), and CLI flags (--debug-worker, --wait-for-debugger, --debug-port) are all verified against the source.
• There is an unused import httpx in the proxy configuration example that should be removed.
• ~70% of the Troubleshooting section duplicates existing README content (Debugging, Logging, Retries, Timeouts, Proxy config, null-vs-missing, version check). This creates a documentation maintenance burden and should be addressed by either cross-linking or consolidating.

Confidence Score: 4/5

• This is a documentation-only change with no runtime impact; safe to merge with minor cleanup.
• Score of 4 because the change is documentation-only (zero code risk), all examples are technically accurate, and the only issues are an unused import in a code snippet and significant content duplication with existing README sections — both style concerns rather than correctness issues.
• README.md has substantial duplication with its own existing content that should be addressed to avoid maintenance drift.

Important Files Changed

Filename	Overview
README.md	Adds a 200-line Troubleshooting section with accurate code examples, but has an unused import and substantially duplicates existing README content (debugging, logging, retries, timeouts, proxy config, null-vs-missing, version check).

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User encounters issue] --> B{Issue type?}
    B -->|Auth/API Key| C[Authentication & API Key Issues]
    B -->|Install| D[Installation Issues]
    B -->|Network| E[Connection & Timeout Errors]
    B -->|429 errors| F[Rate Limiting]
    B -->|Need logs| G[Environment & Logging]
    B -->|Agent dev| H[Agent Development Issues]
    B -->|Types/IDE| I[Type Checking & IDE Integration]

    C --> C1[Set AGENTEX_SDK_API_KEY env var]
    C --> C2[Pass api_key to Agentex constructor]
    D --> D1[pip install agentex-sdk]
    D --> D2[Check Python >= 3.9]
    E --> E1[Configure proxy via DefaultHttpxClient]
    E --> E2[Increase timeout parameter]
    F --> F1[Increase max_retries]
    G --> G1[Set AGENTEX_LOG=debug]
    H --> H1[Check manifest.yaml]
    H --> H2[Use --debug-worker flag]
    I --> I1[Set typeCheckingMode to basic]
    I --> I2[Use model_fields_set]

Loading

_{Last reviewed commit: de68de9}