Skip to main content
Last updated on
Tags:
Options
Open in ChatGPTAsk ChatGPT about this pageOpen in ClaudeAsk Claude about this page

Troubleshooting

Common issues and solutions when integrating Deep Agents with OpenBox.

Middleware Not Connecting to OpenBox​

Check that your environment variables are set:

[ -n "$OPENBOX_URL" ] && echo "OPENBOX_URL is set" || echo "OPENBOX_URL is NOT set"
[ -n "$OPENBOX_API_KEY" ] && echo "OPENBOX_API_KEY is set" || echo "OPENBOX_API_KEY is NOT set"

Verify step by step:

  1. Confirm OPENBOX_URL and OPENBOX_API_KEY are set (or passed as api_url/api_key parameters)
  2. Run your agent and check logs for OpenBox SDK initialized successfully
  3. If using .env, ensure python-dotenv is installed and load_dotenv() is called before create_openbox_middleware()

If you get OpenBoxInsecureURLError, your OPENBOX_URL uses HTTP for a non-localhost address. Use HTTPS:

# Wrong
OPENBOX_URL=http://core.openbox.ai

# Correct
OPENBOX_URL=https://core.openbox.ai

No Sessions in Dashboard​

If sessions don't appear after running your agent:

  1. Ensure the middleware initialized successfully (check for OpenBox SDK initialized successfully in logs)
  2. Confirm the agent completed at least one invocation — sessions are created on abefore_agent
  3. Verify the API key matches the agent registered in OpenBox (agent names must match exactly)
  4. Check that validate=True (default) — this catches bad credentials at startup

HITL Conflict Warning​

WARNING: HITL conflict detected — "export_data" is listed in DeepAgents interrupt_on
and is also subject to OpenBox REQUIRE_APPROVAL policy.

This means both DeepAgents' built-in interrupt_on and OpenBox's HITL approval are targeting the same tool. The SDK continues to function, but you may get double-interruption.

Fix: Choose one mechanism:

  • Use OpenBox HITL — Remove the tool from DeepAgents' interrupt_on list. OpenBox handles approval via the dashboard.
  • Use DeepAgents interrupt — Remove the REQUIRE_APPROVAL policy for that tool in OpenBox.

Governance Blocks or Halts Your Agent​

When a policy triggers, the SDK raises a governance exception. This is expected — it means governance is working.

ExceptionMeaningRecoverable?
GovernanceBlockedErrorA single tool was blockedYes — agent can continue
GovernanceHaltErrorSession terminated (HALT, rejection, or expiry)No — agent should stop
GuardrailsValidationErrorPII or content policy violationNo — input rejected

To investigate:

  1. Open the OpenBox Dashboard
  2. Go to your agent → Overview tab
  3. Open the session to see which rule triggered the block

See Error Handling for exception types and handling patterns.

Subagent Not Being Governed​

If subagent dispatches aren't appearing as governed tool calls:

  1. Check known_subagents — the subagent name must be listed:
middleware = create_openbox_middleware(
    # ...
    known_subagents=["researcher", "editor", "general-purpose"],
)

  1. Verify the tool name is task — the SDK only detects subagents from task tool calls. Custom dispatch mechanisms won't be detected.

  2. Check the subagent_type argument — the subagent resolver extracts the name from tool_args["subagent_type"]. If missing, it falls back to "general-purpose".

Enable debug logging to see subagent detection:

OPENBOX_DEBUG=1 python content_writer.py

Approval Requests Not Appearing​

If your agent is paused waiting for approval but nothing shows in the Approvals page:

  1. Confirm the behavioral rule is set to Require Approval (not Block)
  2. Check that the agent's trust tier matches the rule conditions
  3. Verify the approval timeout hasn't already expired
  4. Check governance_timeout — if too short, the middleware may time out before the approval is created

See Approvals for how the approval queue works.

OpenAI or LLM API Errors​

The demo uses LangChain's init_chat_model with the format provider:model-name:

ProviderExample Value
OpenAIopenai:gpt-4o-mini
Anthropicanthropic:claude-sonnet-4-5-20250929
Googlegoogle-genai:gemini-2.0-flash

If you're seeing LLM errors:

  1. Check that OPENAI_API_KEY (or your provider's key) is set in .env
  2. Verify the model string format is provider:model-name
uv run python3 -c "
from dotenv import load_dotenv
load_dotenv()
from langchain.chat_models import init_chat_model
llm = init_chat_model('openai:gpt-4o-mini')
print(llm.invoke('Say hello').content)
"

Tavily or Image Generation Errors​

The demo's optional features require additional API keys:

FeatureEnvironment VariableRequired?
Web search (researcher subagent)TAVILY_API_KEYOptional — researcher returns error without it
Cover image generationGOOGLE_API_KEYOptional — generate_cover returns error without it
Social media imagesGOOGLE_API_KEYOptional — generate_social_image returns error without it

The agent handles missing keys gracefully — tools return error messages instead of crashing. To enable all features, set the keys in .env.

Debug Logging​

Enable verbose SDK logging to see governance decisions as they happen:

OPENBOX_DEBUG=1 python content_writer.py

This logs every middleware hook invocation, governance request, verdict, and subagent detection to stderr.

You can also set logging levels programmatically:

import logging
logging.getLogger("openbox_langgraph").setLevel(logging.DEBUG)
logging.getLogger("openbox_deepagent").setLevel(logging.DEBUG)

Inspect the full event trace in the OpenBox Dashboard under Agents → your agent → Details → Event Log Timeline.