agenticdome-python-sdk 1.0.6__py3-none-any.whl → 1.0.7__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: agenticdome-python-sdk
3
- Version: 1.0.6
3
+ Version: 1.0.7
4
4
  Summary: Official Python SDK for AgentGuard Intelligence Engine and Action Firewall.
5
5
  Home-page: https://github.com/agenticdome/agenticdome-python-sdk-python
6
6
  Author: AgenticDome
@@ -109,7 +109,7 @@ The package includes:
109
109
  - MCP host, gateway, and third-party server forwarding wrappers
110
110
  - AWS Bedrock Runtime, Converse, InvokeModel, tool/action, and retrieval wrappers
111
111
  - Google ADK model/tool callback wrappers
112
- - LlamaIndex FunctionTool, query, retrieval, and output wrappers
112
+ - LlamaIndex FunctionTool, query, retrieval, callback, and optional handoff wrappers
113
113
  - Manager-to-specialist delegation token handling
114
114
  - Output DLP and sanitization workflows
115
115
  - Optional Redis-backed distributed token storage
@@ -478,17 +478,17 @@ export AGENTICDOME_REDIS_KEY_PREFIX="AgenticDome:production:handoff"
478
478
 
479
479
  | Framework | Can AgenticDome be applied globally by config only? | Global code location | Required code action | Tool-level code action |
480
480
  | :--- | :--- | :--- | :--- | :--- |
481
- | CrewAI | No. Env config is global, but hooks activate only after import. | Application bootstrap before crews are created, for example `main.py`, `worker.py`, or `celery_app.py`. | `import agenticdome_sdk.crewai` once. | Usually none; global hooks protect CrewAI tool calls. Ensure tool inputs include session/agent metadata where your CrewAI version supports it. |
482
- | PydanticAI | No. Env config initializes defaults, but each agent/tool must be attached or decorated. | Module where each `Agent(...)` is constructed. | Create `CyberSecFirewall(...)` and call `firewall.attach_to_agent(agent)`. | Decorate sensitive tools with `@firewall.secure_tool`. |
483
- | LangGraph | No. Env config initializes defaults, but graph interception requires graph nodes, wrappers, or middleware. | Module where `StateGraph` or LangChain `create_agent()` is assembled. | Add `input_node()`, `transition_node()`, `output_node()` to the graph, or use `as_langchain_middleware()`. | Wrap existing tool nodes with `wrap_tool_node()` when you cannot edit graph topology. |
484
- | Microsoft Agent Framework | No. Env config initializes defaults, but local tools and run boundaries must be wrapped. | Module where agents, workflows, and local function tools are declared. | Use `run_agent_securely()` around whole-agent calls where possible. | Use `@firewall.secure_tool`, `wrap_tool_handler()`, `secure_delegated_tool()`, or `wrap_delegated_tool_handler()`. |
485
- | Microsoft AI Foundry | No. Env config initializes threat and Mesh clients, but local run/tool boundaries must be wrapped. | Module that handles Foundry prompt runs, function-call execution, or `FoundryChatClient` local tools. | Use `run_secure()` around local Foundry run calls. | Use `wrap_tool_executor()` or `@firewall.secure_tool(...)` around local function tools before submitting tool output back to Foundry. |
486
- | Agno | No. Env config initializes defaults, but hooks must be attached to each Agent, Team, or AgentOS component. | Module where `Agent(...)`, Team, or AgentOS components are declared. | Use `attach_firewall(agent_or_team)` or `firewall.attach_firewall(agent_or_team)` to add `pre_hooks`, `post_hooks`, and `tool_hooks`. | Use `@firewall.secure_tool(...)` for high-risk local tools or custom tool functions. |
487
- | OpenAI Agents SDK | No. Env config initializes defaults, but runner and function-tool boundaries must be wrapped. | Module where `Agent(...)`, `Runner.run(...)`, `@function_tool`, or handoff tools are declared. | Use `run_agent_securely()` around `Runner.run(...)`. | Use `wrap_tool_handler()`, `wrap_delegated_tool_handler()`, or `@firewall.secure_tool(...)` before applying `@function_tool`. |
488
- | MCP host / gateway | No. Env config initializes defaults, but MCP interception must be placed in the host forwarding path. | The JSON-RPC gateway/proxy function that receives MCP requests before forwarding to third-party MCP servers. | Use `preflight_request()` before forwarding `tools/call`, or `forward_with_firewall()` around the forwarder. | Tool authorization is automatic for `tools/call`; private `_AgenticDome_*` metadata is stripped before forwarding. |
489
- | AWS Bedrock | No. Env config initializes defaults, but Bedrock calls and local tools must be wrapped in application code. | Module that calls `bedrock-runtime.converse(...)`, `invoke_model(...)`, Bedrock Agent action-group handlers, or knowledge-base retrieval handlers. | Use `converse_securely()` or `invoke_model_securely()` around model calls. | Use `wrap_tool_handler()` or `@firewall.secure_tool(...)` around local action-group and tool-use handlers. |
490
- | Google ADK | No. Env config initializes defaults, but ADK callbacks must be registered on each agent. | Module where `LlmAgent(...)` or agent config is declared. | Register `before_model`, `after_model`, `before_tool`, and `after_tool` callbacks using `install_on_agent(...)` or pass the callback methods at construction. | Use `wrap_tool_handler()` or `@firewall.secure_tool(...)` for local functions that need explicit protection outside ADK callbacks. |
491
- | LlamaIndex | No. Env config initializes defaults, but tools/query/retrieval boundaries must be wrapped in code. | Module where `FunctionTool`, `QueryEngineTool`, retrievers, query engines, or agents are assembled. | Use `run_query_securely()` around query flows and `sanitize_retrieval_result()` after retrieval. | Use `wrap_tool_function()`, `to_function_tool()`, or `@firewall.secure_tool(...)` before giving tools to an agent. |
481
+ | CrewAI | No. Env config is global, but hooks activate only after import or scoped attachment. | Application bootstrap before crews are created, or the module where Crew/CrewAI-compatible objects are assembled. | `import agenticdome_sdk.crewai` once for global hooks, or use `AgenticDomeCrewAIFirewall().attach(...)` for scoped hook lists. | Global hooks protect CrewAI tool calls; use `AgenticDomeCrewAIFirewall.secure_tool(...)` where you need explicit local wrapper enforcement, schema validation, or sanitized-argument execution. |
482
+ | PydanticAI | No. Env config initializes defaults, but each agent/tool must be attached or decorated. | Module where each `Agent(...)`, `Hooks`, and local function tool is constructed. | Create `CyberSecFirewall(...)` and call `create_hooks()`, `install_native_hooks(agent)`, or `attach_to_agent(agent)` depending on your PydanticAI version. | Decorate sensitive tools with `@firewall.secure_tool(...)` and optional `tool_schema` validation. |
483
+ | LangGraph | No. Env config initializes defaults, but graph interception requires graph nodes, wrappers, or middleware. | Module where `StateGraph` or LangChain `create_agent()` is assembled. | Add `input_node()`, `transition_node()`, `graph_transition_node()`, `output_node()` to the graph, or use `as_langchain_middleware()`. | Wrap existing nodes with `wrap_agent_node()` / `wrap_tool_node()` and use `security_route()` for blocked conditional edges. |
484
+ | Microsoft Agent Framework | No. Env config initializes defaults, but local tools, middleware hooks, and run boundaries must be attached in code. | Module where agents, workflows, local function tools, or framework middleware are declared. | Use `create_middleware()`, `install_on_agent()`, or `run_agent_securely()` around whole-agent calls where possible. | Use `@firewall.secure_tool`, `wrap_tool_handler`, `secure_delegated_tool`, `wrap_delegated_tool_handler`, and sanitized-argument enforcement for local tools. |
485
+ | Microsoft AI Foundry | No. Env config initializes threat and Mesh clients, but local run/tool/middleware boundaries must be attached in code. | Module that handles Foundry prompt runs, function-call execution, `FoundryChatClient` local tools, or Foundry client construction. | Use `create_middleware()`, `install_on_client()`, or `run_secure()` around local Foundry run calls. | Use `wrap_tool_executor()`, `@firewall.secure_tool(...)`, `before_tool_call()`, `authorize_manager_handoff()`, and `verify_delegated_execution()` around local and delegated tools. |
486
+ | Agno | No. Env config initializes defaults, but hooks or middleware-style helpers must be attached to each Agent, Team, Workflow, or AgentOS component. | Module where `Agent(...)`, Team, Workflow, or AgentOS components are declared. | Use `attach_firewall(agent_or_team)`, `create_hook_bundle()`, `create_middleware()`, or `create_plugin()` to add `pre_hooks`, `post_hooks`, and `tool_hooks`. | Use `@firewall.secure_tool(...)` for high-risk local tools; sanitized args, schema validation, delegation verification, and streaming sanitization are available. |
487
+ | OpenAI Agents SDK | No. Env config initializes defaults, but runner, guardrail, stream, function-tool, and handoff boundaries must be wrapped or registered. | Module where `Agent(...)`, `Runner.run(...)`, `Runner.run_streamed(...)`, `@function_tool`, guardrails, or handoff tools are declared. | Use `run_agent_securely()`, `run_agent_stream_securely()`, `create_input_guardrail()`, or `create_output_guardrail()` around agent runs and SDK guardrail slots. | Use `wrap_tool_handler()`, `wrap_delegated_tool_handler()`, `@firewall.secure_tool(...)`, `authorize_manager_handoff()`, and `verify_specialist_execution()` before applying `@function_tool` or executing specialist tools. |
488
+ | MCP host / gateway | No. Env config initializes defaults, but MCP interception must be placed in the host forwarding path. | The JSON-RPC gateway/proxy function that receives MCP requests before forwarding to third-party MCP servers. | Use `preflight_request()` or `forward_with_firewall()` around the forwarder for tools, resources, prompts, sampling, and list methods. | Use `authorize_manager_handoff()` and `verify_decision_token_if_present()` for delegated MCP execution; private `_AgenticDome_*` metadata is stripped before forwarding. |
489
+ | AWS Bedrock | No. Env config initializes defaults, but Bedrock Runtime, Bedrock Agents, action groups, retrieval, and local tools must be wrapped in application code. | Module that calls `bedrock-runtime.converse(...)`, `converse_stream(...)`, `invoke_model(...)`, `invoke_model_with_response_stream(...)`, `bedrock-agent-runtime.invoke_agent(...)`, action-group Lambda handlers, or knowledge-base retrieval handlers. | Use `converse_securely()`, `converse_stream_securely()`, `invoke_model_securely()`, `invoke_model_with_response_stream_securely()`, or `invoke_agent_securely()` around model/agent calls. | Use `wrap_tool_handler()`, `@firewall.secure_tool(...)`, `wrap_action_group_lambda()`, `authorize_manager_handoff()`, and `verify_delegated_execution()` around local and delegated tool execution. |
490
+ | Google ADK | No. Env config initializes defaults, but ADK callbacks or plugin-style hooks must be registered on each agent. | Module where `LlmAgent(...)`, ADK plugins, or agent config are declared. | Use `build_callback_kwargs()`, `create_plugin()`, or `install_on_agent(...)` to register before/after agent, model, and tool callbacks. | Use `wrap_tool_handler()` or `@firewall.secure_tool(...)` for local functions; sanitized arguments, schema validation, delegation tokens, and streaming output helpers are available for sensitive tools. |
491
+ | LlamaIndex | No. Env config initializes defaults, but tools/query/retrieval/callback boundaries must be wrapped in code. | Module where `FunctionTool`, `QueryEngineTool`, retrievers, query engines, node postprocessors, callbacks, or agents are assembled. | Use `run_query_securely()`, `wrap_query_engine()`, `wrap_retriever()`, `create_node_postprocessor()`, and `create_callback_handler()` at assembly boundaries. | Use `wrap_tool_function()`, `to_function_tool()`, `@firewall.secure_tool(...)`, `authorize_manager_handoff()`, and `verify_delegated_execution()` for tools and multi-agent handoffs. |
492
492
  | Custom Python | No. Env config initializes the client only. | Your API handler, agent gateway, router, or tool executor. | Call `guardrail_validate()` before prompts/tools and `mesh_validate()` before returning output. | Call `a2a_authorize_tool()` and `a2a_verify_decision_token_rpc()` for manager/specialist delegation. |
493
493
 
494
494
  ### CrewAI: Global Hook Activation
