fix(v2): make debugger agent configurable

[MaiaJP-AIXplain]

Summary

The debugger previously resolved every request through one hardcoded agent ID. That permanently pinned aix.Debugger().run(...), Debugger.debug_response(...), and response.debug() to a single shared agent, so teams running their own debugger agent could not use these SDK entry points.

This change makes the target configurable through the new debugger_agent_id argument on all three entry points and changes the default to 6a83989b20d5ce8082cdc775 (aiXplain Debugger Agent c3).

Resolution precedence is:

1. Explicit debugger_agent_id argument.
2. AIXPLAIN_DEBUGGER_AGENT_ID environment variable.
3. The module-level DEBUGGER_AGENT_ID default.

The environment variable is read at call time, so changes made after importing the SDK are honored. DEBUGGER_AGENT_ID remains importable with the same name, making this non-breaking apart from the requested default-value change.

Merge precondition

The new default agent is currently deployed on dev only. It must be deployed to production before this PR merges. Until then, production users can select an available agent with the explicit argument or environment override.

Validation

• .venv/bin/python -m pytest tests/unit/v2/test_meta_agents.py — 61 passed.
• ruff check aixplain/v2/meta_agents.py aixplain/v2/agent.py tests/unit/v2/test_meta_agents.py — all checks passed.
• ruff format --check aixplain/v2/meta_agents.py aixplain/v2/agent.py tests/unit/v2/test_meta_agents.py — 3 files already formatted.
• Regenerated the committed debugger API references and LLM documentation sections.

[elsheikhams99]

Verified: all 61 tests in tests/unit/v2/test_meta_agents.py pass. The core threading (AgentRunResult.debug → Debugger.debug_response → Debugger.run → _get_debugger_agent) is internally consistent, breaks no existing signatures (new params are keyword-appended, no **kwargs collision), and debugger_agent_id is correctly consumed rather than leaked into the downstream agent.run(**kwargs). The AIXPLAIN_* env-var pattern matches existing precedent in client.py:59-60.

---

Blocking

🔴 1. Docs regenerated on the feature branch — 46 view_source links point at a branch that will be deleted

docs/api-reference/python/aixplain/v2/agent.md:14 and 45 more, across three files:

-[[view_source]](https://github.com/aixplain/aiXplain/blob/main/aixplain/v2/agent.py#L45)
+[[view_source]](https://github.com/aixplain/aiXplain/blob/fm/sdk-debugger-agent-id-e5/aixplain/v2/agent.py#L45)

Cause: pydoc-markdown.yml sets source_linker.use_branch: true, so pydoc-markdown stamps whatever branch it was run on.

Why this is blocking rather than cosmetic: .github/workflows/docs.yaml regenerates docs on push to main, but its add-paths is limited to docs/api-reference/python/**. So the two .md files self-heal on the next bot PR, but docs/llms-full.txt is never touched by the bot — its 7 branch-stamped links (against 357 correct blob/main ones) 404 permanently once the branch is deleted.

Fix (pick one):

• Preferred — drop all three docs files from the PR; let the docs bot regenerate them post-merge. But note it won't fix llms-full.txt, so also:

• sed -i 's|blob/fm/sdk-debugger-agent-id-e5/|blob/main/|g' \
    docs/llms-full.txt docs/api-reference/python/aixplain/v2/agent.md \
    docs/api-reference/python/aixplain/v2/meta_agents.md

• Separately worth filing: use_branch: true makes every non-main doc regen wrong. Pinning to main in pydoc-markdown.yml removes this footgun for good.

🔴 2. Default agent ID swapped to a new hard-coded prod ID with zero verification path

aixplain/v2/meta_agents.py:42 — 696fdccad63e898317c097a0 → 6a83989b20d5ce8082cdc775.

Three facts compound here, and the direct-to-main target is what makes it blocking:

• No functional/integration test touches the debugger at all (grep -rl debug tests/functional/ → nothing). The only coverage is a tautological unit assertion at test_meta_agents.py:865 that re-states the literal.
• .github/workflows/main.yaml triggers on push to main/test and workflow_dispatch — there is no pull_request trigger, so this PR runs no CI before merge.
• Merging to main puts it in the published SDK path. If that agent isn't live and readable by an arbitrary customer team API key on prod, every response.debug() without an override raises for all users, and it's discovered post-merge.

Fix: confirm the new ID is deployed and gettable with a non-privileged prod key before merging — e.g. Agent.get("6a83989b20d5ce8082cdc775") against platform-api.aixplain.com with a fresh key. Since CI won't do it for you here, paste the result in the PR. (The env-var escape hatch this PR adds is a genuine improvement over the previous hard-coded-only state — it just doesn't protect users who never set it.)

---

Non-blocking

🟡 3. Explicit "" bypasses the fallback chain

aixplain/v2/meta_agents.py:54 uses is not None for the argument but truthiness for the env var. A caller doing response.debug(debugger_agent_id=os.getenv("MY_DEBUGGER", "")) — a common shape — sends "" straight to Agent.get("") instead of falling back.

if debugger_agent_id:
    return debugger_agent_id
return os.getenv("AIXPLAIN_DEBUGGER_AGENT_ID") or DEBUGGER_AGENT_ID

Consistent truthiness across both tiers, and it costs nothing.

🟡 4. Duplicate test

test_get_debugger_agent_reads_environment_at_call_time is line-for-line equivalent to test_get_debugger_agent_uses_environment_override — both monkeypatch.setenv inside the patch block and call the same path. Its docstring claims it covers "an override set after module import," but nothing in it distinguishes import-time from call-time. To actually earn its name it would need to import the module first, then set the env. Otherwise delete it.

🟢 5. Tautological constant test

test_debugger_agent_id_constant asserts the constant equals its own literal — it can only ever fail as a reminder to edit two places. Pre-existing pattern, so fine to leave, but it's the reason the ID change touched tests at all.

🟢 6. Unrelated scope creep in AGENTS.md

The new "Maintaining this file" section at AGENTS.md:224-230 is meta-guidance about the file itself, unrelated to making the debugger configurable. Harmless, but it makes the commit do two things — worth splitting if the team cares about clean history on main.

🟢 7. AIXPLAIN_DEBUGGER_AGENT_ID undocumented outside generated API docs

The env var appears only in docstrings and their pydoc output. Since it's the intended production escape hatch for #2, a line in the README's env-var/setup section would make it discoverable to someone whose debug() just broke.

---

Summary

	Count
Blocking	2 — branch-stamped doc links, unverified prod agent ID
Non-blocking	5

The design is sound and the implementation is clean. Both blockers are about the merge target rather than the logic: docs generated off main leave dead links that the bot can't repair in llms-full.txt, and a hard-coded prod ID reaches the published SDK with neither PR-triggered CI nor functional coverage behind it.