From 92ec42de6ea49d05aa0eca4c429ac4a11d6e6426 Mon Sep 17 00:00:00 2001 From: george larson Date: Thu, 20 Aug 2026 10:06:11 -0400 Subject: [PATCH] docs(sdk): document AgentContext.disabled_agents deny-list Companion to OpenHands/software-agent-sdk#4557: per-conversation sub-agent deny-list, enforced at spawn time by the task and delegate tools. Co-authored-by: openhands --- sdk/guides/agent-file-based.mdx | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/sdk/guides/agent-file-based.mdx b/sdk/guides/agent-file-based.mdx index 8be696755..1ad60e418 100644 --- a/sdk/guides/agent-file-based.mdx +++ b/sdk/guides/agent-file-based.mdx @@ -268,6 +268,27 @@ conversation = Conversation( To learn more about agent delegation, follow our [comprehensive guide](/sdk/guides/task-tool-set). +## Disabling Sub-Agents per Conversation + +`AgentContext.disabled_agents` is a per-conversation deny-list of sub-agent names, mirroring the `disabled_skills` model for skills. When the task tool or the delegate tool is asked to spawn a listed agent, the spawn is refused and the calling LLM receives a tool error naming the disabled agent, so it can pick another type or do the work itself. + +```python icon="python" +from openhands.sdk import Agent, AgentContext, Tool +from openhands.tools.task import TaskToolSet + +main_agent = Agent( + llm=llm, + tools=[Tool(name=TaskToolSet.name)], + agent_context=AgentContext(disabled_agents=["code-explorer"]), +) +``` + +Enforcement happens at spawn time, not registration time: the sub-agent registry is process-global and shared across conversations on the agent server, so unregistering an agent would remove it for every conversation in the process. A listed name that is not registered is a harmless no-op, and the default empty list disables nothing. + + +`disabled_agents` rides the standard `AgentContext` plumbing, so server and frontend integrations can set it per conversation through the start-conversation settings payload (`agent_settings.agent_context.disabled_agents`). + + ## Example Agent Files ### Code Reviewer