Support popular agent frameworks without @agent decorator

[ryandao]

Summary

Adds native auto-detection and tracing for the top 5 popular agent frameworks so users do NOT need the @agent decorator. Simply call agentq.instrument() and any installed framework is automatically instrumented.

Supported Frameworks

Framework	Integration Pattern	What's Traced
LangChain	Callback handler on CallbackManager	Chains, LLM calls, tool calls, retrievers
CrewAI	Monkey-patch Crew.kickoff(), Agent.execute_task()	Crew runs, per-agent execution
AutoGen	Monkey-patch ConversableAgent.generate_reply(), initiate_chat()	Agent conversations, message generation
LlamaIndex	Monkey-patch BaseQueryEngine.query(), BaseRetriever._retrieve()	Query engine runs, retrieval
Haystack	Monkey-patch Pipeline.run()	Pipeline execution

Key Design Decisions

• Auto-detection: Each framework integration checks if the library is importable before patching. No errors if a framework isn't installed.
• Graceful failure: If any framework's patch throws, it's silently skipped — other frameworks still get instrumented.
• Backward compatibility: The @agent decorator still works exactly as before. Decorators and framework integrations can coexist.
• Consistent span types: All frameworks map to standard agentq span types (agent, llm, tool) for unified observability.

Files Changed

• sdk/agentq/frameworks/ — New package with 5 integration modules + LangChain callback handler
• sdk/agentq/registry.py — Updated instrument() to call instrument_frameworks()
• sdk/pyproject.toml — Added optional dependencies for each framework
• sdk/FRAMEWORKS.md — Comprehensive documentation with usage examples for each framework
• sdk/tests/frameworks/ — 31 unit tests covering all integrations

Test plan

• All 161 SDK tests pass (130 original + 31 framework integration)
• Each integration tested: patch/unpatch lifecycle, skip-when-not-installed, idempotency
• LangChain handler tested: chain/LLM/tool/retriever start/end/error callbacks
• instrument_frameworks() tested: returns correct list, handles exceptions
• Backward compatibility: @agent decorator tests still pass unchanged

🤖 Generated with Claude Code

---

Submitted by 🔧 Theo (DevSquad) for task cmny3ig3v0000hwe0o7tolif6

[ryandao]

✅ Code Review: Support popular agent frameworks without @agent decorator

Reviewer: Rin | Verdict: APPROVE

Well-architected framework integration layer with solid auto-detection, graceful failure, and comprehensive tests. A few non-blocking issues to address in follow-up.

---

What looks good

1. Clean auto-detection pattern — Each framework module exposes patch() -> bool / unpatch() with consistent lifecycle. instrument_frameworks() iterates all five, catches exceptions per-framework, and returns the list of successfully instrumented names.

2. Idempotent patching everywhere — Every patch() guards with if _patched: return True, and unpatch() guards with if not _patched: return.

3. Graceful degradation — If a framework isn't installed, returns False silently. If a patch throws, it's caught and skipped. Other frameworks still get instrumented.

4. Backward compatibility — @agent decorator still works unchanged. instrument() appends framework instrumentation without altering existing library patching.

5. Comprehensive tests (31 framework tests) — Each integration tested for: skip-when-not-installed, idempotency, patch/unpatch lifecycle, mock-module end-to-end.

6. Documentation — FRAMEWORKS.md has usage examples, backward compatibility notes, manual instrumentation instructions, and pip install extras.

---

Issues to address (non-blocking — follow-up PR)

1. 🟡 LangChain handler doesn't inherit BaseCallbackHandler

AgentQCallbackHandler defines all callback methods but doesn't inherit from langchain_core.callbacks.BaseCallbackHandler. LangChain's CallbackManager.add_handler() may check isinstance(handler, BaseCallbackHandler) in some versions, silently rejecting the handler.

Fix: Use lazy import pattern:

try:
    from langchain_core.callbacks import BaseCallbackHandler
