Fix blockbuster failing on blocking calls inside Agent.__init__

[dangusev]

BlockBuster fails some integration tests because Instructions object parses markdown files on __init__ in a blocking way.
Making it non-blocking would be more clunky and require more code, and it's ok for Instructions.__init__ to be blocking since it's created once and before any async work.

So the solution is:

• To skip BlockBuster checks for all Agent.__init__.
• To allow LLM.set_instructions() to accept plain str.

Summary by CodeRabbit

• Refactor

  • LLM instruction-setting methods now accept plain strings in addition to structured instruction objects, simplifying API usage and improving flexibility across all LLM providers.

• Tests

  • Updated test suite to validate the enhanced instruction API.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

The set_instructions method signature is generalized across the LLM framework to accept both Instructions objects and plain strings, with type dispatch logic added to the core implementation. Corresponding test cases are updated to pass strings directly, and test fixtures are adjusted to permit blocking calls in Agent.__init__.

Changes

Cohort / File(s)	Summary
Core LLM API Update agents-core/vision_agents/core/llm/llm.py	Updated set_instructions method signature to accept Instructions | str with type-based dispatch logic; raises TypeError for invalid input types
Test Fixture Configuration conftest.py	Added imports for AudioFormat, PcmData, and Participant; augmented blockbuster fixture to explicitly permit blocking calls within Agent.__init__
AWS Plugin Tests plugins/aws/tests/test_aws.py, plugins/aws/tests/test_aws_realtime.py	Updated test calls to set_instructions to pass strings directly instead of Instructions objects; removed Instructions import from test files
Gemini Plugin Tests plugins/gemini/tests/test_gemini_llm.py	Updated test to pass string argument to set_instructions; removed Instructions import
OpenAI Plugin plugins/openai/vision_agents/plugins/openai/openai_realtime.py, plugins/openai/tests/test_openai_realtime.py	Updated Realtime.set_instructions signature to accept Instructions | str; test updated to pass string argument

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Areas requiring extra attention:
  • Type dispatch logic and error handling in agents-core/vision_agents/core/llm/llm.py, especially the TypeError path and Instructions.full_reference usage
  • Blockbuster fixture modifications in conftest.py to ensure Agent.__init__ blocking behavior is correctly enabled across test suite
  • Verify that all plugin implementations (Realtime classes) properly support the expanded type signature

Possibly related PRs

• Refactor instructions parsing #204: Directly modifies the same set_instructions method in the core LLM API; coordinated implementation of the signature change
• [AI-271] Elevenhour labs Scribe2 #170: Adjusts Participant usage and fixture configuration in conftest.py, overlapping with fixture modifications

Suggested labels

agents-core, plugins, config

Suggested reviewers

• Nash0x7E2

Poem

A method splits its shell, accepting both—
the strict form and the whispered word.
Type checks bloom like anthills, precise:
string or object, each path leads home.
The fixtures crack open their careful doors,
letting blockage through init's threshold.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 63.64% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the primary change: fixing blockbuster failures caused by blocking calls in Agent.init, which is the core motivation for the conftest.py modifications.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/instructions-make-parsing-async

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (4)

plugins/aws/tests/test_aws.py (2)

30-32: Avoid hasattr and getattr per coding guidelines.

The coding guidelines explicitly state to avoid using hasattr, getattr, delattr, and setattr. Consider using normal attribute access with a try/except or checking for response.exception is None directly if the attribute is always expected.

-        assert not hasattr(response, "exception") or response.exception is None, (
-            f"Response should not have an exception, got: {getattr(response, 'exception', None)}"
-        )
+        assert response.exception is None, (
+            f"Response should not have an exception, got: {response.exception}"
+        )

Based on coding guidelines, prefer normal attribute access over hasattr/getattr.

---

41-41: Remove redundant @pytest.mark.asyncio decorators.

Per coding guidelines, @pytest.mark.asyncio is not needed as it's automatic. This applies to multiple tests in this file (lines 41, 49, etc.).

plugins/gemini/tests/test_gemini_llm.py (1)

47-47: Avoid hasattr per coding guidelines.

Consider using normal attribute access instead of hasattr(response.original, "text").

-        assert hasattr(response.original, "text")  # Gemini response has text attribute
+        assert response.original.text is not None  # Gemini response has text attribute

Based on coding guidelines, prefer normal attribute access.

conftest.py (1)

63-63: Path construction may be fragile.

The path agent_cls_file is constructed by replacing . with / and appending .py. This assumes the module maps directly to a file path, which may break if the package structure changes or uses namespace packages.

Consider using inspect.getfile(Agent) for a more robust approach:

import inspect
agent_cls_file = inspect.getfile(Agent)

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 28674b8 and fec072f.

📒 Files selected for processing (7)

• agents-core/vision_agents/core/llm/llm.py (1 hunks)
• conftest.py (2 hunks)
• plugins/aws/tests/test_aws.py (1 hunks)
• plugins/aws/tests/test_aws_realtime.py (2 hunks)
• plugins/gemini/tests/test_gemini_llm.py (1 hunks)
• plugins/openai/tests/test_openai_realtime.py (1 hunks)
• plugins/openai/vision_agents/plugins/openai/openai_realtime.py (1 hunks)

🧰 Additional context used

📓 Path-based instructions (2)

**/*test*.py

📄 CodeRabbit inference engine (.cursor/rules/python.mdc)

**/*test*.py: Never mock in tests; use pytest for testing
Mark integration tests with @pytest.mark.integration decorator
@pytest.mark.asyncio is not needed - it is automatic