@@ -635,11 +635,138 @@ secure_refund = firewall.wrap_delegated_tool_handler(
635
635
  | `AGENTICDOME_REDIS_KEY_PREFIX` | string | framework-specific | Redis key prefix. |
636
636
  | `AGENTICDOME_LANGGRAPH_AGENT_ID` | string | `langgraph_orchestrator` | Default LangGraph orchestrator node identity. |
637
637
  | `AGENTICDOME_LANGGRAPH_FINAL_ID` | string | `langgraph_final_node` | Default LangGraph final-output node identity. |
638
+ | `AGENTICDOME_LANGGRAPH_REQUIRE_SERVER_TOKENS` | boolean | `false` | Requires handoff authorization responses to include server-issued decision tokens. |
639
+ | `AGENTICDOME_LANGGRAPH_STRICT_DELEGATED_EXECUTION` | boolean | `true` | Blocks delegated executions that carry delegation metadata without a valid token. |
640
+ | `AGENTICDOME_LANGGRAPH_MAX_INPUT_CHARS` | integer | `50000` | Maximum LangGraph input or transition text reviewed before local blocking. |
641
+ | `AGENTICDOME_LANGGRAPH_MAX_OUTPUT_CHARS` | integer | `100000` | Maximum LangGraph output, stream buffer, or retrieval document text reviewed before local blocking. |
642
+ | `AGENTICDOME_LANGGRAPH_MAX_TOOL_ARG_CHARS` | integer | `20000` | Maximum serialized LangGraph tool arguments before blocking. |
643
+ | `AGENTICDOME_LANGGRAPH_STREAMING_BUFFER_CHARS` | integer | `4000` | Sliding buffer size used by streaming event sanitization. |
644
+ | `AGENTICDOME_LANGGRAPH_RATE_LIMIT_PER_MINUTE` | integer | `0` | Per-agent/session/purpose local LangGraph rate limit; `0` disables it. |
645
+ | `AGENTICDOME_LANGGRAPH_RETRY_ATTEMPTS` | integer | `2` | Retry attempts for LangGraph policy client calls. |
646
+ | `AGENTICDOME_LANGGRAPH_RETRY_BACKOFF_S` | float | `0.25` | Initial exponential backoff delay for LangGraph policy client retries. |
647
+ | `AGENTICDOME_LANGGRAPH_CIRCUIT_BREAKER_FAILURES` | integer | `5` | Consecutive policy call failures before opening the LangGraph circuit breaker. |
648
+ | `AGENTICDOME_LANGGRAPH_CIRCUIT_BREAKER_RESET_S` | integer | `60` | Seconds before retrying after the LangGraph circuit breaker opens. |
649
+ | `AGENTICDOME_LANGGRAPH_AUDIT_LOGGING` | boolean | `true` | Emits structured audit logs from the LangGraph adapter. |
650
+ | `AGENTICDOME_LANGGRAPH_OTEL_ENABLED` | boolean | `true` | Emits OpenTelemetry-compatible debug events from the LangGraph adapter. |
651
+ | `AGENTICDOME_LANGGRAPH_EMERGENCY_BLOCK_TOOLS` | CSV string | empty | Local emergency deny list for LangGraph tool names. |
652
+ | `AGENTICDOME_LANGGRAPH_EMERGENCY_BLOCK_AGENTS` | CSV string | empty | Local emergency deny list for LangGraph agent IDs. |
653
+ | `AGENTICDOME_CLOUD_PROVIDER` | string | empty | Optional cloud/provider label added to policy context. |
654
+ | `AGENTICDOME_CLOUD_PROJECT_ID` | string | empty | Optional project/account label added to policy context. |
655
+ | `AGENTICDOME_IDENTITY_PROVIDER` | string | empty | Optional identity-provider label added to policy context. |
638
656
  | `AGENTICDOME_ENABLE_COPILOT_THREAT_API` | boolean | `false` | Enables optional Microsoft Copilot / AI Foundry threat helper calls where available. |
657
+ | `AGENTICDOME_ENFORCE_COPILOT_THREAT_API` | boolean | `false` | Makes optional Copilot / AI Foundry threat helper failures or blocks enforce locally. |
658
+ | `AGENTICDOME_PRODUCTION_MODE` | boolean | `false` | Enables production hardening such as stable session ID enforcement. |
659
+ | `AGENTICDOME_REQUIRE_STABLE_SESSION_ID_IN_PROD` | boolean | `true` | Requires a stable session/run/trace ID when production mode is enabled. |
660
+ | `AGENTICDOME_PYDANTICAI_MAX_INPUT_CHARS` | integer | `50000` | Maximum PydanticAI prompt/input text reviewed before local truncation. |
661
+ | `AGENTICDOME_PYDANTICAI_MAX_OUTPUT_CHARS` | integer | `100000` | Maximum PydanticAI output text reviewed before local truncation. |
662
+ | `AGENTICDOME_PYDANTICAI_MAX_TOOL_ARG_CHARS` | integer | `20000` | Maximum serialized PydanticAI tool arguments before blocking. |
663
+ | `AGENTICDOME_PYDANTICAI_RATE_LIMIT_PER_MINUTE` | integer | `0` | Per-agent/session/purpose local rate limit; `0` disables it. |
664
+ | `AGENTICDOME_PYDANTICAI_RETRY_ATTEMPTS` | integer | `2` | Retry attempts for PydanticAI policy client calls. |
665
+ | `AGENTICDOME_PYDANTICAI_RETRY_BACKOFF_S` | float | `0.25` | Initial exponential backoff delay for PydanticAI policy client retries. |
666
+ | `AGENTICDOME_PYDANTICAI_CIRCUIT_BREAKER_FAILURES` | integer | `5` | Consecutive policy call failures before opening the local PydanticAI circuit breaker. |
667
+ | `AGENTICDOME_PYDANTICAI_CIRCUIT_BREAKER_RESET_S` | integer | `60` | Seconds before retrying after the PydanticAI circuit breaker opens. |
668
+ | `AGENTICDOME_PYDANTICAI_AUDIT_LOGGING` | boolean | `true` | Emits structured audit logs from the PydanticAI adapter. |
669
+ | `AGENTICDOME_PYDANTICAI_OTEL_ENABLED` | boolean | `true` | Emits OpenTelemetry span events when OpenTelemetry is installed and a span is active. |
670
+ | `AGENTICDOME_PYDANTICAI_EMERGENCY_BLOCK_TOOLS` | CSV string | empty | Local emergency deny list for PydanticAI tool names. |
671
+ | `AGENTICDOME_PYDANTICAI_EMERGENCY_BLOCK_AGENTS` | CSV string | empty | Local emergency deny list for PydanticAI agent IDs. |
672
+ | `AGENTICDOME_MSAF_MAX_INPUT_CHARS` | integer | `50000` | Maximum Microsoft Agent Framework input text reviewed before local truncation. |
673
+ | `AGENTICDOME_MSAF_MAX_OUTPUT_CHARS` | integer | `100000` | Maximum Microsoft Agent Framework output text reviewed before local truncation. |
674
+ | `AGENTICDOME_MSAF_MAX_TOOL_ARG_CHARS` | integer | `20000` | Maximum serialized local tool arguments before blocking. |
675
+ | `AGENTICDOME_MSAF_RATE_LIMIT_PER_MINUTE` | integer | `0` | Per-agent/session/purpose local rate limit; `0` disables it. |
676
+ | `AGENTICDOME_MSAF_RETRY_ATTEMPTS` | integer | `2` | Retry attempts for AgenticDome policy client calls. |
677
+ | `AGENTICDOME_MSAF_CIRCUIT_BREAKER_FAILURES` | integer | `5` | Consecutive policy call failures before opening the local circuit breaker. |
678
+ | `AGENTICDOME_MSAF_CIRCUIT_BREAKER_RESET_S` | integer | `60` | Seconds before retrying after the circuit breaker opens. |
679
+ | `AGENTICDOME_MSAF_AUDIT_LOGGING` | boolean | `true` | Emits structured audit logs from the Microsoft Agent Framework adapter. |
680
+ | `AGENTICDOME_MSAF_OTEL_ENABLED` | boolean | `true` | Emits OpenTelemetry span events when OpenTelemetry is installed and a span is active. |
681
+ | `AGENTICDOME_MSAF_EMERGENCY_BLOCK_TOOLS` | CSV string | empty | Local emergency deny list for tool names. |
682
+ | `AGENTICDOME_MSAF_EMERGENCY_BLOCK_AGENTS` | CSV string | empty | Local emergency deny list for agent IDs. |
683
+ | `AGENTICDOME_TOKEN_HMAC_SECRET` | string | empty | Optional HMAC secret for tagging stored decision-token records. |
639
684
  | `AGENTICDOME_COPILOT_API_VERSION` | string | `2025-09-01` | API version used by optional Copilot / AI Foundry threat helper calls. |
640
685
  | `AGENTICDOME_BEARER_TOKEN` | string | optional | Bearer token used by Microsoft AI Foundry threat-contract endpoints. |
686
+ | `AGENTICDOME_FOUNDRY_REQUIRE_OUTPUT_SANITIZATION_IN_PROD` | boolean | `true` | Requires API-key-backed Mesh output sanitization when Foundry production mode is enabled. |
687
+ | `AGENTICDOME_FOUNDRY_MAX_INPUT_CHARS` | integer | `50000` | Maximum Microsoft AI Foundry prompt/input text reviewed before local truncation. |
688
+ | `AGENTICDOME_FOUNDRY_MAX_OUTPUT_CHARS` | integer | `100000` | Maximum Foundry output text reviewed before local truncation. |
689
+ | `AGENTICDOME_FOUNDRY_MAX_TOOL_ARG_CHARS` | integer | `20000` | Maximum serialized Foundry local tool arguments before blocking. |
690
+ | `AGENTICDOME_FOUNDRY_RATE_LIMIT_PER_MINUTE` | integer | `0` | Per-agent/session/purpose local rate limit; `0` disables it. |
691
+ | `AGENTICDOME_FOUNDRY_RETRY_ATTEMPTS` | integer | `2` | Retry attempts for Foundry policy client calls. |
692
+ | `AGENTICDOME_FOUNDRY_RETRY_BACKOFF_S` | float | `0.25` | Initial exponential backoff delay for Foundry policy client retries. |
693
+ | `AGENTICDOME_FOUNDRY_CIRCUIT_BREAKER_FAILURES` | integer | `5` | Consecutive policy call failures before opening the local Foundry circuit breaker. |
694
+ | `AGENTICDOME_FOUNDRY_CIRCUIT_BREAKER_RESET_S` | integer | `60` | Seconds before retrying after the Foundry circuit breaker opens. |
695
+ | `AGENTICDOME_FOUNDRY_AUDIT_LOGGING` | boolean | `true` | Emits structured audit logs from the Microsoft AI Foundry adapter. |
696
+ | `AGENTICDOME_FOUNDRY_OTEL_ENABLED` | boolean | `true` | Emits OpenTelemetry span events when OpenTelemetry is installed and a span is active. |
697
+ | `AGENTICDOME_FOUNDRY_EMERGENCY_BLOCK_TOOLS` | CSV string | empty | Local emergency deny list for Foundry tool names. |
698
+ | `AGENTICDOME_FOUNDRY_EMERGENCY_BLOCK_AGENTS` | CSV string | empty | Local emergency deny list for Foundry agent IDs. |
699
+ | `AGENTICDOME_CREWAI_MAX_INPUT_CHARS` | integer | `50000` | Maximum CrewAI prompt or authorization text reviewed before local truncation. |
700
+ | `AGENTICDOME_CREWAI_MAX_OUTPUT_CHARS` | integer | `100000` | Maximum CrewAI output text reviewed before local truncation. |
701
+ | `AGENTICDOME_CREWAI_MAX_TOOL_ARG_CHARS` | integer | `20000` | Maximum serialized CrewAI tool arguments before blocking. |
702
+ | `AGENTICDOME_CREWAI_STREAMING_BUFFER_CHARS` | integer | `4000` | Sliding context window used by CrewAI streaming sanitization helpers. |
703
+ | `AGENTICDOME_CREWAI_RATE_LIMIT_PER_MINUTE` | integer | `0` | Per-agent/session/purpose local CrewAI rate limit; `0` disables it. |
704
+ | `AGENTICDOME_CREWAI_RETRY_ATTEMPTS` | integer | `2` | Retry attempts for CrewAI policy client calls. |
705
+ | `AGENTICDOME_CREWAI_RETRY_BACKOFF_S` | float | `0.25` | Initial exponential backoff delay for CrewAI policy client retries. |
706
+ | `AGENTICDOME_CREWAI_CIRCUIT_BREAKER_FAILURES` | integer | `5` | Consecutive policy call failures before opening the local CrewAI circuit breaker. |
707
+ | `AGENTICDOME_CREWAI_CIRCUIT_BREAKER_RESET_S` | integer | `60` | Seconds before retrying after the CrewAI circuit breaker opens. |
708
+ | `AGENTICDOME_CREWAI_AUDIT_LOGGING` | boolean | `true` | Emits structured audit logs from the CrewAI adapter. |
709
+ | `AGENTICDOME_CREWAI_OTEL_ENABLED` | boolean | `true` | Emits OpenTelemetry span events when OpenTelemetry is installed and a span is active. |
710
+ | `AGENTICDOME_CREWAI_EMERGENCY_BLOCK_TOOLS` | CSV string | empty | Local emergency deny list for CrewAI tool names. |
711
+ | `AGENTICDOME_CREWAI_EMERGENCY_BLOCK_AGENTS` | CSV string | empty | Local emergency deny list for CrewAI agent IDs. |
712
+ | `AGENTICDOME_AGNO_MAX_INPUT_CHARS` | integer | `50000` | Maximum Agno prompt or authorization text reviewed before local truncation. |
713
+ | `AGENTICDOME_AGNO_MAX_OUTPUT_CHARS` | integer | `100000` | Maximum Agno output or retrieved-context text reviewed before local truncation. |
714
+ | `AGENTICDOME_AGNO_MAX_TOOL_ARG_CHARS` | integer | `20000` | Maximum serialized Agno tool arguments before blocking. |
715
+ | `AGENTICDOME_AGNO_STREAMING_BUFFER_CHARS` | integer | `4000` | Sliding context window used by Agno streaming sanitization helpers. |
716
+ | `AGENTICDOME_AGNO_RATE_LIMIT_PER_MINUTE` | integer | `0` | Per-agent/session/purpose local Agno rate limit; `0` disables it. |
717
+ | `AGENTICDOME_AGNO_RETRY_ATTEMPTS` | integer | `2` | Retry attempts for Agno policy client calls. |
718
+ | `AGENTICDOME_AGNO_RETRY_BACKOFF_S` | float | `0.25` | Initial exponential backoff delay for Agno policy client retries. |
719
+ | `AGENTICDOME_AGNO_CIRCUIT_BREAKER_FAILURES` | integer | `5` | Consecutive policy call failures before opening the local Agno circuit breaker. |
720
+ | `AGENTICDOME_AGNO_CIRCUIT_BREAKER_RESET_S` | integer | `60` | Seconds before retrying after the Agno circuit breaker opens. |
721
+ | `AGENTICDOME_AGNO_AUDIT_LOGGING` | boolean | `true` | Emits structured audit logs from the Agno adapter. |
722
+ | `AGENTICDOME_AGNO_OTEL_ENABLED` | boolean | `true` | Emits OpenTelemetry span events when OpenTelemetry is installed and a span is active. |
723
+ | `AGENTICDOME_AGNO_EMERGENCY_BLOCK_TOOLS` | CSV string | empty | Local emergency deny list for Agno tool names. |
724
+ | `AGENTICDOME_AGNO_EMERGENCY_BLOCK_AGENTS` | CSV string | empty | Local emergency deny list for Agno agent IDs. |
725
+ | `AGENTICDOME_OPENAI_AGENTS_MAX_INPUT_CHARS` | integer | `50000` | Maximum OpenAI Agents prompt or authorization text reviewed before local truncation. |
726
+ | `AGENTICDOME_OPENAI_AGENTS_MAX_OUTPUT_CHARS` | integer | `100000` | Maximum OpenAI Agents output text reviewed before local truncation. |
727
+ | `AGENTICDOME_OPENAI_AGENTS_MAX_TOOL_ARG_CHARS` | integer | `20000` | Maximum serialized OpenAI Agents tool arguments before blocking. |
728
+ | `AGENTICDOME_OPENAI_AGENTS_STREAMING_BUFFER_CHARS` | integer | `4000` | Sliding context window used by OpenAI Agents streaming sanitization helpers. |
729
+ | `AGENTICDOME_OPENAI_AGENTS_RATE_LIMIT_PER_MINUTE` | integer | `0` | Per-agent/session/purpose local OpenAI Agents rate limit; `0` disables it. |
730
+ | `AGENTICDOME_OPENAI_AGENTS_RETRY_ATTEMPTS` | integer | `2` | Retry attempts for OpenAI Agents policy client calls. |
731
+ | `AGENTICDOME_OPENAI_AGENTS_RETRY_BACKOFF_S` | float | `0.25` | Initial exponential backoff delay for OpenAI Agents policy client retries. |
732
+ | `AGENTICDOME_OPENAI_AGENTS_CIRCUIT_BREAKER_FAILURES` | integer | `5` | Consecutive policy call failures before opening the local OpenAI Agents circuit breaker. |
733
+ | `AGENTICDOME_OPENAI_AGENTS_CIRCUIT_BREAKER_RESET_S` | integer | `60` | Seconds before retrying after the OpenAI Agents circuit breaker opens. |
734
+ | `AGENTICDOME_OPENAI_AGENTS_AUDIT_LOGGING` | boolean | `true` | Emits structured audit logs from the OpenAI Agents adapter. |
735
+ | `AGENTICDOME_OPENAI_AGENTS_OTEL_ENABLED` | boolean | `true` | Emits OpenTelemetry span events when OpenTelemetry is installed and a span is active. |
736
+ | `AGENTICDOME_OPENAI_AGENTS_EMERGENCY_BLOCK_TOOLS` | CSV string | empty | Local emergency deny list for OpenAI Agents tool names. |
737
+ | `AGENTICDOME_OPENAI_AGENTS_EMERGENCY_BLOCK_AGENTS` | CSV string | empty | Local emergency deny list for OpenAI Agents agent IDs. |
641
738
  | `AGENTICDOME_BEDROCK_AGENT_ID` | string | `aws_bedrock_agent` | Default agent identity for AWS Bedrock runtime calls and local action handlers. |
739
+ | `AGENTICDOME_AWS_ACCOUNT_ID` | string | empty | AWS account ID added to Bedrock policy context when available. |
740
+ | `AGENTICDOME_AWS_REGION` | string | `AWS_REGION` / `AWS_DEFAULT_REGION` | AWS region added to Bedrock policy context when available. |
741
+ | `AGENTICDOME_AWS_ROLE_ARN` | string | empty | AWS role ARN added to Bedrock policy context. |
742
+ | `AGENTICDOME_AWS_PRINCIPAL_ARN` | string | empty | AWS principal/caller ARN added to Bedrock policy context. |
743
+ | `AGENTICDOME_BEDROCK_MAX_INPUT_CHARS` | integer | `50000` | Maximum Bedrock prompt or authorization text reviewed before local truncation. |
744
+ | `AGENTICDOME_BEDROCK_MAX_OUTPUT_CHARS` | integer | `100000` | Maximum Bedrock output text reviewed before local truncation. |
745
+ | `AGENTICDOME_BEDROCK_MAX_TOOL_ARG_CHARS` | integer | `20000` | Maximum serialized Bedrock local tool/action-group arguments before blocking. |
746
+ | `AGENTICDOME_BEDROCK_STREAMING_BUFFER_CHARS` | integer | `4000` | Sliding review buffer size for Bedrock streaming sanitization helpers. |
747
+ | `AGENTICDOME_BEDROCK_RATE_LIMIT_PER_MINUTE` | integer | `0` | Per-agent/session/purpose local Bedrock rate limit; `0` disables it. |
748
+ | `AGENTICDOME_BEDROCK_RETRY_ATTEMPTS` | integer | `2` | Retry attempts for Bedrock policy client calls. |
749
+ | `AGENTICDOME_BEDROCK_RETRY_BACKOFF_S` | float | `0.25` | Initial exponential backoff delay for Bedrock policy client retries. |
750
+ | `AGENTICDOME_BEDROCK_CIRCUIT_BREAKER_FAILURES` | integer | `5` | Consecutive policy call failures before opening the local Bedrock circuit breaker. |
751
+ | `AGENTICDOME_BEDROCK_CIRCUIT_BREAKER_RESET_S` | integer | `60` | Seconds before retrying after the Bedrock circuit breaker opens. |
752
+ | `AGENTICDOME_BEDROCK_AUDIT_LOGGING` | boolean | `true` | Emits structured audit logs from the AWS Bedrock adapter. |
753
+ | `AGENTICDOME_BEDROCK_OTEL_ENABLED` | boolean | `true` | Emits OpenTelemetry span events when OpenTelemetry is installed and a span is active. |
754
+ | `AGENTICDOME_BEDROCK_EMERGENCY_BLOCK_TOOLS` | CSV string | empty | Local emergency deny list for Bedrock tool/action names. |
755
+ | `AGENTICDOME_BEDROCK_EMERGENCY_BLOCK_AGENTS` | CSV string | empty | Local emergency deny list for Bedrock agent IDs. |
642
756
  | `AGENTICDOME_GOOGLE_ADK_AGENT_ID` | string | `google_adk_agent` | Default agent identity for Google ADK callback enforcement. |
757
+ | `AGENTICDOME_GOOGLE_ADK_MAX_INPUT_CHARS` | integer | `50000` | Maximum Google ADK prompt or authorization text reviewed before local truncation. |
758
+ | `AGENTICDOME_GOOGLE_ADK_MAX_OUTPUT_CHARS` | integer | `100000` | Maximum Google ADK model or tool output text reviewed before local truncation. |
759
+ | `AGENTICDOME_GOOGLE_ADK_MAX_TOOL_ARG_CHARS` | integer | `20000` | Maximum serialized Google ADK tool arguments before blocking. |
760
+ | `AGENTICDOME_GOOGLE_ADK_STREAMING_BUFFER_CHARS` | integer | `4000` | Sliding context window used by Google ADK streaming sanitization helpers. |
761
+ | `AGENTICDOME_GOOGLE_ADK_RATE_LIMIT_PER_MINUTE` | integer | `0` | Per-agent/session/purpose local Google ADK rate limit; `0` disables it. |
762
+ | `AGENTICDOME_GOOGLE_ADK_RETRY_ATTEMPTS` | integer | `2` | Retry attempts for Google ADK policy client calls. |
763
+ | `AGENTICDOME_GOOGLE_ADK_RETRY_BACKOFF_S` | float | `0.25` | Initial exponential backoff delay for Google ADK policy client retries. |
764
+ | `AGENTICDOME_GOOGLE_ADK_CIRCUIT_BREAKER_FAILURES` | integer | `5` | Consecutive policy call failures before opening the local Google ADK circuit breaker. |
765
+ | `AGENTICDOME_GOOGLE_ADK_CIRCUIT_BREAKER_RESET_S` | integer | `60` | Seconds before retrying after the Google ADK circuit breaker opens. |
766
+ | `AGENTICDOME_GOOGLE_ADK_AUDIT_LOGGING` | boolean | `true` | Emits structured audit logs from the Google ADK adapter. |
767
+ | `AGENTICDOME_GOOGLE_ADK_OTEL_ENABLED` | boolean | `true` | Emits OpenTelemetry span events when OpenTelemetry is installed and a span is active. |
768
+ | `AGENTICDOME_GOOGLE_ADK_EMERGENCY_BLOCK_TOOLS` | CSV string | empty | Local emergency deny list for Google ADK tool names. |
769
+ | `AGENTICDOME_GOOGLE_ADK_EMERGENCY_BLOCK_AGENTS` | CSV string | empty | Local emergency deny list for Google ADK agent IDs. |
643
770
  | `AGENTICDOME_LLAMAINDEX_AGENT_ID` | string | `llamaindex_agent` | Default agent identity for LlamaIndex tools, query engines, and retrievers. |
644
771
  | `AGENTICDOME_SANITIZE_QUERY_OUTPUT` | boolean | `true` | Enables Mesh output review for LlamaIndex query responses. |
645
772
  | `AGENTICDOME_BEDROCK_MODEL_ID` | string | empty | Optional default Bedrock model ID for policy context. |
@@ -649,6 +776,24 @@ secure_refund = firewall.wrap_delegated_tool_handler(
649
776
  | `AGENTICDOME_SANITIZE_TOOL_OUTPUT` | boolean | `true` | Enables Mesh output review for MCP tool results before returning to the client. |
650
777
  | `AGENTICDOME_VERIFY_DECISION_TOKENS` | boolean | `true` | Verifies delegated decision tokens when MCP tool calls carry handoff metadata. |
651
778
  | `AGENTICDOME_SCREEN_UPSTREAM_PROMPT` | boolean | `true` | Screens upstream user prompt text in MCP host context before tool forwarding. |
779
+ | `AGENTICDOME_MCP_PROTECT_TOOLS_LIST` | boolean | `true` | Authorizes and filters MCP `tools/list` discovery responses. |
780
+ | `AGENTICDOME_MCP_PROTECT_RESOURCES_LIST` | boolean | `true` | Authorizes MCP `resources/list` discovery requests. |
781
+ | `AGENTICDOME_MCP_PROTECT_RESOURCES_READ` | boolean | `true` | Authorizes MCP `resources/read` requests before forwarding. |
782
+ | `AGENTICDOME_MCP_PROTECT_PROMPTS_LIST` | boolean | `true` | Authorizes MCP `prompts/list` discovery requests. |
783
+ | `AGENTICDOME_MCP_PROTECT_PROMPTS_GET` | boolean | `true` | Authorizes MCP `prompts/get` requests before forwarding. |
784
+ | `AGENTICDOME_MCP_PROTECT_SAMPLING_CREATE_MESSAGE` | boolean | `true` | Authorizes MCP `sampling/createMessage` requests. |
785
+ | `AGENTICDOME_SANITIZE_RESOURCE_OUTPUT` | boolean | `true` | Enables Mesh output review for MCP resource read results. |
786
+ | `AGENTICDOME_SANITIZE_PROMPT_OUTPUT` | boolean | `true` | Enables Mesh output review for MCP prompt results. |
787
+ | `AGENTICDOME_SANITIZE_STREAMING_OUTPUT` | boolean | `true` | Enables chunk-level sanitization helpers for streaming MCP responses. |
788
+ | `AGENTICDOME_MCP_SERVER_ID` | string | empty | Default MCP server identity included in policy context. |
789
+ | `AGENTICDOME_MCP_SERVER_URL` | string | empty | Default MCP server URL included in policy context. |
790
+ | `AGENTICDOME_MCP_SERVER_TRUST_LEVEL` | string | empty | Default MCP server trust label included in policy context. |
791
+ | `AGENTICDOME_MCP_SERVER_VENDOR` | string | empty | Default MCP server vendor included in policy context. |
792
+ | `AGENTICDOME_MCP_MAX_OUTPUT_CHARS` | integer | `100000` | Maximum text sent for MCP output sanitization before local truncation. |
793
+ | `AGENTICDOME_MCP_MAX_TOOL_ARG_CHARS` | integer | `20000` | Maximum serialized MCP arguments allowed before blocking. |
794
+ | `AGENTICDOME_MCP_MAX_REQUEST_TEXT_CHARS` | integer | `20000` | Maximum upstream request text sent for prompt/method authorization before local truncation. |
795
+ | `AGENTICDOME_MCP_RATE_LIMIT_PER_MINUTE` | integer | `0` | Per-principal per-server per-method local rate limit; `0` disables it. |
796
+ | `AGENTICDOME_MCP_AUDIT_LOGGING` | boolean | `true` | Emits structured MCP gateway audit logs from the adapter. |
652
797
  | `AGENTICDOME_REPORT_INCIDENTS` | boolean | `true` | Reports blocked actions and middleware failures. |
653
798
  | `AGENTICDOME_BLOCKED_INCIDENT_SEVERITY` | string | `medium` | Default severity for incident reports. |
654
799
 
@@ -661,17 +806,17 @@ Use this table to choose the SDK module and the exact place where AgenticDome sh
661
806
  | Runtime | SDK module | Where to call AgenticDome | Primary API |
662
807
  | :--- | :--- | :--- | :--- |
663
808
  | Core Python / custom runtimes | `agenticdome_sdk.client` | Your own gateway, router, tool executor, or API handler. | `AgentGuardClient.guardrail_validate()`, `mesh_validate()`, `a2a_authorize_tool()`, `a2a_verify_decision_token_rpc()` |
664
- | CrewAI | `agenticdome_sdk.crewai` | Import once in the process bootstrap before crews run. Hooks are registered globally. | `import agenticdome_sdk.crewai` |
665
- | PydanticAI | `agenticdome_sdk.pydantic` | Instantiate the firewall near agent construction, attach lifecycle hooks, and decorate tools. | `CyberSecFirewall.attach_to_agent()`, `@firewall.secure_tool` |
666
- | LangGraph | `agenticdome_sdk.langgraph` | Add firewall nodes to `StateGraph`, wrap existing graph nodes, or use LangChain middleware. | `input_node()`, `transition_node()`, `output_node()`, `wrap_agent_node()`, `wrap_tool_node()`, `as_langchain_middleware()` |
667
- | Microsoft Agent Framework | `agenticdome_sdk.microsoft_agent_framework` | Wrap local function-tool handlers, delegated specialist handlers, and whole agent run boundaries. | `wrap_tool_handler()`, `secure_tool()`, `wrap_delegated_tool_handler()`, `secure_delegated_tool()`, `run_agent_securely()` |
668
- | Microsoft AI Foundry | `agenticdome_sdk.microsoft_ai_foundry` | Validate Foundry prompt contracts, analyze local function tool execution, and optionally sanitize output with Mesh. | `validate_prompt_contract()`, `analyze_tool_execution()`, `wrap_tool_executor()`, `secure_tool()`, `run_secure()` |
669
- | Agno | `agenticdome_sdk.agno` | Attach hooks to agents/teams and optionally decorate high-risk local tools. | `attach_firewall()`, `cybersec_pre_hook`, `cybersec_post_hook`, `cybersec_tool_hook`, `@firewall.secure_tool` |
670
- | OpenAI Agents SDK | `agenticdome_sdk.openai_agents` | Wrap `Runner.run(...)`, function tools, and delegated specialist tools. | `run_agent_securely()`, `wrap_tool_handler()`, `wrap_delegated_tool_handler()`, `secure_tool()`, `authorize_manager_handoff()` |
671
- | MCP host / gateway | `agenticdome_sdk.mcp_host` | Guard MCP JSON-RPC `tools/call` before third-party server forwarding and sanitize returned tool results. | `preflight_request()`, `forward_with_firewall()`, `verify_decision_token_if_present()`, `sanitize_mcp_result()` |
672
- | AWS Bedrock | `agenticdome_sdk.aws_bedrock` | Guard Bedrock Runtime prompt ingress, local tool/action execution, model output, and retrieval results. | `converse_securely()`, `invoke_model_securely()`, `wrap_tool_handler()`, `secure_tool()`, `sanitize_retrieval_result()` |
673
- | Google ADK | `agenticdome_sdk.google_adk` | Register model/tool callbacks for prompt screening, tool authorization, and output sanitization. | `install_on_agent()`, `before_model`, `after_model`, `before_tool`, `after_tool`, `wrap_tool_handler()` |
674
- | LlamaIndex | `agenticdome_sdk.llamaindex` | Wrap FunctionTool functions, query calls, retrieval results, and final output. | `wrap_tool_function()`, `to_function_tool()`, `run_query_securely()`, `sanitize_retrieval_result()` |
809
+ | CrewAI | `agenticdome_sdk.crewai` | Import once for global hook registration, or use the class facade for scoped attach/unregister, local wrappers, streaming sanitization, and delegated execution hardening. | `import agenticdome_sdk.crewai`, `AgenticDomeCrewAIFirewall`, `attach_firewall()`, `unregister_firewall()`, `sanitize_streaming_response()` |
810
+ | PydanticAI | `agenticdome_sdk.pydantic` | Instantiate the firewall near agent construction, attach native Hooks where supported, decorate tools, verify delegated execution, and sanitize output/streams. | `CyberSecFirewall.create_hooks()`, `install_native_hooks()`, `attach_to_agent()`, `@firewall.secure_tool(...)`, `sanitize_text()`, `sanitize_streaming_response()` |
811
+ | LangGraph | `agenticdome_sdk.langgraph` | Add firewall nodes to `StateGraph`, wrap existing graph nodes, or use LangChain middleware. | `input_node()`, `transition_node()`, `graph_transition_node()`, `output_node()`, `wrap_agent_node()`, `wrap_tool_node()`, `sanitize_retrieval_documents()`, `sanitize_streaming_events()`, `security_route()`, `as_langchain_middleware()` |
812
+ | Microsoft Agent Framework | `agenticdome_sdk.microsoft_agent_framework` | Attach middleware hooks, wrap local/delegated function-tool handlers, and protect whole agent run boundaries. | `create_middleware()`, `install_on_agent()`, `before_agent_run()`, `before_tool_call()`, `wrap_tool_handler()`, `secure_tool()`, `wrap_delegated_tool_handler()`, `secure_delegated_tool()`, `run_agent_securely()`, `sanitize_streaming_response()` |
813
+ | Microsoft AI Foundry | `agenticdome_sdk.microsoft_ai_foundry` | Validate Foundry prompt contracts, attach middleware-style hooks, analyze local/delegated function tool execution, and sanitize output with Mesh. | `create_middleware()`, `install_on_client()`, `validate_prompt_contract()`, `analyze_tool_execution()`, `before_tool_call()`, `wrap_tool_executor()`, `secure_tool()`, `run_secure()`, `sanitize_streaming_response()`, `authorize_manager_handoff()` |
814
+ | Agno | `agenticdome_sdk.agno` | Attach hooks or middleware-style helper objects to agents/teams/workflows, decorate high-risk local tools, verify delegated execution, and sanitize output/streams. | `attach_firewall()`, `create_hook_bundle()`, `create_middleware()`, `create_plugin()`, `cybersec_pre_hook`, `cybersec_post_hook`, `cybersec_tool_hook`, `@firewall.secure_tool`, `sanitize_streaming_response()` |
815
+ | OpenAI Agents SDK | `agenticdome_sdk.openai_agents` | Wrap `Runner.run(...)`, streamed runs, SDK guardrail slots, function tools, and delegated specialist tools. | `run_agent_securely()`, `run_agent_stream_securely()`, `create_input_guardrail()`, `create_output_guardrail()`, `wrap_tool_handler()`, `wrap_delegated_tool_handler()`, `secure_tool()`, `sanitize_streaming_response()`, `authorize_manager_handoff()`, `verify_specialist_execution()` |
816
+ | MCP host / gateway | `agenticdome_sdk.mcp_host` | Guard MCP JSON-RPC tool/resource/prompt/sampling/list methods before third-party server forwarding and sanitize returned results. | `preflight_request()`, `forward_with_firewall()`, `authorize_manager_handoff()`, `verify_decision_token_if_present()`, `filter_tools_list_result()`, `sanitize_mcp_result()`, `sanitize_streaming_response()` |
817
+ | AWS Bedrock | `agenticdome_sdk.aws_bedrock` | Guard Bedrock Runtime, Bedrock Agents, local tool/action execution, model output, streaming output, and retrieval results. | `converse_securely()`, `converse_stream_securely()`, `invoke_model_securely()`, `invoke_model_with_response_stream_securely()`, `invoke_agent_securely()`, `wrap_tool_handler()`, `secure_tool()`, `wrap_action_group_lambda()`, `sanitize_retrieval_result()`, `authorize_manager_handoff()`, `verify_delegated_execution()` |
818
+ | Google ADK | `agenticdome_sdk.google_adk` | Register ADK callbacks or plugin-style hooks for agent/model/tool lifecycle enforcement, local tool authorization, delegation tokens, and output sanitization. | `build_callback_kwargs()`, `create_plugin()`, `install_on_agent()`, `before_model`, `after_model`, `before_tool`, `after_tool`, `wrap_tool_handler()`, `secure_tool()`, `authorize_manager_handoff()`, `verify_delegated_execution()`, `sanitize_streaming_response()` |
819
+ | LlamaIndex | `agenticdome_sdk.llamaindex` | Wrap FunctionTool functions, query calls, retrieval results, callbacks, and optional multi-agent handoffs. | `wrap_tool_function()`, `to_function_tool()`, `run_query_securely()`, `wrap_query_engine()`, `wrap_retriever()`, `create_node_postprocessor()`, `create_callback_handler()`, `authorize_manager_handoff()` |
675
820
 
676
821
  ### Core Python Module
677
822
 
@@ -862,7 +1007,7 @@ secure_refund = firewall.wrap_delegated_tool_handler(
862
1007
 
863
1008
  ## CrewAI Integration
864
1009
 
865
- AgenticDome provides native CrewAI lifecycle hook integration.
1010
+ AgenticDome provides CrewAI lifecycle hook integration for prompt ingress, tool authorization, delegation, token verification, and output DLP. Importing the module still registers the global CrewAI hooks, and the adapter now also exposes `AgenticDomeCrewAIFirewall` for scoped attach/unregister, explicit local tool wrapping, and testable non-global usage.
866
1011
 
867
1012
  Importing the CrewAI module once registers global hooks for:
868
1013
 
@@ -872,6 +1017,19 @@ before_tool_call
872
1017
  after_tool_call
873
1018
  ```
874
1019
 
1020
+ The CrewAI integration supports:
1021
+
1022
+ - Prompt screening before LLM calls
1023
+ - Direct tool authorization before tool execution
1024
+ - Manager-to-specialist handoff authorization with explicit target metadata
1025
+ - Specialist-side delegated execution verification using direct token metadata or one-time token-store recovery
1026
+ - Redis-backed token storage with `GETDEL` consume fallback and optional HMAC validation
1027
+ - Private `_AgenticDome_*` argument stripping, sanitized tool arguments, and optional schema validation
1028
+ - Output DLP with structured-output preservation and sanitized JSON parsing
1029
+ - Streaming output sanitization through `sanitize_streaming_response()`
1030
+ - Production mode with stable session ID requirements
1031
+ - Local size limits, rate limits, retries/backoff, circuit breaker behavior, audit logs, OpenTelemetry events, and emergency local deny lists
1032
+
875
1033
  ### Install CrewAI Support
876
1034
 
877
1035
  ```bash
@@ -883,14 +1041,11 @@ pip install "agenticdome-python-sdk[crewai]"
883
1041
  To activate global security policies across CrewAI agents, import the CrewAI integration once at the application entry point, such as `main.py`, `app.py`, or your worker bootstrap file.
884
1042
 
885
1043
  ```python
886
- import os
887
-
888
1044
  from crewai import Agent, Crew, Task
889
1045
 
890
1046
  # Importing this module registers AgenticDome global before/after hooks.
891
1047
  import agenticdome_sdk.crewai # noqa: F401
892
1048
 
893
-
894
1049
  manager = Agent(
895
1050
  role="Operations Manager",
896
1051
  goal="Coordinate cross-functional tasks and delegate to specialist units",
@@ -910,36 +1065,62 @@ task = Task(
910
1065
  agent=manager,
911
1066
  )
912
1067
 
913
- crew = Crew(
914
- agents=[manager, researcher],
915
- tasks=[task],
916
- )
917
-
1068
+ crew = Crew(agents=[manager, researcher], tasks=[task])
918
1069
  result = crew.kickoff()
919
- print(result)
920
1070
  ```
921
1071
 
922
- ### CrewAI Security Flow
923
-
924
- #### 1. Prompt Ingress Screening
1072
+ ### Scoped CrewAI Integration
925
1073
 
926
- Before the LLM is called, AgenticDome screens prompts for hostile or policy-violating input.
1074
+ Use the class facade when you want explicit hook functions, scoped attach/unregister, or a test-local client/token store. This is additive to the global import behavior.
927
1075
 
928
- #### 2. Tool Authorization
1076
+ ```python
1077
+ from agenticdome_sdk.crewai import AgenticDomeCrewAIFirewall
929
1078
 
930
- Before a tool is executed, AgenticDome validates tool name, tool arguments, session context, agent identity, and policy metadata.
1079
+ firewall = AgenticDomeCrewAIFirewall()
1080
+ firewall.attach(crew)
1081
+ # ... run a scoped test or runtime ...
1082
+ firewall.unregister(crew)
1083
+ ```
931
1084
 
932
- #### 3. Manager Delegation Authorization
1085
+ For high-risk local tools, wrap the function explicitly. If AgenticDome returns sanitized arguments, the wrapper executes the tool with those sanitized values.
933
1086
 
934
- When a manager agent delegates work to a specialist, AgenticDome authorizes the handoff and can return a cryptographic decision token.
1087
+ ```python
1088
+ @firewall.secure_tool(
1089
+ tool_name="crm.customer.read",
1090
+ tool_platform="crm",
1091
+ tool_schema={"required": ["customer_id"], "properties": {"customer_id": {"type": "string"}}},
1092
+ )
1093
+ def lookup_customer(agent, customer_id: str):
1094
+ return crm.get_customer(customer_id)
1095
+ ```
935
1096
 
936
- #### 4. Specialist Token Verification
1097
+ ### CrewAI Security Flow
937
1098
 
938
- When the specialist executes the delegated tool, the token is verified against the AgenticDome central plane.
1099
+ 1. Before the LLM is called, AgenticDome screens prompts for hostile or policy-violating input.
1100
+ 2. Before a tool is executed, AgenticDome validates tool name, clean tool arguments, session context, agent identity, and policy metadata.
1101
+ 3. When a manager agent delegates work to a specialist, AgenticDome authorizes the handoff and can return a decision token.
1102
+ 4. When the specialist executes the delegated tool, the token is verified against the AgenticDome central plane and consumed once from the local token store when recovered from Redis/in-memory storage.
1103
+ 5. After tool execution, AgenticDome reviews output content and can redact, block, or preserve structured outputs before they leave the runtime boundary.
939
1104
 
940
- #### 5. Output DLP
1105
+ ### Runtime Configuration
941
1106
 
942
- After tool execution, AgenticDome reviews output content for sensitive data and can redact or block it before it leaves the runtime boundary.
1107
+ ```bash
1108
+ export AGENTICDOME_PLATFORM="crewai"
1109
+ export AGENTICDOME_PRODUCTION_MODE="true"
1110
+ export AGENTICDOME_REQUIRE_STABLE_SESSION_ID_IN_PROD="true"
1111
+ export AGENTICDOME_CREWAI_MAX_INPUT_CHARS="50000"
1112
+ export AGENTICDOME_CREWAI_MAX_OUTPUT_CHARS="100000"
1113
+ export AGENTICDOME_CREWAI_MAX_TOOL_ARG_CHARS="20000"
1114
+ export AGENTICDOME_CREWAI_RATE_LIMIT_PER_MINUTE="120"
1115
+ export AGENTICDOME_CREWAI_RETRY_ATTEMPTS="2"
1116
+ export AGENTICDOME_CREWAI_CIRCUIT_BREAKER_FAILURES="5"
1117
+ export AGENTICDOME_CREWAI_AUDIT_LOGGING="true"
1118
+ export AGENTICDOME_CREWAI_OTEL_ENABLED="true"
1119
+ # Optional for distributed multi-worker delegation:
1120
+ # export AGENTICDOME_REDIS_URL="redis://localhost:6379/0"
1121
+ # export AGENTICDOME_REDIS_KEY_PREFIX="AgenticDome:crewai:handoff"
1122
+ # export AGENTICDOME_TOKEN_HMAC_SECRET="replace-with-secret-from-your-secret-manager"
1123
+ ```
943
1124
 
944
1125
  ### CrewAI Import Reference
945
1126
 
@@ -953,6 +1134,7 @@ Optional exported CrewAI objects:
953
1134
  from agenticdome_sdk.crewai import (
954
1135
  CONFIG,
955
1136
  CLIENT,
1137
+ AgenticDomeCrewAIFirewall,
956
1138
  DecisionTokenRecord,
957
1139
  DecisionTokenStore,
958
1140
  InMemoryDecisionTokenStore,
@@ -960,23 +1142,32 @@ from agenticdome_sdk.crewai import (
960
1142
  AgenticDome_before_tool_call,
961
1143
  AgenticDome_after_tool_call,
962
1144
  AgenticDome_before_llm_call,
1145
+ sanitize_streaming_response,
1146
+ attach_firewall,
1147
+ unregister_firewall,
963
1148
  )
964
1149
  ```
965
1150
 
966
- ---
967
-
968
1151
  ## PydanticAI Integration
969
1152
 
970
1153
  AgenticDome also provides a native PydanticAI firewall integration.
971
1154
 
972
1155
  The PydanticAI integration supports:
973
1156
 
974
- - Prompt ingress checks where lifecycle hooks are available
975
- - Tool perimeter authorization through `@firewall.secure_tool`
976
- - Delegation-token generation for handoff tools
977
- - Specialist decision-token verification
978
- - Egress output DLP
979
- - Redis-backed multi-worker handoff-token storage
1157
+ - Prompt ingress checks through legacy lifecycle hooks where available
1158
+ - Native PydanticAI `Hooks` capability creation through `create_hooks()` for current PydanticAI versions
1159
+ - Tool perimeter authorization through `@firewall.secure_tool(...)`
1160
+ - Pydantic/JSON-schema tool argument validation and sanitized-argument execution
1161
+ - Delegation-token generation for handoff tools using clean target args before token injection
1162
+ - Specialist decision-token verification from explicit args or one-time token-store fallback
1163
+ - In-memory and Redis-backed multi-worker handoff-token storage with optional HMAC-tagged records
1164
+ - Egress output DLP with correct `block_on_sensitive_output` semantics
1165
+ - Structured-output preservation by parsing sanitized JSON back to dictionaries/lists
1166
+ - Stable session ID enforcement in production mode
1167
+ - Local rate limits, input/output/tool-argument size limits, retries, circuit breaker behavior, audit logging, and OpenTelemetry span events
1168
+ - Streaming output sanitization with `sanitize_streaming_response()`
1169
+ - Identity-rich policy context from `ctx`, `deps`, or nested identity/principal objects
1170
+ - Local emergency deny lists for tools and agents
980
1171
 
981
1172
  ### Install PydanticAI Support
982
1173
 
@@ -1041,13 +1232,24 @@ customer_support_agent = Agent(
1041
1232
  )
1042
1233
 
1043
1234
 
1044
- # 3. Attach ingress/egress lifecycle protections where supported by the runtime.
1235
+ # 3. Prefer native PydanticAI Hooks where your version supports capabilities.
1236
+ # You can also pass firewall.create_hooks() at Agent construction time via capabilities=[...].
1237
+ firewall.install_native_hooks(customer_support_agent)
1238
+
1239
+ # Legacy PydanticAI versions can still use compatibility lifecycle hooks.
1045
1240
  firewall.attach_to_agent(customer_support_agent)
1046
1241
 
1047
1242
 
1048
1243
  # 4. Protect capability tools using the perimeter decorator.
1049
1244
  @customer_support_agent.tool
1050
- @firewall.secure_tool
1245
+ @firewall.secure_tool(
1246
+ tool_name="customer.profile.read",
1247
+ tool_platform="crm",
1248
+ tool_schema={
1249
+ "required": ["user_id"],
1250
+ "properties": {"user_id": {"type": "string"}},
1251
+ },
1252
+ )
1051
1253
  async def fetch_user_profile(ctx: RunContext[Any], user_id: str) -> dict:
1052
1254
  """Retrieves account management metadata profiles for a corporate ID."""
1053
1255
  return {
@@ -1073,8 +1275,16 @@ firewall = CyberSecFirewall(
1073
1275
  api_key=os.getenv("AGENTICDOME_API_KEY", ""),
1074
1276
  tenant_id=os.getenv("AGENTICDOME_TENANT_ID", ""),
1075
1277
  fail_closed=True,
1278
+ production_mode=True,
1076
1279
  )
1077
1280
  )
1281
+
1282
+ async for safe_chunk in firewall.sanitize_streaming_response(
1283
+ chunks=agent_stream,
1284
+ agent_id="customer_support_agent",
1285
+ session_id="sess_prod_01J4X",
1286
+ ):
1287
+ yield safe_chunk
1078
1288
  ```
1079
1289
 
1080
1290
  ### PydanticAI Import Reference
@@ -1085,6 +1295,7 @@ from agenticdome_sdk.pydantic import (
1085
1295
  FirewallConfig,
1086
1296
  PydanticAIFirewallError,
1087
1297
  PydanticAIFirewallDenied,
1298
+ PydanticAIFirewallConfigurationError,
1088
1299
  DecisionTokenRecord,
1089
1300
  DecisionTokenStore,
1090
1301
  InMemoryDecisionTokenStore,
@@ -1094,11 +1305,13 @@ from agenticdome_sdk.pydantic import (
1094
1305
 
1095
1306
  ### PydanticAI Notes
1096
1307
 
1097
- PydanticAI lifecycle hook APIs may vary between framework versions. The firewall handles this safely:
1308
+ PydanticAI lifecycle hook APIs have evolved. Current PydanticAI documents `pydantic_ai.capabilities.Hooks` for lifecycle interception across runs, model requests, tool validation/execution, output processing, and event streams. Prefer `create_hooks()` or `install_native_hooks()` for current runtimes, and keep `@firewall.secure_tool(...)` on sensitive local tools as a hard enforcement boundary.
1098
1309
 
1099
- - If compatible lifecycle decorators are available, `attach_to_agent()` attaches prompt ingress and egress DLP hooks.
1100
- - If lifecycle decorators are not available, `@firewall.secure_tool` still protects tool execution.
1101
- - Tool authorization and DLP remain available through the secure tool decorator.
1310
+ - If compatible legacy lifecycle decorators are available, `attach_to_agent()` attaches prompt ingress and egress DLP hooks.
1311
+ - If native `Hooks` capabilities are available, `create_hooks()` returns a capability object you can pass into `Agent(..., capabilities=[...])`.
1312
+ - If lifecycle decorators are not available, `@firewall.secure_tool(...)` still protects tool execution.
1313
+ - In production mode, configure API base, API key, tenant ID, and stable session IDs.
1314
+ - `AGENTICDOME_BLOCK_ON_SENSITIVE_OUTPUT=true` means AgenticDome may ask Mesh to block sensitive output; the SDK only blocks when the policy response verdict is `BLOCKED`.
1102
1315
 
1103
1316
  ---
1104
1317
 
@@ -1112,7 +1325,13 @@ The LangGraph integration supports:
1112
1325
  - Tool-call authorization through `authorize_transition()` or `transition_node()`
1113
1326
  - Delegation authorization when state or tool arguments identify `target_agent_id`, `delegate_to`, `coworker`, `specialist_agent_id`, or equivalent handoff fields
1114
1327
  - Specialist-side decision-token verification from graph state, tool arguments, or Redis/in-memory token storage
1328
+ - One-time decision-token consumption with optional HMAC binding for stored token records
1329
+ - Sanitized tool-argument mutation before local tool execution
1115
1330
  - Final message and tool-output DLP through `sanitize_output()` or `output_node()`
1331
+ - Retrieval/document sanitization through `sanitize_retrieval_documents()`
1332
+ - Streaming event sanitization through `sanitize_streaming_events()`
1333
+ - Graph transition authorization through `authorize_graph_transition()` or `graph_transition_node()`
1334
+ - `security_block` route support through `security_route()`
1116
1335
  - Wrapper helpers for existing agent nodes and tool nodes
1117
1336
 
1118
1337
  ### Install LangGraph Support
@@ -1168,7 +1387,10 @@ firewall = AgenticDomeLangGraphFirewall(
1168
1387
  api_key=os.getenv("AGENTICDOME_API_KEY", ""),
1169
1388
  tenant_id=os.getenv("AGENTICDOME_TENANT_ID", ""),
1170
1389
  fail_closed=True,
1390
+ production_mode=True,
1171
1391
  require_explicit_session_id=True,
1392
+ rate_limit_per_minute=120,
1393
+ max_tool_arg_chars=20_000,
1172
1394
  )
1173
1395
  )
1174
1396
 
@@ -1250,7 +1472,30 @@ state["AgenticDome"] = {
1250
1472
  }
1251
1473
  ```
1252
1474
 
1253
- The specialist execution is verified when the specialist tool call reaches `authorize_transition()` or a wrapped tool node. Tokens can be carried in state, passed as `_AgenticDome_decision_token`, or recovered from Redis/in-memory token storage.
1475
+ The specialist execution is verified when the specialist tool call reaches `authorize_transition()` or a wrapped tool node. Tokens can be carried in state, passed as `_AgenticDome_decision_token`, or recovered from Redis/in-memory token storage. Stored records are consumed once; Redis deployments use atomic `GETDEL` when available and fall back to a pipeline. Set `AGENTICDOME_TOKEN_HMAC_SECRET` to bind stored tokens to the source agent, target agent, tool name, and sanitized argument hash.
1476
+
1477
+ ### LangGraph Hardening Helpers
1478
+
1479
+ Use `authorize_graph_transition()` or `graph_transition_node()` when sensitive graph edges should be policy-controlled. Blocked states set `AgenticDome.route` and `next_agent_id` to `security_block`, and `security_route()` can be used as a conditional-edge router.
1480
+
1481
+ ```python
1482
+ graph.add_node(
1483
+ "authorize_escalation",
1484
+ firewall.graph_transition_node(
1485
+ from_node="triage",
1486
+ to_node="refund_specialist",
1487
+ agent_id="support_orchestrator",
1488
+ ),
1489
+ )
1490
+
1491
+ graph.add_conditional_edges(
1492
+ "authorize_escalation",
1493
+ firewall.security_route,
1494
+ {"continue": "refund_specialist", "security_block": "security_block"},
1495
+ )
1496
+ ```
1497
+
1498
+ Use `sanitize_retrieval_documents()` before adding retrieved chunks to model context, and `sanitize_streaming_events()` for async event streams. Both use the same Mesh output policy path as final-output sanitization.
1254
1499
 
1255
1500
  ### LangGraph Import Reference
1256
1501
 
@@ -1271,7 +1516,7 @@ from agenticdome_sdk.langgraph import (
1271
1516
  ### LangGraph Accuracy and Interception Notes
1272
1517
 
1273
1518
  - LangGraph itself is graph-native: reliable interception is normally achieved by inserting security nodes into the graph or wrapping existing nodes/tool nodes.
1274
- - LangChain's modern `create_agent()` API supports a `middleware` parameter, and LangChain documents middleware hooks as the way to intercept model, tool, and agent-loop behavior. This SDK exposes `as_langchain_middleware()` for that style while keeping LangGraph node wrappers for teams that own explicit `StateGraph` topology.
1519
+ - LangChain's modern `create_agent()` API supports a `middleware` parameter, and LangChain documents middleware hooks as the way to intercept model, tool, and agent-loop behavior. This SDK exposes `as_langchain_middleware()` for that style while keeping LangGraph node wrappers for teams that own explicit `StateGraph` topology. The adapter mutates sanitized tool arguments back into the tool request for local execution.
1275
1520
  - For custom `StateGraph` workflows, middleware is still needed in practice, but it should be implemented as graph nodes or wrappers at the boundaries you need to enforce: before model input, before tool execution, before handoff execution, and before final output.
1276
1521
  - If a graph contains remote tools or provider-hosted tools that execute outside your Python process, the Python SDK can only guard the local request/response boundary. It cannot intercept inside the remote provider runtime.
1277
1522
 
@@ -1288,13 +1533,19 @@ AgenticDome provides an async firewall helper for Microsoft Agent Framework for
1288
1533
 
1289
1534
  The Microsoft Agent Framework integration supports:
1290
1535
 
1291
- - Prompt ingress screening with `screen_input()` or `run_agent_securely()`
1292
- - Direct function-tool authorization with `authorize_direct_tool_call()` or `wrap_tool_handler()`
1293
- - Manager-to-specialist delegation authorization with `authorize_manager_handoff()`
1536
+ - Prompt ingress screening with `screen_input()`, native-style middleware hooks, or `run_agent_securely()`
1537
+ - Direct function-tool authorization with internal argument stripping and sanitized-argument enforcement
1538
+ - Manager-to-specialist delegation authorization with HMAC-tagged token records and atomic Redis consumption where available
1294
1539
  - Specialist-side token verification with `verify_specialist_execution()` or `wrap_delegated_tool_handler()`
1295
- - Output DLP with `sanitize_text()`
1296
- - Optional Copilot / AI Foundry helper calls when enabled
1540
+ - Stable session ID enforcement for production deployments
1541
+ - Entra/principal identity context propagation into policy context
1542
+ - Output DLP with structured JSON preservation and optional response-object mutation
1543
+ - Streaming output sanitization with `sanitize_streaming_response()`
1544
+ - OpenTelemetry event emission and structured audit logging
1545
+ - Local rate limits, input/output/argument size limits, retries, and circuit breaker protection
1546
+ - Optional Copilot / AI Foundry threat helper enforcement when enabled
1297
1547
  - Redis-backed multi-worker decision-token storage
1548
+ - Emergency local deny lists for tools or agents
1298
1549
 
1299
1550
  ### Install Microsoft Helper Support
1300
1551
 
@@ -1362,6 +1613,9 @@ secure_get_customer_profile = firewall.wrap_tool_handler(
1362
1613
  tool_platform="crm",
1363
1614
  )
1364
1615
 
1616
+ # If AgenticDome returns sanitized_tool_args, the wrapped handler receives
1617
+ # those safe arguments instead of the original model-provided arguments.
1618
+
1365
1619
 
1366
1620
  @tool(approval_mode="never_require")
1367
1621
  async def get_customer_profile(
@@ -1376,6 +1630,25 @@ async def get_customer_profile(
1376
1630
  return await secure_get_customer_profile(ctx, {"customer_id": customer_id})
1377
1631
  ```
1378
1632
 
1633
+ ### Microsoft Native-Style Middleware Hooks
1634
+
1635
+ Use `create_middleware()` or `install_on_agent()` when your Microsoft Agent Framework runtime exposes middleware or callback-style extension points. These hooks provide a harder-to-bypass assembly-level integration while preserving the explicit wrappers for tool enforcement.
1636
+
1637
+ ```python
1638
+ firewall = AgenticDomeMicrosoftAgentFirewall()
1639
+
1640
+ agent = firewall.install_on_agent(agent)
1641
+ middleware = firewall.create_middleware()
1642
+
1643
+ # The returned middleware exposes async hook methods:
1644
+ # before_agent_run(ctx, input_text)
1645
+ # after_agent_run(ctx, output)
1646
+ # before_tool_call(ctx, tool_name, tool_args)
1647
+ # after_tool_call(ctx, tool_name, result)
1648
+ ```
1649
+
1650
+ `before_tool_call()` returns the sanitized tool arguments that should be forwarded to the local tool executor.
1651
+
1379
1652
  ### Microsoft Quickstart: Secure an Agent Run Boundary
1380
1653
 
1381
1654
  Use `run_agent_securely()` when you need prompt ingress and final-output DLP around a complete agent call.
@@ -1416,6 +1689,31 @@ secure_refund_handler = firewall.wrap_delegated_tool_handler(
1416
1689
  )
1417
1690
  ```
1418
1691
 
1692
+ ### Microsoft Production Configuration
1693
+
1694
+ ```bash
1695
+ export AGENTICDOME_PLATFORM="microsoft_agent_framework_v1"
1696
+ export AGENTICDOME_PRODUCTION_MODE="true"
1697
+ export AGENTICDOME_REQUIRE_STABLE_SESSION_ID_IN_PROD="true"
1698
+ export AGENTICDOME_MSAF_MAX_INPUT_CHARS="50000"
1699
+ export AGENTICDOME_MSAF_MAX_OUTPUT_CHARS="100000"
1700
+ export AGENTICDOME_MSAF_MAX_TOOL_ARG_CHARS="20000"
1701
+ export AGENTICDOME_MSAF_RATE_LIMIT_PER_MINUTE="0"
1702
+ export AGENTICDOME_MSAF_RETRY_ATTEMPTS="2"
1703
+ export AGENTICDOME_MSAF_CIRCUIT_BREAKER_FAILURES="5"
1704
+ export AGENTICDOME_MSAF_CIRCUIT_BREAKER_RESET_S="60"
1705
+ export AGENTICDOME_MSAF_AUDIT_LOGGING="true"
1706
+ export AGENTICDOME_MSAF_OTEL_ENABLED="true"
1707
+ # Optional local emergency controls:
1708
+ # export AGENTICDOME_MSAF_EMERGENCY_BLOCK_TOOLS="payments.refund.create"
1709
+ # export AGENTICDOME_MSAF_EMERGENCY_BLOCK_AGENTS="legacy_agent"
1710
+ # Optional HMAC tag for stored decision-token records:
1711
+ # export AGENTICDOME_TOKEN_HMAC_SECRET="change-me"
1712
+ # Optional Copilot / AI Foundry helper enforcement:
1713
+ # export AGENTICDOME_ENABLE_COPILOT_THREAT_API="true"
1714
+ # export AGENTICDOME_ENFORCE_COPILOT_THREAT_API="true"
1715
+ ```
1716
+
1419
1717
  ### Microsoft Import Reference
1420
1718
 
1421
1719
  ```python
@@ -1437,7 +1735,7 @@ from agenticdome_sdk.microsoft_agent_framework import (
1437
1735
  - The framework has a tool approval feature for human-in-the-loop gating, but approval is not the same as policy enforcement, DLP, or tenant-aware A2A token verification. AgenticDome should sit at the local tool handler or workflow executor boundary for deterministic enforcement.
1438
1736
  - Microsoft workflows expose execution through workflow builders, executors, streaming events, and output events. For security enforcement, wrap the executor/run boundary or the tool/executor functions that process sensitive actions.
1439
1737
  - If a tool executes remotely inside a hosted provider, Foundry agent, Copilot Studio agent, hosted MCP server, or remote A2A agent, this local Python SDK cannot intercept inside that remote runtime. It can still protect the local request before the call, local function tools, local MCP gateways, workflow executor boundaries, and returned output.
1440
- - Middleware/wrappers are therefore needed for robust interception. Use `wrap_tool_handler()` for local tools, `wrap_delegated_tool_handler()` for delegated specialist tools, and `run_agent_securely()` for whole-agent ingress/egress protection.
1738
+ - Middleware/wrappers are therefore needed for robust interception. Prefer `create_middleware()` or `install_on_agent()` where the runtime supports hooks, use `wrap_tool_handler()` for local tools, `wrap_delegated_tool_handler()` for delegated specialist tools, and `run_agent_securely()` for whole-agent ingress/egress protection. In production, pass stable `session_id`/`run_id`/`trace_id` values and Entra/principal identity fields in context.
1441
1739
 
1442
1740
  Official references:
1443
1741
 
@@ -1453,12 +1751,19 @@ AgenticDome provides a Microsoft AI Foundry adapter for the local boundaries you
1453
1751
 
1454
1752
  The Foundry integration supports:
1455
1753
 
1456
- - Prompt/run validation through `validate_prompt_contract()` or `run_secure()`
1457
- - Local function-tool execution analysis through `analyze_tool_execution()` or `wrap_tool_executor()`
1754
+ - Prompt/run validation through `validate_prompt_contract()`, `before_run()`, or `run_secure()`
1755
+ - Native-style middleware hooks through `create_middleware()` and `install_on_client()` for clients that expose a middleware list
1756
+ - Local function-tool execution analysis through `analyze_tool_execution()`, `before_tool_call()`, or `wrap_tool_executor()`
1458
1757
  - `@firewall.secure_tool(...)` for high-risk local tool callables
1459
- - Optional output DLP through Mesh when `AGENTICDOME_API_KEY` and `AGENTICDOME_TENANT_ID` are configured
1460
- - Optional incident reporting when API-key auth is configured
1461
- - Structured-output preservation when Mesh returns unchanged JSON
1758
+ - Direct tool-argument stripping, lightweight JSON-schema validation, and sanitized-argument execution when AgenticDome returns safer arguments
1759
+ - Enterprise identity context propagation for Entra IDs, roles/scopes, Foundry project IDs, and Purview or sensitivity labels
1760
+ - Production-mode stable session ID enforcement and output-sanitization requirements
1761
+ - Output DLP through Mesh when `AGENTICDOME_API_KEY` and `AGENTICDOME_TENANT_ID` are configured
1762
+ - Structured-output preservation by parsing sanitized JSON back to dictionaries/lists where possible
1763
+ - Local rate limits, input/output/tool-argument size limits, retries, circuit breaker behavior, audit logging, and OpenTelemetry span events
1764
+ - Streaming response sanitization through `sanitize_streaming_response()`
1765
+ - Optional manager-to-specialist handoff authorization, decision-token verification, in-memory token storage, Redis token storage, and HMAC-tagged token records
1766
+ - Local emergency deny lists for tools and agents
1462
1767
 
1463
1768
  ### Install Foundry Support
1464
1769
 
@@ -1483,11 +1788,39 @@ export AGENTICDOME_API_BASE="https://au.agenticdome.io"
1483
1788
  export AGENTICDOME_BEARER_TOKEN="your_foundry_threat_contract_bearer_token"
1484
1789
  ```
1485
1790
 
1486
- Mesh output DLP and incident reporting are optional and use API-key authentication:
1791
+ Mesh output DLP and incident reporting use API-key authentication. In production mode, output sanitization is required by default, so configure API-key auth as part of deployment:
1487
1792
 
1488
1793
  ```bash
1489
1794
  export AGENTICDOME_API_KEY="your_api_key"
1490
1795
  export AGENTICDOME_TENANT_ID="your_tenant_id"
1796
+ export AGENTICDOME_PRODUCTION_MODE="true"
1797
+ export AGENTICDOME_REQUIRE_STABLE_SESSION_ID_IN_PROD="true"
1798
+ export AGENTICDOME_FOUNDRY_REQUIRE_OUTPUT_SANITIZATION_IN_PROD="true"
1799
+ ```
1800
+
1801
+ For distributed delegated execution, configure Redis and optionally HMAC-tag stored decision-token records:
1802
+
1803
+ ```bash
1804
+ export AGENTICDOME_REDIS_URL="redis://redis.internal:6379/0"
1805
+ export AGENTICDOME_REDIS_KEY_PREFIX="AgenticDome:foundry:handoff"
1806
+ export AGENTICDOME_TOKEN_HMAC_SECRET="replace-with-secret-from-kms"
1807
+ ```
1808
+
1809
+ ### Native-Style Middleware Hooks
1810
+
1811
+ Use middleware hooks where your Foundry client or local runtime exposes a middleware pipeline. Hard enforcement still happens inside the hook methods and wrappers.
1812
+
1813
+ ```python
1814
+ from agenticdome_sdk.microsoft_ai_foundry import AgenticDomeMicrosoftAIFoundryFirewall
1815
+
1816
+ firewall = AgenticDomeMicrosoftAIFoundryFirewall()
1817
+ foundry_client = firewall.install_on_client(foundry_client)
1818
+
1819
+ # For custom runtimes, register the middleware object explicitly.
1820
+ middleware = firewall.create_middleware()
1821
+ await middleware.before_run(ctx, input_text)
1822
+ result = await foundry_agent.run(input_text)
1823
+ result = await middleware.after_run(ctx, result)
1491
1824
  ```
1492
1825
 
1493
1826
  ### Secure a Foundry Run Boundary
@@ -1523,6 +1856,10 @@ secure_lookup_customer = firewall.wrap_tool_executor(
1523
1856
  tool_name="crm.customer.read",
1524
1857
  tool_platform="crm",
1525
1858
  handler=raw_lookup_customer,
1859
+ tool_schema={
1860
+ "required": ["customer_id"],
1861
+ "properties": {"customer_id": {"type": "string"}},
1862
+ },
1526
1863
  )
1527
1864
 
1528
1865
  result = await secure_lookup_customer(
@@ -1534,11 +1871,55 @@ result = await secure_lookup_customer(
1534
1871
  ### Decorator Form
1535
1872
 
1536
1873
  ```python
1537
- @firewall.secure_tool(tool_name="payments.refund.create", tool_platform="payments")
1874
+ @firewall.secure_tool(
1875
+ tool_name="payments.refund.create",
1876
+ tool_platform="payments",
1877
+ tool_schema={
1878
+ "required": ["customer_id", "amount_cents"],
1879
+ "properties": {
1880
+ "customer_id": {"type": "string"},
1881
+ "amount_cents": {"type": "integer"},
1882
+ },
1883
+ },
1884
+ )
1538
1885
  def create_refund(ctx, args):
1539
1886
  return {"refund_id": "rfnd_123", "status": "created"}
1540
1887
  ```
1541
1888
 
1889
+ ### Delegated Foundry Tool Execution
1890
+
1891
+ Use handoff controls when one Foundry agent or manager delegates sensitive local tool execution to another agent. The authorization response can store a decision token locally or in Redis; the specialist side consumes and verifies that token before executing.
1892
+
1893
+ ```python
1894
+ await firewall.authorize_manager_handoff(
1895
+ text="Ask the billing specialist to create a refund.",
1896
+ manager_agent_id="foundry_manager",
1897
+ specialist_agent_id="billing_specialist",
1898
+ tool_name="payments.refund.create",
1899
+ tool_args={"customer_id": "cust_123", "amount_cents": 2500},
1900
+ session_id="sess_prod_01J4X",
1901
+ tool_platform="payments",
1902
+ )
1903
+
1904
+ await firewall.verify_delegated_execution(
1905
+ specialist_agent_id="billing_specialist",
1906
+ tool_name="payments.refund.create",
1907
+ tool_args={"customer_id": "cust_123", "amount_cents": 2500},
1908
+ session_id="sess_prod_01J4X",
1909
+ )
1910
+ ```
1911
+
1912
+ ### Streaming Output Sanitization
1913
+
1914
+ ```python
1915
+ async for safe_chunk in firewall.sanitize_streaming_response(
1916
+ chunks=foundry_stream,
1917
+ agent_id="foundry_support_agent",
1918
+ session_id="sess_prod_01J4X",
1919
+ ):
1920
+ yield safe_chunk
1921
+ ```
1922
+
1542
1923
  ### Import Reference
1543
1924
 
1544
1925
  ```python
@@ -1548,15 +1929,21 @@ from agenticdome_sdk.microsoft_ai_foundry import (
1548
1929
  MicrosoftAIFoundryDenied,
1549
1930
  MicrosoftAIFoundryFirewallError,
1550
1931
  MicrosoftAIFoundryConfigurationError,
1932
+ DecisionTokenRecord,
1933
+ DecisionTokenStore,
1934
+ InMemoryDecisionTokenStore,
1935
+ RedisDecisionTokenStore,
1551
1936
  )
1552
1937
  ```
1553
1938
 
1554
1939
  ### Microsoft AI Foundry Accuracy and Interception Notes
1555
1940
 
1556
- - Environment configuration alone does not intercept Foundry execution. You must call `run_secure()`, `wrap_tool_executor()`, or `@firewall.secure_tool(...)` at the local run/tool boundary.
1941
+ - Environment configuration alone does not intercept Foundry execution. Attach `create_middleware()` / `install_on_client()` where supported, and still use `run_secure()`, `wrap_tool_executor()`, or `@firewall.secure_tool(...)` at hard local boundaries.
1557
1942
  - Foundry function calling asks your application to execute local functions and return tool output. AgenticDome should wrap that local execution before tool output is submitted back to Foundry.
1943
+ - Production deployments should pass a stable `session_id`, `run_id`, `trace_id`, `conversation_id`, or `thread_id`; generated fallback IDs are intended for local development only.
1944
+ - Pass Entra identity, roles/scopes, Foundry project IDs, and Purview/sensitivity labels on `ctx` or `policy_context` so server-side policy can make identity-aware decisions.
1558
1945
  - If a Foundry hosted tool executes entirely inside a remote provider runtime, this local Python SDK can protect the local request/response boundary but cannot inspect inside the remote execution environment.
1559
- - Mesh output DLP is skipped when `AGENTICDOME_API_KEY` is not configured; threat-contract prompt and tool analysis still use bearer auth.
1946
+ - Mesh output DLP is skipped when `AGENTICDOME_API_KEY` is not configured unless production mode requires output sanitization. Threat-contract prompt and tool analysis still use bearer auth.
1560
1947
 
1561
1948
  Official references:
1562
1949
 
@@ -1567,17 +1954,21 @@ Official references:
1567
1954
 
1568
1955
  ## OpenAI Agents SDK Integration
1569
1956
 
1570
- AgenticDome provides a Python adapter for OpenAI Agents SDK local execution boundaries. This integration makes sense because the OpenAI Agents SDK is Python-first, supports `Runner.run(...)`, function tools, guardrails, handoffs, and agents-as-tools. AgenticDome complements those primitives by enforcing tenant policy before local function tools execute and by sanitizing outputs before they leave the runtime.
1957
+ AgenticDome provides a production OpenAI Agents SDK adapter for the local execution boundaries your application controls. The OpenAI Agents SDK includes agents, function tools, guardrails, handoffs, sessions, streaming, and tracing; AgenticDome complements those primitives by enforcing tenant policy before local tool execution, validating delegated specialist execution, and sanitizing outputs before they leave the runtime.
1571
1958
 
1572
1959
  The OpenAI Agents SDK integration supports:
1573
1960
 
1574
- - Prompt ingress screening with `screen_input()` or `run_agent_securely()`
1961
+ - Prompt ingress screening with `screen_input()`, `run_agent_securely()`, `run_agent_stream_securely()`, or `create_input_guardrail()`
1575
1962
  - Direct function-tool authorization with `wrap_tool_handler()` or `@firewall.secure_tool(...)`
1963
+ - Private `_AgenticDome_*` argument stripping, sanitized tool arguments, and optional schema validation
1576
1964
  - Manager-to-specialist handoff authorization with `authorize_manager_handoff()`
1577
- - Specialist-side token verification with `wrap_delegated_tool_handler()`
1578
- - Output DLP with `sanitize_output()`
1579
- - Redis-backed multi-worker delegation-token storage
1580
- - Structured-output preservation when Mesh returns unchanged JSON
1965
+ - Specialist-side token verification with `verify_specialist_execution()` and `wrap_delegated_tool_handler()`
1966
+ - In-memory or Redis-backed multi-worker decision-token storage with one-time consume and optional HMAC validation
1967
+ - Output DLP with `sanitize_output()` and `create_output_guardrail()`
1968
+ - Streaming output sanitization with `sanitize_streaming_response()`
1969
+ - Structured-output preservation when Mesh returns unchanged JSON, and JSON parsing when Mesh returns sanitized structured output
1970
+ - Production mode with stable session ID requirements
1971
+ - Local size limits, rate limits, retries/backoff, circuit breaker behavior, audit logs, OpenTelemetry events, identity-rich policy context, and emergency local deny lists
1581
1972
 
1582
1973
  ### Install OpenAI Agents Support
1583
1974
 
@@ -1608,9 +1999,20 @@ result = await firewall.run_agent_securely(
1608
1999
  )
1609
2000
  ```
1610
2001
 
2002
+ For streamed runs, use `run_agent_stream_securely()` or pass the stream through `sanitize_streaming_response()` before returning chunks to the caller.
2003
+
2004
+ ### Register Guardrail Helpers
2005
+
2006
+ Use these helpers when your OpenAI Agents SDK wiring supports input/output guardrail slots. Tool authorization should still be enforced at function-tool boundaries because tool execution can happen multiple times inside a run.
2007
+
2008
+ ```python
2009
+ input_guardrail = firewall.create_input_guardrail()
2010
+ output_guardrail = firewall.create_output_guardrail()
2011
+ ```
2012
+
1611
2013
  ### Secure a Function Tool
1612
2014
 
1613
- Wrap the local function-tool implementation before exposing it with `@function_tool`.
2015
+ Wrap the local function-tool implementation before exposing it with `@function_tool`. If AgenticDome returns sanitized arguments, the wrapper executes the tool with the sanitized arguments and strips private metadata before the handler runs.
1614
2016
 
1615
2017
  ```python
1616
2018
  from agents import function_tool
@@ -1624,6 +2026,7 @@ async def raw_lookup_customer(ctx, args):
1624
2026
  secure_lookup_customer = firewall.wrap_tool_handler(
1625
2027
  tool_name="crm.customer.read",
1626
2028
  tool_platform="crm",
2029
+ tool_schema={"required": ["customer_id"], "properties": {"customer_id": {"type": "string"}}},
1627
2030
  handler=raw_lookup_customer,
1628
2031
  )
1629
2032
 
@@ -1654,6 +2057,26 @@ secure_refund_tool = firewall.wrap_delegated_tool_handler(
1654
2057
  )
1655
2058
  ```
1656
2059
 
2060
+ ### Runtime Configuration
2061
+
2062
+ ```bash
2063
+ export AGENTICDOME_PLATFORM="openai_agents_sdk"
2064
+ export AGENTICDOME_PRODUCTION_MODE="true"
2065
+ export AGENTICDOME_REQUIRE_STABLE_SESSION_ID_IN_PROD="true"
2066
+ export AGENTICDOME_OPENAI_AGENTS_MAX_INPUT_CHARS="50000"
2067
+ export AGENTICDOME_OPENAI_AGENTS_MAX_OUTPUT_CHARS="100000"
2068
+ export AGENTICDOME_OPENAI_AGENTS_MAX_TOOL_ARG_CHARS="20000"
2069
+ export AGENTICDOME_OPENAI_AGENTS_RATE_LIMIT_PER_MINUTE="120"
2070
+ export AGENTICDOME_OPENAI_AGENTS_RETRY_ATTEMPTS="2"
2071
+ export AGENTICDOME_OPENAI_AGENTS_CIRCUIT_BREAKER_FAILURES="5"
2072
+ export AGENTICDOME_OPENAI_AGENTS_AUDIT_LOGGING="true"
2073
+ export AGENTICDOME_OPENAI_AGENTS_OTEL_ENABLED="true"
2074
+ # Optional for distributed multi-worker delegation:
2075
+ # export AGENTICDOME_REDIS_URL="redis://localhost:6379/0"
2076
+ # export AGENTICDOME_REDIS_KEY_PREFIX="AgenticDome:openai_agents:handoff"
2077
+ # export AGENTICDOME_TOKEN_HMAC_SECRET="replace-with-secret-from-your-secret-manager"
2078
+ ```
2079
+
1657
2080
  ### Import Reference
1658
2081
 
1659
2082
  ```python
@@ -1663,6 +2086,7 @@ from agenticdome_sdk.openai_agents import (
1663
2086
  OpenAIAgentsFirewallDenied,
1664
2087
  OpenAIAgentsFirewallError,
1665
2088
  DecisionTokenRecord,
2089
+ DecisionTokenStore,
1666
2090
  InMemoryDecisionTokenStore,
1667
2091
  RedisDecisionTokenStore,
1668
2092
  )
@@ -1670,10 +2094,11 @@ from agenticdome_sdk.openai_agents import (
1670
2094
 
1671
2095
  ### OpenAI Agents SDK Accuracy and Interception Notes
1672
2096
 
1673
- - Environment configuration alone does not intercept OpenAI Agents SDK execution. You must wrap `Runner.run(...)`, local function tools, or delegated specialist tools.
1674
- - OpenAI Agents SDK guardrails are useful, but OpenAI's own docs note that agent-level input/output guardrails run only at specific workflow boundaries; tool guardrails run around every custom function-tool invocation. AgenticDome should therefore sit at function-tool boundaries for side-effecting tools.
2097
+ - Environment configuration alone does not intercept OpenAI Agents SDK execution. You must wrap `Runner.run(...)`, streamed runner paths, local function tools, or delegated specialist tools, or register the guardrail helpers where your SDK wiring supports them.
2098
+ - OpenAI Agents SDK guardrails are useful at run boundaries, but side-effecting local tools still need function-tool wrappers because a single agent run can invoke tools multiple times.
1675
2099
  - Handoffs are represented as tools to the model, so manager-to-specialist policy should be enforced where handoff/tool execution is invoked.
1676
2100
  - Hosted tools, MCP tools, or remote runtimes that execute outside your Python process can only be protected at the local request/response boundary; the SDK cannot inspect inside the remote provider runtime.
2101
+ - Production deployments should use stable `session_id`, `run_id`, `trace_id`, `conversation_id`, or `thread_id` values and Redis-backed token storage when manager authorization and specialist execution can happen in different workers.
1677
2102
 
1678
2103
  Official references:
1679
2104
 
@@ -1686,16 +2111,21 @@ Official references:
1686
2111
 
1687
2112
  ## Agno Integration
1688
2113
 
1689
- AgenticDome provides a production Agno adapter for the local hook surfaces that Agno exposes on agents and teams. Agno's SDK includes agents, teams, workflows, tools, guardrails, and lifecycle hooks; the AgenticDome adapter attaches to the local `pre_hooks`, `post_hooks`, and `tool_hooks` boundaries so policy can be enforced before prompts/tools run and before output is returned.
2114
+ AgenticDome provides a production Agno adapter for the local hook surfaces that Agno exposes on agents and teams. Agno's Agent reference documents `pre_hooks`, `post_hooks`, and `tool_hooks`; the adapter attaches to those boundaries so policy can be enforced before prompts/tools run and before output is returned. It also exposes middleware/plugin-shaped helper objects for applications that centralize hook registration.
1690
2115
 
1691
2116
  The Agno integration supports:
1692
2117
 
1693
2118
  - Prompt ingress screening through `pre_hook` / `cybersec_pre_hook`
1694
2119
  - Tool-call authorization through `pre_hook`, `tool_hook`, and `@firewall.secure_tool`
2120
+ - Private `_AgenticDome_*` argument stripping, sanitized tool arguments, and optional schema validation
1695
2121
  - Manager-to-specialist delegation authorization when handoff metadata is present
1696
- - Specialist-side decision-token verification from hook kwargs, tool args, or Redis/in-memory token storage
1697
- - Output DLP through `post_hook` / `cybersec_post_hook`
2122
+ - Specialist-side one-time decision-token verification from hook kwargs, tool args, or Redis/in-memory token storage
2123
+ - Optional token HMAC validation for stored delegation decisions
2124
+ - Output DLP through `post_hook` / `cybersec_post_hook` with structured-output preservation and sanitized JSON parsing
1698
2125
  - Optional retrieved-context sanitization for Agno knowledge/RAG pipelines
2126
+ - Streaming output sanitization through `sanitize_streaming_response()`
2127
+ - Production mode with stable session ID requirements
2128
+ - Local size limits, rate limits, retries/backoff, circuit breaker behavior, audit logs, OpenTelemetry events, identity-rich policy context, and emergency local deny lists
1699
2129
 
1700
2130
  ### Install Agno Support
1701
2131
 
@@ -1736,16 +2166,28 @@ post_hooks -> final output DLP and redaction/blocking
1736
2166
  tool_hooks -> additional local tool boundary enforcement where Agno invokes tool hooks
1737
2167
  ```
1738
2168
 
2169
+ For applications that use a centralized registration layer, use:
2170
+
2171
+ ```python
2172
+ hook_bundle = firewall.create_hook_bundle()
2173
+ middleware = firewall.create_middleware()
2174
+ plugin = firewall.create_plugin()
2175
+ ```
2176
+
1739
2177
  ### Agno Quickstart: Decorate High-Risk Tools
1740
2178
 
1741
- Use the decorator when a local tool reads sensitive data, mutates state, sends messages, writes files, calls payment systems, or triggers external APIs.
2179
+ Use the decorator when a local tool reads sensitive data, mutates state, sends messages, writes files, calls payment systems, or triggers external APIs. If AgenticDome returns sanitized arguments, the wrapper executes the tool with sanitized values and strips private metadata.
1742
2180
 
1743
2181
  ```python
1744
2182
  from agenticdome_sdk.agno import AgenticDomeAgnoFirewall
1745
2183
 
1746
2184
  firewall = AgenticDomeAgnoFirewall()
1747
2185
 
1748
- @firewall.secure_tool(tool_name="crm.customer.read", tool_platform="crm")
2186
+ @firewall.secure_tool(
2187
+ tool_name="crm.customer.read",
2188
+ tool_platform="crm",
2189
+ tool_schema={"required": ["customer_id"], "properties": {"customer_id": {"type": "string"}}},
2190
+ )
1749
2191
  def lookup_customer(agent, customer_id: str) -> dict:
1750
2192
  return {"customer_id": customer_id, "email": "alice@example.com"}
1751
2193
  ```
@@ -1769,7 +2211,7 @@ firewall.pre_hook(
1769
2211
  )
1770
2212
  ```
1771
2213
 
1772
- The specialist side can verify a token passed in args or recover it from Redis/in-memory storage:
2214
+ The specialist side can verify a token passed in args or recover it from Redis/in-memory storage. Stored tokens are consumed once.
1773
2215
 
1774
2216
  ```python
1775
2217
  firewall.pre_hook(
@@ -1780,9 +2222,9 @@ firewall.pre_hook(
1780
2222
  )
1781
2223
  ```
1782
2224
 
1783
- ### Agno Retrieved Context Sanitization
2225
+ ### Agno Retrieved Context and Streaming Sanitization
1784
2226
 
1785
- Use this helper before retrieved context is shown to a user or passed deeper into an agent loop.
2227
+ Use these helpers before retrieved or streamed content is shown to a user or passed deeper into an agent loop.
1786
2228
 
1787
2229
  ```python
1788
2230
  safe_context = firewall.sanitize_retrieved_text(
@@ -1791,6 +2233,33 @@ safe_context = firewall.sanitize_retrieved_text(
1791
2233
  session_id="sess_prod_01J4X",
1792
2234
  policy_context={"source": "agno_knowledge"},
1793
2235
  )
2236
+
2237
+ async for safe_chunk in firewall.sanitize_streaming_response(
2238
+ chunks,
2239
+ agent_id="support_agent",
2240
+ session_id="sess_prod_01J4X",
2241
+ ):
2242
+ yield safe_chunk
2243
+ ```
2244
+
2245
+ ### Runtime Configuration
2246
+
2247
+ ```bash
2248
+ export AGENTICDOME_PLATFORM="agno"
2249
+ export AGENTICDOME_PRODUCTION_MODE="true"
2250
+ export AGENTICDOME_REQUIRE_STABLE_SESSION_ID_IN_PROD="true"
2251
+ export AGENTICDOME_AGNO_MAX_INPUT_CHARS="50000"
2252
+ export AGENTICDOME_AGNO_MAX_OUTPUT_CHARS="100000"
2253
+ export AGENTICDOME_AGNO_MAX_TOOL_ARG_CHARS="20000"
2254
+ export AGENTICDOME_AGNO_RATE_LIMIT_PER_MINUTE="120"
2255
+ export AGENTICDOME_AGNO_RETRY_ATTEMPTS="2"
2256
+ export AGENTICDOME_AGNO_CIRCUIT_BREAKER_FAILURES="5"
2257
+ export AGENTICDOME_AGNO_AUDIT_LOGGING="true"
2258
+ export AGENTICDOME_AGNO_OTEL_ENABLED="true"
2259
+ # Optional for distributed multi-worker delegation:
2260
+ # export AGENTICDOME_REDIS_URL="redis://localhost:6379/0"
2261
+ # export AGENTICDOME_REDIS_KEY_PREFIX="AgenticDome:agno:handoff"
2262
+ # export AGENTICDOME_TOKEN_HMAC_SECRET="replace-with-secret-from-your-secret-manager"
1794
2263
  ```
1795
2264
 
1796
2265
  ### Agno Import Reference
@@ -1801,6 +2270,7 @@ from agenticdome_sdk.agno import (
1801
2270
  FirewallConfig,
1802
2271
  AgenticDomeAgnoDenied,
1803
2272
  DecisionTokenRecord,
2273
+ DecisionTokenStore,
1804
2274
  InMemoryDecisionTokenStore,
1805
2275
  RedisDecisionTokenStore,
1806
2276
  attach_firewall,
@@ -1813,9 +2283,10 @@ from agenticdome_sdk.agno import (
1813
2283
 
1814
2284
  ### Agno Accuracy and Interception Notes
1815
2285
 
1816
- - Environment configuration alone does not attach AgenticDome to Agno. You must call `attach_firewall(agent_or_team)` or assign `cybersec_pre_hook`, `cybersec_post_hook`, and `cybersec_tool_hook` to the Agno component's hooks.
2286
+ - Environment configuration alone does not attach AgenticDome to Agno. You must call `attach_firewall(agent_or_team)`, register `create_hook_bundle()`, use the middleware/plugin helper object, or assign `cybersec_pre_hook`, `cybersec_post_hook`, and `cybersec_tool_hook` to the Agno component's hooks.
1817
2287
  - Agno hosted or remote tools that execute outside your local Python process can only be protected at the local request/response boundary. The SDK cannot inspect inside a remote provider runtime.
1818
2288
  - For production teams and AgentOS deployments, configure Redis so delegation tokens are available across workers and pods.
2289
+ - Use stable `session_id`, `run_id`, or `trace_id` values in production so policy decisions, audit logs, and delegation tokens are traceable.
1819
2290
 
1820
2291
  Official references:
1821
2292
 
@@ -1824,20 +2295,22 @@ Official references:
1824
2295
 
1825
2296
 
1826
2297
 
1827
-
1828
-
1829
2298
  ## Google ADK Integration
1830
2299
 
1831
- AgenticDome provides a production Google ADK adapter for the callback boundaries ADK exposes around model calls and tool execution. This is the strongest integration point because ADK callbacks can inspect or stop execution before a model call or tool call, and can replace model or tool outputs after execution.
2300
+ AgenticDome provides a production Google ADK adapter for the lifecycle boundaries ADK exposes around agent execution, model calls, and tool execution. Register it at agent construction time with ADK callback keyword arguments, attach it to an existing agent, or expose it as a plugin-style object for applications that use ADK plugin registration.
1832
2301
 
1833
2302
  The Google ADK integration supports:
1834
2303
 
1835
2304
  - Prompt screening through `before_model`
1836
2305
  - Model output sanitization through `after_model`
1837
- - Tool argument authorization through `before_tool`
1838
- - Tool result sanitization through `after_tool`
2306
+ - Tool argument authorization, internal metadata stripping, schema validation, and sanitized-argument enforcement through `before_tool`
2307
+ - Tool result sanitization with structured JSON preservation through `after_tool`
2308
+ - Agent lifecycle audit visibility through `before_agent` and `after_agent`
1839
2309
  - Explicit local tool wrappers with `wrap_tool_handler()` and `@firewall.secure_tool(...)`
1840
- - Sync callback methods for synchronous ADK configurations and async callback methods for async runners
2310
+ - Manager-to-specialist handoff authorization with `DecisionTokenStore`, `InMemoryDecisionTokenStore`, and optional `RedisDecisionTokenStore`
2311
+ - Delegated execution verification with one-time token consumption and optional HMAC validation
2312
+ - Streaming output sanitization with a sliding review buffer
2313
+ - Local rate limits, size limits, retries/backoff, circuit breaker behavior, structured audit logs, OpenTelemetry span events, identity-rich policy context, and emergency local deny lists
1841
2314
 
1842
2315
  ### Install Google ADK Support
1843
2316
 
@@ -1847,7 +2320,7 @@ pip install "agenticdome-python-sdk[google-adk]"
1847
2320
 
1848
2321
  ### Google ADK Quickstart: Register Callbacks
1849
2322
 
1850
- Apply AgenticDome where you create the ADK agent.
2323
+ Apply AgenticDome where you create the ADK agent. `build_callback_kwargs()` returns the official callback keyword names used by `LlmAgent(...)`.
1851
2324
 
1852
2325
  ```python
1853
2326
  from google.adk.agents import LlmAgent
@@ -1859,10 +2332,7 @@ agent = LlmAgent(
1859
2332
  name="support_adk_agent",
1860
2333
  model="gemini-2.5-flash",
1861
2334
  instruction="Help support analysts safely.",
1862
- before_model_callback=firewall.before_model,
1863
- after_model_callback=firewall.after_model,
1864
- before_tool_callback=firewall.before_tool,
1865
- after_tool_callback=firewall.after_tool,
2335
+ **firewall.build_callback_kwargs(),
1866
2336
  )
1867
2337
  ```
1868
2338
 
@@ -1872,9 +2342,15 @@ If the agent object already exists, attach callbacks after construction:
1872
2342
  firewall.install_on_agent(agent)
1873
2343
  ```
1874
2344
 
2345
+ For ADK applications that centralize guardrails through plugin registration, expose the same enforcement callbacks as a plugin-style object:
2346
+
2347
+ ```python
2348
+ plugin = firewall.create_plugin()
2349
+ ```
2350
+
1875
2351
  ### Google ADK Tool Protection
1876
2352
 
1877
- Use the decorator when the function can read sensitive records, mutate systems, call SaaS APIs, write files, send messages, or trigger payments.
2353
+ Use the decorator when the function can read sensitive records, mutate systems, call SaaS APIs, write files, send messages, or trigger payments. If AgenticDome returns sanitized tool arguments, the wrapper executes the tool with the sanitized arguments and strips private `_AgenticDome_*` metadata before the handler runs.
1878
2354
 
1879
2355
  ```python
1880
2356
  @firewall.secure_tool(tool_name="crm.customer.read", tool_platform="crm")
@@ -1882,6 +2358,39 @@ def lookup_customer(tool_context, args):
1882
2358
  return crm.get_customer(args["customer_id"])
1883
2359
  ```
1884
2360
 
2361
+ Pass a Pydantic model, Pydantic v1 model, or JSON-schema-like dict to validate arguments before execution:
2362
+
2363
+ ```python
2364
+ secured_lookup = firewall.wrap_tool_handler(
2365
+ tool_name="crm.customer.read",
2366
+ tool_platform="crm",
2367
+ tool_schema={"required": ["customer_id"], "properties": {"customer_id": {"type": "string"}}},
2368
+ handler=lookup_customer,
2369
+ )
2370
+ ```
2371
+
2372
+ ### Google ADK Multi-Agent Delegation
2373
+
2374
+ Use explicit handoff authorization when a manager delegates a tool call to another ADK agent. The adapter stores a decision token against the clean target tool arguments, injects private handoff metadata into the handoff payload, and verifies delegated execution before the specialist runs the tool.
2375
+
2376
+ ```python
2377
+ record = await firewall.authorize_manager_handoff(
2378
+ source_agent_id="manager",
2379
+ target_agent_id="filesystem_specialist",
2380
+ target_tool_name="filesystem.read",
2381
+ target_tool_args={"path": "/reports/q4.txt"},
2382
+ tool_context=tool_context,
2383
+ )
2384
+
2385
+ await firewall.verify_delegated_execution(
2386
+ target_agent_id="filesystem_specialist",
2387
+ tool_name="filesystem.read",
2388
+ tool_args={"path": "/reports/q4.txt"},
2389
+ tool_context=tool_context,
2390
+ decision_token=record.decision_token,
2391
+ )
2392
+ ```
2393
+
1885
2394
  ### Google ADK Runtime Configuration
1886
2395
 
1887
2396
  ```bash
@@ -1889,19 +2398,43 @@ export AGENTICDOME_PLATFORM="google_adk"
1889
2398
  export AGENTICDOME_GOOGLE_ADK_AGENT_ID="support_adk_agent"
1890
2399
  export AGENTICDOME_SANITIZE_MODEL_OUTPUT="true"
1891
2400
  export AGENTICDOME_SANITIZE_TOOL_OUTPUT="true"
2401
+ export AGENTICDOME_PRODUCTION_MODE="true"
2402
+ export AGENTICDOME_REQUIRE_STABLE_SESSION_ID_IN_PROD="true"
2403
+ export AGENTICDOME_HANDOFF_TOKEN_TTL_S="900"
2404
+ export AGENTICDOME_GOOGLE_ADK_MAX_INPUT_CHARS="50000"
2405
+ export AGENTICDOME_GOOGLE_ADK_MAX_OUTPUT_CHARS="100000"
2406
+ export AGENTICDOME_GOOGLE_ADK_MAX_TOOL_ARG_CHARS="20000"
2407
+ export AGENTICDOME_GOOGLE_ADK_RATE_LIMIT_PER_MINUTE="120"
2408
+ export AGENTICDOME_GOOGLE_ADK_RETRY_ATTEMPTS="2"
2409
+ export AGENTICDOME_GOOGLE_ADK_CIRCUIT_BREAKER_FAILURES="5"
2410
+ export AGENTICDOME_GOOGLE_ADK_AUDIT_LOGGING="true"
2411
+ export AGENTICDOME_GOOGLE_ADK_OTEL_ENABLED="true"
2412
+ # Optional for distributed multi-worker handoff verification:
2413
+ # export AGENTICDOME_REDIS_URL="redis://localhost:6379/0"
2414
+ # export AGENTICDOME_REDIS_KEY_PREFIX="AgenticDome:google_adk:handoff"
2415
+ # export AGENTICDOME_TOKEN_HMAC_SECRET="replace-with-secret-from-your-secret-manager"
1892
2416
  ```
1893
2417
 
1894
2418
  ### Google ADK Accuracy and Interception Notes
1895
2419
 
1896
- - Environment configuration alone does not intercept ADK execution. You must register callbacks on the ADK agent or wrap local tool handlers.
2420
+ - Environment configuration alone does not intercept ADK execution. You must register callbacks on the ADK agent, register the plugin-style object where your ADK runtime supports plugins, or wrap local tool handlers.
1897
2421
  - Use async callback methods (`before_model`, `after_model`, `before_tool`, `after_tool`) when your ADK runner supports async callbacks. Use the `*_callback` sync methods only for synchronous configurations.
2422
+ - In production mode, provide stable ADK context values such as `session_id`, `run_id`, `trace_id`, `conversation_id`, or `request_id`; otherwise the adapter fails closed when `AGENTICDOME_REQUIRE_STABLE_SESSION_ID_IN_PROD=true`.
1898
2423
  - AgenticDome protects the local ADK callback boundary and returned content. It cannot inspect execution inside remote tools or services after your process hands off control.
1899
- - Use stable session IDs in ADK context/state for auditability. Set `AGENTICDOME_REQUIRE_SESSION_ID=true` when every request must be traceable.
2424
+ - Include Google Cloud identity and project context in ADK context/state when available, for example `project_id`, `service_account_email`, `principal_id`, `roles`, `scopes`, `region`, and `sensitivity_label`.
2425
+ - Use Redis and `AGENTICDOME_TOKEN_HMAC_SECRET` for multi-worker or Kubernetes deployments where handoff authorization and specialist execution can happen in different processes.
1900
2426
 
1901
2427
  ### Google ADK Import Reference
1902
2428
 
1903
2429
  ```python
1904
- from agenticdome_sdk.google_adk import AgenticDomeGoogleADKFirewall, FirewallConfig
2430
+ from agenticdome_sdk.google_adk import (
2431
+ AgenticDomeGoogleADKFirewall,
2432
+ DecisionTokenRecord,
2433
+ DecisionTokenStore,
2434
+ FirewallConfig,
2435
+ InMemoryDecisionTokenStore,
2436
+ RedisDecisionTokenStore,
2437
+ )
1905
2438
  ```
1906
2439
 
1907
2440
  ---
@@ -1917,6 +2450,11 @@ The LlamaIndex integration supports:
1917
2450
  - Tool output review before results return to the agent
1918
2451
  - Query output DLP and redaction
1919
2452
  - Retrieval-result sanitization before retrieved context enters a prompt or reaches a user
2453
+ - Query-engine and retriever wrappers for central assembly points
2454
+ - LlamaIndex node postprocessor creation for RAG context sanitization
2455
+ - Callback handler creation for global audit visibility and optional extra input blocking
2456
+ - Optional manager-to-specialist handoff authorization and decision-token verification
2457
+ - Optional Redis-backed decision token storage for multi-worker LlamaIndex deployments
1920
2458
  - Optional creation of LlamaIndex `FunctionTool` objects when LlamaIndex is installed
1921
2459
 
1922
2460
  ### Install LlamaIndex Support
@@ -1971,6 +2509,22 @@ answer = await firewall.run_query_securely(
1971
2509
  )
1972
2510
  ```
1973
2511
 
2512
+ For central assembly code, wrap query engines and retrievers before passing them to agents or workflows.
2513
+
2514
+ ```python
2515
+ secure_query_engine = firewall.wrap_query_engine(
2516
+ query_engine,
2517
+ agent_id="support_llamaindex_agent",
2518
+ session_id="sess_prod_01J4X",
2519
+ )
2520
+
2521
+ secure_retriever = firewall.wrap_retriever(
2522
+ retriever,
2523
+ agent_id="support_llamaindex_agent",
2524
+ session_id="sess_prod_01J4X",
2525
+ )
2526
+ ```
2527
+
1974
2528
  Use `sanitize_retrieval_result()` after retrievers return nodes and before retrieved text is inserted into a prompt.
1975
2529
 
1976
2530
  ```python
@@ -1981,6 +2535,55 @@ safe_nodes = await firewall.sanitize_retrieval_result(
1981
2535
  )
1982
2536
  ```
1983
2537
 
2538
+ For RAG pipelines that accept node postprocessors, create one from the firewall.
2539
+
2540
+ ```python
2541
+ node_postprocessor = firewall.create_node_postprocessor(
2542
+ agent_id="support_llamaindex_agent",
2543
+ session_id="sess_prod_01J4X",
2544
+ )
2545
+ ```
2546
+
2547
+ ### LlamaIndex Callback Visibility
2548
+
2549
+ Use callbacks for global audit visibility, incident telemetry, and optional extra blocking. Keep hard enforcement in the query, retriever, and tool wrappers.
2550
+
2551
+ ```python
2552
+ from llama_index.core import Settings
2553
+ from llama_index.core.callbacks import CallbackManager
2554
+
2555
+ handler = firewall.create_callback_handler(
2556
+ agent_id="support_llamaindex_agent",
2557
+ session_id="sess_prod_01J4X",
2558
+ )
2559
+
2560
+ Settings.callback_manager = CallbackManager([handler])
2561
+ ```
2562
+
2563
+ Set `enforce_input=True` only when you want callback query/prompt events to perform an additional synchronous input check. Wrappers remain the preferred enforcement boundary.
2564
+
2565
+ ### LlamaIndex Multi-Agent Handoffs
2566
+
2567
+ Only add handoff controls when your LlamaIndex application delegates from manager agents to specialist agents that can execute sensitive tools.
2568
+
2569
+ ```python
2570
+ await firewall.authorize_manager_handoff(
2571
+ manager_agent_id="triage_manager",
2572
+ specialist_agent_id="billing_specialist",
2573
+ tool_name="billing.refund.create",
2574
+ tool_args={"invoice_id": "inv_123", "amount": 2500},
2575
+ tool_platform="billing",
2576
+ session_id="sess_prod_01J4X",
2577
+ )
2578
+
2579
+ await firewall.verify_delegated_execution(
2580
+ specialist_agent_id="billing_specialist",
2581
+ tool_name="billing.refund.create",
2582
+ tool_args={"invoice_id": "inv_123", "amount": 2500},
2583
+ session_id="sess_prod_01J4X",
2584
+ )
2585
+ ```
2586
+
1984
2587
  ### LlamaIndex Runtime Configuration
1985
2588
 
1986
2589
  ```bash
@@ -1988,35 +2591,52 @@ export AGENTICDOME_PLATFORM="llamaindex"
1988
2591
  export AGENTICDOME_LLAMAINDEX_AGENT_ID="support_llamaindex_agent"
1989
2592
  export AGENTICDOME_SANITIZE_QUERY_OUTPUT="true"
1990
2593
  export AGENTICDOME_SANITIZE_TOOL_OUTPUT="true"
2594
+ export AGENTICDOME_HANDOFF_TOKEN_TTL_S="900"
2595
+ # Optional for distributed multi-worker handoff verification:
2596
+ # export AGENTICDOME_REDIS_URL="redis://localhost:6379/0"
2597
+ # export AGENTICDOME_REDIS_KEY_PREFIX="AgenticDome:llamaindex:handoff"
1991
2598
  ```
1992
2599
 
1993
2600
  ### LlamaIndex Accuracy and Interception Notes
1994
2601
 
1995
- - Environment configuration alone does not intercept LlamaIndex execution. You must wrap tools, query calls, query engines, retrievers, or output boundaries.
2602
+ - Environment configuration alone does not intercept LlamaIndex execution. You must wrap tools, query calls, query engines, retrievers, node postprocessors, callbacks, or output boundaries.
1996
2603
  - LlamaIndex has many integrations and provider-native tool specs. AgenticDome can protect local Python functions and local query/retrieval boundaries; remote services outside your process must be protected at their request/response boundary.
1997
- - For global behavior, place wrappers in the module where tools, query engines, and agents are assembled, not inside individual request handlers only.
2604
+ - For global behavior, place wrappers in the module where tools, query engines, retrievers, node postprocessors, callbacks, and agents are assembled, not inside individual request handlers only.
1998
2605
  - Use stable `session_id` values for auditability. Set `AGENTICDOME_REQUIRE_SESSION_ID=true` when every query/tool call must be traceable.
1999
2606
 
2000
2607
  ### LlamaIndex Import Reference
2001
2608
 
2002
2609
  ```python
2003
- from agenticdome_sdk.llamaindex import AgenticDomeLlamaIndexFirewall, FirewallConfig
2610
+ from agenticdome_sdk.llamaindex import (
2611
+ AgenticDomeLlamaIndexFirewall,
2612
+ DecisionTokenRecord,
2613
+ DecisionTokenStore,
2614
+ FirewallConfig,
2615
+ InMemoryDecisionTokenStore,
2616
+ RedisDecisionTokenStore,
2617
+ )
2004
2618
  ```
2005
2619
 
2006
2620
  ---
2007
2621
 
2008
2622
  ## AWS Bedrock Integration
2009
2623
 
2010
- AgenticDome provides a production AWS Bedrock adapter for the local Python boundaries your application controls. This integration makes sense when your service calls Bedrock Runtime directly, handles Bedrock tool-use results, implements Bedrock Agent action groups, or processes knowledge-base retrieval before the content enters a model or reaches a user.
2624
+ AgenticDome provides a production AWS Bedrock adapter for the local Python boundaries your application controls. This integration is intended for services that call Bedrock Runtime directly, stream model responses, invoke Bedrock Agents, implement action-group Lambda handlers, execute local tool-use results, or process knowledge-base retrieval before content enters a model or reaches a user.
2011
2625
 
2012
2626
  The Bedrock integration supports:
2013
2627
 
2014
- - Prompt screening before `bedrock-runtime.converse(...)` or `invoke_model(...)`
2628
+ - Prompt screening before `bedrock-runtime.converse(...)`, `converse_stream(...)`, `invoke_model(...)`, `invoke_model_with_response_stream(...)`, and `bedrock-agent-runtime.invoke_agent(...)`
2015
2629
  - Model output DLP and redaction before responses leave your application
2630
+ - Streaming response sanitization for ConverseStream and InvokeModelWithResponseStream events
2631
+ - Provider-specific prompt/response parsing for common Claude, Titan, Llama, Mistral, and Converse payload shapes
2016
2632
  - Local tool-use and Bedrock Agent action-group authorization
2017
- - Tool/action output review before returning tool results to Bedrock or the user
2018
- - Knowledge-base and retrieval-result sanitization
2019
- - Fail-closed or fail-open behavior controlled by `AGENTICDOME_FAIL_CLOSED`
2633
+ - Sanitized tool arguments, private `_AgenticDome_*` metadata stripping, and optional schema validation
2634
+ - Tool/action output review before returning results to Bedrock or the user
2635
+ - Knowledge-base retrieval sanitization at the individual retrieval-node level
2636
+ - Production mode with stable session ID requirements
2637
+ - AWS account, region, role, principal, Bedrock agent, and knowledge-base context in policy decisions
2638
+ - Local size limits, rate limits, retries/backoff, circuit breaker behavior, structured audit logs, OpenTelemetry span events, and emergency local deny lists
2639
+ - Optional manager-to-specialist handoff authorization with in-memory or Redis-backed decision-token storage and HMAC validation
2020
2640
 
2021
2641
  ### Install AWS Bedrock Support
2022
2642
 
@@ -2024,7 +2644,7 @@ The Bedrock integration supports:
2024
2644
  pip install "agenticdome-python-sdk[bedrock]"
2025
2645
  ```
2026
2646
 
2027
- The adapter accepts any boto3-compatible Bedrock Runtime client. It does not import boto3 at module import time, so tests and custom clients can use the same wrapper.
2647
+ The adapter accepts any boto3-compatible Bedrock Runtime or Bedrock Agent Runtime client. It does not import boto3 at module import time, so tests and custom clients can use the same wrapper.
2028
2648
 
2029
2649
  ### Bedrock Quickstart: Secure Converse
2030
2650
 
@@ -2057,9 +2677,22 @@ response = await firewall.converse_securely(
2057
2677
  messages/system -> prompt screen -> Bedrock Converse -> output review -> sanitized response
2058
2678
  ```
2059
2679
 
2680
+ For streaming Converse responses:
2681
+
2682
+ ```python
2683
+ async for event in firewall.converse_stream_securely(
2684
+ bedrock_runtime_client=bedrock,
2685
+ model_id="anthropic.claude-3-5-sonnet-20241022-v2:0",
2686
+ messages=messages,
2687
+ agent_id="support_bedrock_agent",
2688
+ session_id="sess_prod_01J4X",
2689
+ ):
2690
+ yield event
2691
+ ```
2692
+
2060
2693
  ### Bedrock Quickstart: Secure InvokeModel
2061
2694
 
2062
- Use `invoke_model_securely()` for provider-specific payloads such as Titan, Claude, Llama, or other model-native request bodies.
2695
+ Use `invoke_model_securely()` for provider-specific payloads such as Titan, Claude, Llama, Mistral, or other model-native request bodies.
2063
2696
 
2064
2697
  ```python
2065
2698
  import json
@@ -2075,9 +2708,48 @@ response = await firewall.invoke_model_securely(
2075
2708
  )
2076
2709
  ```
2077
2710
 
2078
- The adapter extracts prompt text from common Bedrock payload shapes including `inputText`, `prompt`, `messages`, `contents`, `system`, and provider-native JSON bodies. If the model response uses common text fields such as `outputText`, `completion`, `generation`, `answer`, or Converse `output.message.content[].text`, sanitized text is written back into the response copy.
2711
+ For streamed provider-native responses:
2712
+
2713
+ ```python
2714
+ async for event in firewall.invoke_model_with_response_stream_securely(
2715
+ bedrock_runtime_client=bedrock,
2716
+ model_id="amazon.titan-text-express-v1",
2717
+ body=json.dumps({"inputText": "Draft a customer email."}),
2718
+ agent_id="support_bedrock_agent",
2719
+ session_id="sess_prod_01J4X",
2720
+ ):
2721
+ yield event
2722
+ ```
2723
+
2724
+ The adapter extracts prompt text from common Bedrock payload shapes including `inputText`, `prompt`, `messages`, `contents`, `system`, Claude `anthropic_version` messages, Llama/Mistral prompts, and provider-native JSON bodies. If the model response uses common text fields such as `outputText`, `completion`, `generation`, `answer`, `text`, `generated_text`, or Converse `output.message.content[].text`, sanitized text is written back into the response copy.
2725
+
2726
+ ### Bedrock Agents and Action Groups
2079
2727
 
2080
- ### Bedrock Tool / Action Group Protection
2728
+ Use `invoke_agent_securely()` around Bedrock Agent Runtime calls:
2729
+
2730
+ ```python
2731
+ agent_runtime = boto3.client("bedrock-agent-runtime", region_name="us-east-1")
2732
+
2733
+ response = await firewall.invoke_agent_securely(
2734
+ bedrock_agent_runtime_client=agent_runtime,
2735
+ agent_id="BEDROCK_AGENT_ID",
2736
+ agent_alias_id="BEDROCK_AGENT_ALIAS_ID",
2737
+ session_id="sess_prod_01J4X",
2738
+ input_text="Find the customer refund policy.",
2739
+ source_agent_id="support_bedrock_agent",
2740
+ )
2741
+ ```
2742
+
2743
+ Wrap action-group Lambda handlers so tool authorization and output review happen before the Lambda result is returned to Bedrock:
2744
+
2745
+ ```python
2746
+ def lambda_handler(event, context):
2747
+ return perform_action(event)
2748
+
2749
+ secure_lambda_handler = firewall.wrap_action_group_lambda(handler=lambda_handler)
2750
+ ```
2751
+
2752
+ ### Bedrock Tool Protection
2081
2753
 
2082
2754
  Wrap every local function that performs side effects, reads sensitive records, calls SaaS APIs, writes files, sends messages, processes payments, or handles Bedrock Agent action-group work.
2083
2755
 
@@ -2091,13 +2763,14 @@ def lookup_customer(ctx, args):
2091
2763
  return crm.get_customer(args["customer_id"])
2092
2764
  ```
2093
2765
 
2094
- For explicit wrapping:
2766
+ For explicit wrapping with schema validation:
2095
2767
 
2096
2768
  ```python
2097
2769
  secure_refund = firewall.wrap_tool_handler(
2098
2770
  tool_name="payments.refund.create",
2099
2771
  tool_platform="payments",
2100
2772
  handler=create_refund,
2773
+ tool_schema={"required": ["customer_id", "amount"], "properties": {"customer_id": {"type": "string"}, "amount": {"type": "number"}}},
2101
2774
  )
2102
2775
 
2103
2776
  result = await secure_refund(
@@ -2106,9 +2779,31 @@ result = await secure_refund(
2106
2779
  )
2107
2780
  ```
2108
2781
 
2782
+ ### Bedrock Multi-Agent Delegation
2783
+
2784
+ Use explicit handoff authorization when a manager delegates a sensitive Bedrock tool/action to a specialist agent. Redis is recommended when authorization and execution can happen in different workers or pods.
2785
+
2786
+ ```python
2787
+ record = await firewall.authorize_manager_handoff(
2788
+ source_agent_id="manager",
2789
+ target_agent_id="refund_specialist",
2790
+ target_tool_name="payments.refund.create",
2791
+ target_tool_args={"customer_id": "cust_123", "amount": 250},
2792
+ session_id="sess_prod_01J4X",
2793
+ )
2794
+
2795
+ await firewall.verify_delegated_execution(
2796
+ target_agent_id="refund_specialist",
2797
+ tool_name="payments.refund.create",
2798
+ tool_args={"customer_id": "cust_123", "amount": 250},
2799
+ session_id="sess_prod_01J4X",
2800
+ decision_token=record.decision_token,
2801
+ )
2802
+ ```
2803
+
2109
2804
  ### Bedrock Retrieval Sanitization
2110
2805
 
2111
- Use `sanitize_retrieval_result()` after knowledge-base retrieval and before retrieved content is placed into a prompt or returned to a user.
2806
+ Use `sanitize_retrieval_result()` after knowledge-base retrieval and before retrieved content is placed into a prompt or returned to a user. For Bedrock Knowledge Bases response shapes, each `retrievalResults[].content.text` node is sanitized independently so metadata and ranking structure are preserved.
2112
2807
 
2113
2808
  ```python
2114
2809
  safe_retrieval = await firewall.sanitize_retrieval_result(
@@ -2127,19 +2822,43 @@ export AGENTICDOME_BEDROCK_AGENT_ID="support_bedrock_agent"
2127
2822
  export AGENTICDOME_BEDROCK_MODEL_ID="anthropic.claude-3-5-sonnet-20241022-v2:0"
2128
2823
  export AGENTICDOME_SANITIZE_MODEL_OUTPUT="true"
2129
2824
  export AGENTICDOME_SANITIZE_TOOL_OUTPUT="true"
2825
+ export AGENTICDOME_PRODUCTION_MODE="true"
2826
+ export AGENTICDOME_REQUIRE_STABLE_SESSION_ID_IN_PROD="true"
2827
+ export AGENTICDOME_AWS_ACCOUNT_ID="123456789012"
2828
+ export AGENTICDOME_AWS_REGION="us-east-1"
2829
+ export AGENTICDOME_BEDROCK_MAX_INPUT_CHARS="50000"
2830
+ export AGENTICDOME_BEDROCK_MAX_OUTPUT_CHARS="100000"
2831
+ export AGENTICDOME_BEDROCK_MAX_TOOL_ARG_CHARS="20000"
2832
+ export AGENTICDOME_BEDROCK_RATE_LIMIT_PER_MINUTE="120"
2833
+ export AGENTICDOME_BEDROCK_RETRY_ATTEMPTS="2"
2834
+ export AGENTICDOME_BEDROCK_CIRCUIT_BREAKER_FAILURES="5"
2835
+ export AGENTICDOME_BEDROCK_AUDIT_LOGGING="true"
2836
+ export AGENTICDOME_BEDROCK_OTEL_ENABLED="true"
2837
+ # Optional for distributed multi-worker handoff verification:
2838
+ # export AGENTICDOME_REDIS_URL="redis://localhost:6379/0"
2839
+ # export AGENTICDOME_REDIS_KEY_PREFIX="AgenticDome:aws_bedrock:handoff"
2840
+ # export AGENTICDOME_TOKEN_HMAC_SECRET="replace-with-secret-from-your-secret-manager"
2130
2841
  ```
2131
2842
 
2132
2843
  ### Bedrock Accuracy and Interception Notes
2133
2844
 
2134
- - Environment configuration alone does not intercept Bedrock calls. You must wrap the code path that calls `converse(...)`, `invoke_model(...)`, local tool handlers, action-group handlers, or retrieval handlers.
2845
+ - Environment configuration alone does not intercept Bedrock calls. You must wrap the code path that calls `converse(...)`, `converse_stream(...)`, `invoke_model(...)`, `invoke_model_with_response_stream(...)`, `invoke_agent(...)`, local tool handlers, action-group handlers, or retrieval handlers.
2135
2846
  - AgenticDome protects the local application boundary and returned content. It cannot inspect execution inside AWS-managed Bedrock services after your request has been sent.
2136
- - Use stable `session_id` values for auditability. Set `AGENTICDOME_REQUIRE_SESSION_ID=true` when every model or tool call must be traceable.
2847
+ - Use stable `session_id` values for auditability. Set `AGENTICDOME_PRODUCTION_MODE=true` and `AGENTICDOME_REQUIRE_STABLE_SESSION_ID_IN_PROD=true` when every model, agent, retrieval, or tool call must be traceable.
2137
2848
  - Bedrock provider-native payloads vary by model. The adapter extracts common prompt and response fields and falls back to serialized JSON review for unknown shapes.
2849
+ - Include AWS identity and resource context when available: account ID, region, principal ARN, role ARN, Bedrock agent ID, agent alias ID, knowledge-base ID, and sensitivity labels.
2138
2850
 
2139
2851
  ### Bedrock Import Reference
2140
2852
 
2141
2853
  ```python
2142
- from agenticdome_sdk.aws_bedrock import AgenticDomeAWSBedrockFirewall, FirewallConfig
2854
+ from agenticdome_sdk.aws_bedrock import (
2855
+ AgenticDomeAWSBedrockFirewall,
2856
+ DecisionTokenRecord,
2857
+ DecisionTokenStore,
2858
+ FirewallConfig,
2859
+ InMemoryDecisionTokenStore,
2860
+ RedisDecisionTokenStore,
2861
+ )
2143
2862
  ```
2144
2863
 
2145
2864
  ---
@@ -2152,9 +2871,16 @@ The MCP integration supports:
2152
2871
 
2153
2872
  - Optional upstream prompt screening from host context
2154
2873
  - MCP `tools/call` authorization through `mcp_guardrail_validate()`
2874
+ - Authorization for `tools/list`, `resources/list`, `resources/read`, `prompts/list`, `prompts/get`, and `sampling/createMessage`
2875
+ - `tools/list` response filtering so low-privilege agents do not see tools they cannot use
2876
+ - Resource, prompt, sampling, tool, and streaming-output sanitization
2155
2877
  - Delegated decision-token verification when handoff metadata is present
2878
+ - Manager-to-MCP handoff authorization with in-memory or Redis-backed decision token storage
2879
+ - Per-MCP-server policy context such as server ID, URL, vendor, and trust level
2880
+ - Sanitized tool argument forwarding when AgenticDome returns safe replacement arguments
2881
+ - Local output/argument size limits, rate limiting, and audit logging
2156
2882
  - Internal `_AgenticDome_*` metadata stripping before forwarding to third-party MCP servers
2157
- - Mesh output sanitization for common MCP result shapes such as `content[].text`, top-level `text`, lists, and serialized structured results
2883
+ - Mesh output sanitization for common MCP result shapes such as `content[].text`, prompt messages, top-level `text`, lists, and serialized structured results
2158
2884
  - Fail-closed or fail-open behavior controlled by `AGENTICDOME_FAIL_CLOSED`
2159
2885
 
2160
2886
  ### Install MCP Host Support
@@ -2190,7 +2916,7 @@ async def handle_mcp_request(request: dict, user_prompt: str, session_id: str) -
2190
2916
  `forward_with_firewall()` performs the full host-boundary flow:
2191
2917
 
2192
2918
  ```text
2193
- JSON-RPC request -> upstream prompt screen -> delegation token verification -> tools/call authorization -> third-party MCP server -> result sanitization -> client
2919
+ JSON-RPC request -> rate limit / upstream prompt screen -> method authorization -> optional delegation-token verification -> third-party MCP server -> list filtering / result sanitization -> client
2194
2920
  ```
2195
2921
 
2196
2922
  ### MCP Quickstart: Preflight Only
@@ -2221,7 +2947,7 @@ return response
2221
2947
 
2222
2948
  ### MCP Delegated Execution
2223
2949
 
2224
- If a manager agent authorizes a delegated MCP tool call, pass the decision token and source agent ID as private MCP arguments or in host context. The adapter verifies the token and removes private metadata before forwarding the request downstream.
2950
+ If another framework or orchestrator already issued a decision token, pass the token and source agent ID as private MCP arguments or in host context. The adapter verifies the token and removes private metadata before forwarding the request downstream.
2225
2951
 
2226
2952
  ```python
2227
2953
  request = {
@@ -2246,29 +2972,62 @@ The third-party MCP server receives only the business arguments after preflight
2246
2972
  {"customer_id": "cust_123", "amount": 250}
2247
2973
  ```
2248
2974
 
2975
+ If the MCP gateway itself owns manager-to-specialist delegation, authorize the handoff first. The issued token is stored in the configured token store and consumed when the specialist MCP execution reaches the gateway.
2976
+
2977
+ ```python
2978
+ await firewall.authorize_manager_handoff(
2979
+ manager_agent_id="support_manager",
2980
+ target_agent_id="payments_mcp_worker",
2981
+ tool_name="payments.refund.create",
2982
+ tool_args={"customer_id": "cust_123", "amount": 250},
2983
+ context={"session_id": "sess_prod_01J4X"},
2984
+ tool_platform="payments_mcp_server",
2985
+ )
2986
+ ```
2987
+
2249
2988
  ### MCP Runtime Configuration
2250
2989
 
2251
2990
  ```bash
2252
2991
  export AGENTICDOME_PLATFORM="mcp"
2253
2992
  export AGENTICDOME_MCP_HOST_ID="enterprise_mcp_gateway"
2254
2993
  export AGENTICDOME_MCP_TOOL_PLATFORM="third_party_mcp_server"
2994
+ export AGENTICDOME_MCP_SERVER_ID="github-mcp"
2995
+ export AGENTICDOME_MCP_SERVER_URL="https://mcp.github.internal"
2996
+ export AGENTICDOME_MCP_SERVER_TRUST_LEVEL="internal"
2255
2997
  export AGENTICDOME_SANITIZE_TOOL_OUTPUT="true"
2998
+ export AGENTICDOME_SANITIZE_RESOURCE_OUTPUT="true"
2999
+ export AGENTICDOME_SANITIZE_PROMPT_OUTPUT="true"
3000
+ export AGENTICDOME_SANITIZE_STREAMING_OUTPUT="true"
2256
3001
  export AGENTICDOME_VERIFY_DECISION_TOKENS="true"
3002
+ export AGENTICDOME_HANDOFF_TOKEN_TTL_S="900"
2257
3003
  export AGENTICDOME_SCREEN_UPSTREAM_PROMPT="true"
3004
+ export AGENTICDOME_MCP_MAX_OUTPUT_CHARS="100000"
3005
+ export AGENTICDOME_MCP_MAX_TOOL_ARG_CHARS="20000"
3006
+ export AGENTICDOME_MCP_RATE_LIMIT_PER_MINUTE="0"
3007
+ # Optional for multi-worker gateways:
3008
+ # export AGENTICDOME_REDIS_URL="redis://localhost:6379/0"
3009
+ # export AGENTICDOME_REDIS_KEY_PREFIX="AgenticDome:mcp:handoff"
2258
3010
  ```
2259
3011
 
2260
3012
  ### MCP Accuracy and Interception Notes
2261
3013
 
2262
3014
  - Environment configuration alone does not intercept MCP traffic. You must call `preflight_request()` or `forward_with_firewall()` in the host, gateway, proxy, or router that forwards JSON-RPC requests.
2263
- - The adapter protects `tools/call`. Non-tool JSON-RPC methods pass through unchanged by default.
2264
- - AgenticDome can protect the local host boundary and returned result, but it cannot inspect code running inside a remote third-party MCP server you do not control.
3015
+ - The adapter protects `tools/call` and can also guard `tools/list`, `resources/list`, `resources/read`, `prompts/list`, `prompts/get`, and `sampling/createMessage`. Disable individual enterprise protections with the corresponding `AGENTICDOME_MCP_PROTECT_*` setting when a simple host needs passthrough behavior.
3016
+ - AgenticDome can protect the local host boundary and returned result, but it cannot inspect code running inside a remote third-party MCP server you do not control. Pass `mcp_server_id`, `mcp_server_url`, `mcp_server_vendor`, and trust metadata in `context` for per-server policy decisions.
2265
3017
  - Use stable `session_id` values for auditability. Set `AGENTICDOME_REQUIRE_SESSION_ID=true` when every host request should be traceable.
2266
3018
  - For delegated MCP execution, include both `_AgenticDome_decision_token` and `_AgenticDome_source_agent_id`; partial handoff metadata is blocked.
2267
3019
 
2268
3020
  ### MCP Import Reference
2269
3021
 
2270
3022
  ```python
2271
- from agenticdome_sdk.mcp_host import AgenticDomeMCPHostFirewall, FirewallConfig
3023
+ from agenticdome_sdk.mcp_host import (
3024
+ AgenticDomeMCPHostFirewall,
3025
+ DecisionTokenRecord,
3026
+ DecisionTokenStore,
3027
+ FirewallConfig,
3028
+ InMemoryDecisionTokenStore,
3029
+ RedisDecisionTokenStore,
3030
+ )
2272
3031
  ```
2273
3032
 
2274
3033
  ---
@@ -2548,7 +3307,13 @@ from agenticdome_sdk.microsoft_agent_framework import AgenticDomeMicrosoftAgentF
2548
3307
  Microsoft AI Foundry firewall:
2549
3308
 
2550
3309
  ```python
2551
- from agenticdome_sdk.microsoft_ai_foundry import AgenticDomeMicrosoftAIFoundryFirewall, FirewallConfig
3310
+ from agenticdome_sdk.microsoft_ai_foundry import (
3311
+ AgenticDomeMicrosoftAIFoundryFirewall,
3312
+ FirewallConfig,
3313
+ DecisionTokenStore,
3314
+ InMemoryDecisionTokenStore,
3315
+ RedisDecisionTokenStore,
3316
+ )
2552
3317
  ```
2553
3318
 
2554
3319
  Agno firewall: