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"
[ -n "$OPENBOX_AGENT_DID" ] && echo "OPENBOX_AGENT_DID is set" || echo "OPENBOX_AGENT_DID is NOT set"
[ -n "$OPENBOX_AGENT_PRIVATE_KEY" ] && echo "OPENBOX_AGENT_PRIVATE_KEY is set" || echo "OPENBOX_AGENT_PRIVATE_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()
  4. If Require signing is enabled, set both OPENBOX_AGENT_DID and OPENBOX_AGENT_PRIVATE_KEY

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 and DID identity match the agent registered in OpenBox
  4. Check that validate=True (default) — this catches bad credentials at startup

OpenBox Returns 401 Invalid Token or Agent Identity​

When Require signing is enabled for the agent, OpenBox validates both the API key and the DID signature.

Check these common causes:

  1. OPENBOX_AGENT_DID belongs to a different OpenBox agent than OPENBOX_API_KEY
  2. OPENBOX_AGENT_PRIVATE_KEY is not the base64 raw Ed25519 seed returned by OpenBox
  3. Only one DID value is set; the SDK requires both or neither
  4. The agent identity was rotated in OpenBox but the runtime still uses the old private key
  5. agent_name does not match the registered agent, so policy and behavior rules appear to be missing

If Require signing is disabled for the agent, remove both DID environment variables and authenticate with OPENBOX_API_KEY only.

Double Approval or Pause Behavior​

This usually means both DeepAgents' built-in interrupt_on and OpenBox's HITL approval are targeting the same tool. The SDK enforces OpenBox approval verdicts, but it does not disable DeepAgents' own interrupt behavior.

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. Verify the tool name is task — the SDK detects subagents from DeepAgents task tool calls. Custom dispatch mechanisms won't be detected as subagents automatically.

  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".

  3. Keep known_subagents aligned — this keeps middleware introspection and runtime configuration clear, but the actual subagent detection comes from the task tool payload:

middleware = create_openbox_middleware(
    # ...
    known_subagents=["researcher", "editor", "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.