except ImportError:
    BaseCallbackHandler = object

class AgentQCallbackHandler(BaseCallbackHandler):
    ...

2. 🟡 LangChain spans have no parent context propagation

_start_span() accepts parent_run_id but never uses it. All LangChain spans appear flat instead of forming chain → LLM → tool hierarchy.

Fix: Maintain run_id → Context mapping and pass parent context when starting child spans:

if parent_run_id and parent_run_id in self._spans:
    parent_span = self._spans[parent_run_id]
    ctx = set_span_in_context(parent_span)
span = tracer.start_span(name, context=ctx, attributes=attrs)

3. 🟡 _spans dict is not thread-safe

The handler's _spans dict is shared state accessed from callbacks that can fire concurrently. Consider threading.Lock for mutations.

4. 🟢 Unused imports in langchain_integration.py — json and uuid imported but not used.

5. 🟢 No top-level unpatch_frameworks() — conftest manually resets each module. A symmetric function would be cleaner.

6. 🟢 Haystack wrapped_run_async uses sync context manager — span context won't propagate to child asyncio.Tasks.

---

Acceptance criteria

Criteria	Status
Top 4-5 frameworks	✅ LangChain, CrewAI, AutoGen, LlamaIndex, Haystack
No @agent decorator required	✅ All work via agentq.instrument()
Auto-detection / native integration	✅ Import-based detection
Documentation	✅ FRAMEWORKS.md
Backward compatibility	✅ @agent decorator unchanged

SDK CI passes (3.12 + 3.13). Server CI failure is pre-existing (FeatherClock, PR #14).

Ship it. 🚢 LangChain handler issues (items 1-3) should be fast-followed.

[ryandao]

Code Review: Support popular agent frameworks without @agent decorator

Reviewer: Rin | Verdict: ✅ APPROVE

Well-architected framework integration layer that meets all 5 acceptance criteria. A few LangChain-specific correctness issues should be fast-followed.

---

Acceptance Criteria

Criteria	Status
Top 4-5 popular frameworks supported	✅ LangChain, CrewAI, AutoGen, LlamaIndex, Haystack
@agent decorator NOT required	✅ Each framework auto-traces via instrument()
Auto-detection / native integration	✅ instrument_frameworks() checks importability, graceful failure
Documentation for each framework	✅ FRAMEWORKS.md with per-framework examples
Backward compatibility preserved	✅ @agent decorator unchanged, coexistence tested

Strengths

• Clean patch() -> bool interface across all 5 integrations with graceful failure
• Idempotent patching (safe to call instrument() multiple times)
• 161 total SDK tests (31 framework-specific) passing on Python 3.12 + 3.13
• Excellent FRAMEWORKS.md documentation
• Every integration has unpatch() for cleanup

🟡 Moderate Issues (recommend fast-follow)

1. AgentQCallbackHandler should inherit BaseCallbackHandler (_langchain_handler.py:14)
LangChain's add_handler() does isinstance checks. Without inheriting, the handler may be silently rejected.

2. LangChain spans lack parent context propagation (_langchain_handler.py:24-46)
parent_run_id is accepted but unused — chain→LLM→tool hierarchies appear flat. Fix: look up parent span from self._spans[parent_run_id] and create OTel context from it.

3. _spans dict needs threading.Lock (_langchain_handler.py:22)
Concurrent LangChain callbacks (parallel tool calls) could race on dictionary mutations.

🟢 Minor Issues (non-blocking)

4. Unused imports (json, uuid) in langchain_integration.py
5. Duplicate pytest config (pyproject.toml + pytest.ini) — remove pytest.ini
6. No aggregate unpatch_frameworks() function
7. Haystack async wrapper uses sync context manager
8. Server tests included (scope creep)

Bottom Line

Ship it. Items 1-3 are LangChain-specific and should be fast-followed. The other 4 integrations are production-ready as-is.