Files:

• plugins/gemini/tests/test_gemini_llm.py
• plugins/aws/tests/test_aws_realtime.py
• plugins/aws/tests/test_aws.py
• plugins/openai/tests/test_openai_realtime.py
• conftest.py

**/*.py

📄 CodeRabbit inference engine (.cursor/rules/python.mdc)

**/*.py: Never adjust sys.path in Python code
Never write except Exception as e - use specific exception handling
Avoid using getattr, hasattr, delattr and setattr; prefer normal attribute access in Python
Docstrings should follow the Google style guide for docstrings

Files:

• plugins/gemini/tests/test_gemini_llm.py
• plugins/openai/vision_agents/plugins/openai/openai_realtime.py
• plugins/aws/tests/test_aws_realtime.py
• plugins/aws/tests/test_aws.py
• agents-core/vision_agents/core/llm/llm.py
• plugins/openai/tests/test_openai_realtime.py
• conftest.py

🧬 Code graph analysis (6)

plugins/gemini/tests/test_gemini_llm.py (2)

agents-core/vision_agents/core/llm/llm.py (1)

• set_instructions (179-193)

plugins/openai/vision_agents/plugins/openai/openai_realtime.py (1)

• set_instructions (471-473)

plugins/openai/vision_agents/plugins/openai/openai_realtime.py (2)

agents-core/vision_agents/core/llm/llm.py (1)

• set_instructions (179-193)

agents-core/vision_agents/core/instructions.py (1)

• Instructions (15-115)

plugins/aws/tests/test_aws_realtime.py (4)

plugins/openai/tests/test_openai_realtime.py (1)

• realtime (20-30)

plugins/gemini/tests/test_gemini_realtime.py (1)

• realtime (15-23)

agents-core/vision_agents/core/llm/llm.py (1)

• set_instructions (179-193)

plugins/openai/vision_agents/plugins/openai/openai_realtime.py (1)

• set_instructions (471-473)

plugins/aws/tests/test_aws.py (2)

agents-core/vision_agents/core/llm/llm.py (1)

• set_instructions (179-193)

plugins/openai/vision_agents/plugins/openai/openai_realtime.py (1)

• set_instructions (471-473)

agents-core/vision_agents/core/llm/llm.py (2)

plugins/openai/vision_agents/plugins/openai/openai_realtime.py (1)

• set_instructions (471-473)

agents-core/vision_agents/core/instructions.py (1)

• Instructions (15-115)

plugins/openai/tests/test_openai_realtime.py (4)

plugins/aws/tests/test_aws_realtime.py (1)

• realtime (20-31)

plugins/gemini/tests/test_gemini_realtime.py (1)

• realtime (15-23)

agents-core/vision_agents/core/llm/llm.py (1)

• set_instructions (179-193)

plugins/openai/vision_agents/plugins/openai/openai_realtime.py (1)

• set_instructions (471-473)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: unit / Mypy
• GitHub Check: unit / Test "not integration"

🔇 Additional comments (9)

plugins/aws/tests/test_aws.py (1)

149-149: LGTM!

The change to pass a plain string to set_instructions aligns with the updated API that now accepts Instructions | str.

plugins/gemini/tests/test_gemini_llm.py (1)

87-87: LGTM!

The change to pass a plain string to set_instructions is consistent with the updated API across the codebase.

plugins/aws/tests/test_aws_realtime.py (2)

27-27: LGTM!

The fixture now passes a plain string to set_instructions, consistent with the updated API.

---

37-39: LGTM!

Consistent usage of the string-based set_instructions API within the test.

agents-core/vision_agents/core/llm/llm.py (2)

179-193: LGTM!

The implementation correctly handles both str and Instructions types with proper type dispatch. The docstring follows Google style, and the TypeError provides a clear message for invalid inputs. This is the core change that enables the API flexibility across all plugins.

---

186-189: The review comment is not applicable—None is not a valid use case.

The method's type signature explicitly specifies instructions: Instructions | str, excluding None. The Agent class always provides a non-None string default, and no callers in the codebase pass None to set_instructions. The current implementation correctly raises a TypeError for invalid types, which is consistent with the explicit type contract. If None were to become a valid input in the future, the type signature would need to be updated to Optional[Instructions | str], but there is no evidence or requirement for this.

conftest.py (1)

59-68: The review comment is incorrect — bb.functions is the correct attribute name and the code is properly implemented.

The BlockBuster library (version ≥1.5.5,<1.6) exposes a .functions dict that maps blocking function names to BlockBusterFunction instances. Each BlockBusterFunction has a can_block_in() method, which is correctly called in the code at line 67. The original concern referencing BlockBuster.bb appears to be based on a misunderstanding of the library's API. The implementation is correct as written.

plugins/openai/vision_agents/plugins/openai/openai_realtime.py (1)

471-473: Override correctly mirrors core LLM.set_instructions behavior

The widened Instructions | str signature and delegation to super().set_instructions keep the type logic centralized while ensuring realtime_session["instructions"] is always the resolved string (self._instructions). This is consistent with vision_agents.core.llm.llm.LLM.set_instructions and looks correct.

plugins/openai/tests/test_openai_realtime.py (1)

19-30: Test fixture correctly uses string-based instructions API

Calling realtime.set_instructions("be friendly") aligns this integration test with the updated set_instructions(Instructions | str) API and avoids unnecessary Instructions construction in the fixture. Looks good.