> ## Documentation Index
> Fetch the complete documentation index at: https://silmaril.security/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Deep Agents

> Protect root agents, tools, and subagents in TypeScript or Python.

## Before you begin

Initialize the [TypeScript](https://silmaril.security/docs/sdk/typescript.md#initialize) or [Python](https://silmaril.security/docs/sdk/python.md#initialize) client as `fw`. Supply your configured chat `model` and `tools`.

The examples below require **TypeScript SDK 0.8.2 or later** or **Python SDK 0.8.1 or later**. Silmaril uses the native LangGraph `configurable.thread_id` from each invocation automatically.

TypeScript SDK 0.9.1 qualifies Deep Agents `>=1.16.0 <1.17.0`. Python SDK
0.9.1 qualifies `deepagents >=0.7.30 <0.8` on Python 3.11 through 3.15 with
`langchain-core >=1.3.3 <2`; its Deep Agents extra does not install Deep Agents
on Python 3.10.

The TypeScript adapter resolves released profiles for string model specs. For
model objects in the qualified 1.16.x interval, it uses known `getName()`
provider mappings, `ConfigurableModel._defaultConfig`, `model_name` or
`modelName`, then exact provider/model and provider fallback. Unknown models
with no recognized hints use the empty profile; malformed hints fail instead
of silently dropping profile protection. The adapter does not import Deep
Agents internals or modify its global profile registry.

Profile-disabled or customized general-purpose subagents, inherited tools and
skills, tool prototypes, exclusions, and matching static middleware overrides
are preserved. Novel root middleware remains root-only. A profile
`extraMiddleware` factory combined with custom root middleware is rejected
because its named overrides cannot be preserved statically. The qualified
1.16.x profile API has no rename field.

The Python adapter preserves the released 0.7.x profile contract. Unsupported
combinations fail with a compatibility error: runtime-registered string
profiles with root prompt, tool, or middleware customization require a
pre-built model or general-purpose-only customization; a general-purpose
system prompt cannot be combined with a base system prompt; and an
`extra_middleware` factory cannot be combined with custom root middleware.
These 0.9.1 profile changes do not broaden the remote-subagent guarantees
documented below, which remain the 0.9.0 functionality boundary.

Choose Shadow or Warn explicitly for observation. Effective Block mode replaces denied tool interactions and model content with safe messages.

Classification errors allow execution by default, except for `ReviewCompatibilityError`. A missing or mismatched backend acknowledgement of an explicit `review` choice always fails the call, even with fail-open enabled. Set `failOpen: false` in TypeScript or `fail_open: False` in Python to propagate other classification errors too. See [review depth](https://silmaril.security/docs/guides/review-depth.md) for backend compatibility requirements.

## Create a protected agent

Deep Agents creates its own subagent graphs. Use the protected constructor to
cover the root, its general-purpose subagent, and declarative subagents. In the
examples below, create one reusable agent and pass the application's normal
thread ID when invoking it. A checkpointer maintains conversation state between
turns; the in-memory checkpointers shown here are for local development.

> [tab] TypeScript
>
> ```bash theme={"theme":"github-light-default"}
> npm install @silmaril-security/sdk@0.10.0 deepagents langchain @langchain/core @langchain/langgraph
> ```
>
> ```typescript theme={"theme":"github-light-default"}
> import { MemorySaver } from "@langchain/langgraph"
> import { createProtectedDeepAgent } from "@silmaril-security/sdk/adapters/deepagents"
>
> const agent = createProtectedDeepAgent(fw, {
>   model,
>   tools,
>   subagents: [{ name: "research", description: "Research safely" }],
>   checkpointer: new MemorySaver(),
> })
>
> const configA = { configurable: { thread_id: "conversation-a" } }
> await agent.invoke(
>   { messages: [{ role: "user", content: "Research Kafka." }] },
>   configA,
> )
> // Same agent and thread: continue the existing conversation.
> await agent.invoke(
>   { messages: [{ role: "user", content: "Compare it with Redis Streams." }] },
>   configA,
> )
> // Same agent, different thread: a separate conversation.
> await agent.invoke(
>   { messages: [{ role: "user", content: "Explain PostgreSQL indexes." }] },
>   { configurable: { thread_id: "conversation-b" } },
> )
> ```
>
> For a compiled subagent, use the verified factory before creating the parent:
>
> ```typescript theme={"theme":"github-light-default"}
> import { createProtectedCompiledSubagent } from "@silmaril-security/sdk/adapters/deepagents"
>
> const review = createProtectedCompiledSubagent(fw, {
>   name: "review", description: "Review results", model,
> })
> const agent = createProtectedDeepAgent(fw, {
>   model, protectedCompiledSubagents: [review],
> })
> ```

> [tab] Python
>
> Python DeepAgents requires **Python 3.11 or later**. The base Python SDK also supports Python 3.10, but its DeepAgents extra does not.
>
> ```bash theme={"theme":"github-light-default"}
> pip install "silmaril-security-sdk[deepagents]==0.10.0"
> ```
>
> ```python theme={"theme":"github-light-default"}
> from langgraph.checkpoint.memory import InMemorySaver
> from silmaril_security.sdk.deepagents import create_protected_deep_agent
>
> agent = create_protected_deep_agent(
>     fw, model=model, tools=tools,
>     subagents=[{"name": "research", "description": "Research safely"}],
>     checkpointer=InMemorySaver(),
> )
>
> config_a = {"configurable": {"thread_id": "conversation-a"}}
> agent.invoke(
>     {"messages": [{"role": "user", "content": "Research Kafka."}]},
>     config=config_a,
> )
> # Same agent and thread: continue the existing conversation.
> agent.invoke(
>     {"messages": [{"role": "user", "content": "Compare it with Redis Streams."}]},
>     config=config_a,
> )
> # Same agent, different thread: a separate conversation.
> agent.invoke(
>     {"messages": [{"role": "user", "content": "Explain PostgreSQL indexes."}]},
>     config={"configurable": {"thread_id": "conversation-b"}},
> )
> ```
>
> For a compiled subagent, use the verified factory before creating the parent:
>
> ```python theme={"theme":"github-light-default"}
> from silmaril_security.sdk.deepagents import create_protected_compiled_subagent
>
> review = create_protected_compiled_subagent(
>     fw, name="review", description="Review results", model=model,
> )
> agent = create_protected_deep_agent(
>     fw, model=model, protected_compiled_subagents=[review],
> )
> ```

For a compiled subagent, use `createProtectedCompiledSubagent` in TypeScript or
`create_protected_compiled_subagent` in Python. These helpers install Silmaril
middleware before compiling the graph. Pass the returned spec through
`protectedCompiledSubagents` or `protected_compiled_subagents`, respectively.
The parent constructor verifies the exact graph and Firewall client and rejects
an arbitrary compiled runnable. Root custom middleware does not automatically
reach every subagent. Review compatibility errors always propagate; other
classification errors allow execution by default. Set
`silmaril: { failOpen: false }` in TypeScript or
`middleware_options={"fail_open": False}` in Python to propagate those other
errors too.

The middleware checks user input before model use, tool calls before execution,
tool results before the next model call, and non-streamed model output before
the graph consumes it. In Block mode, denied tool calls and results become a
fixed safe tool message with the original call ID. The agent may choose an
allowed alternative. Repeated denials end with a fixed safe response. Denied
model output is replaced before it enters graph messages. Shadow and Warn
report decisions without replacing content. From SDK 0.10.0, Shadow mode
classifies in the background, so `onClassify` or `on_classify` runs after the
boundary continues; set `failOpen: false` or `fail_open: False` to keep those
checks inline. Already emitted streaming text cannot be recalled.

TypeScript SDK 0.7.3 and later apply the repeated-denial cap only in effective Block
mode. Genuine earlier Block denials remain counted, but do not halt Warn or
Shadow continuation.

## Classify input in parallel

From SDK 0.10.0, set `parallel` so the user-input check runs while the model
call is in flight instead of ahead of it.

> [tab] TypeScript
>
> ```typescript theme={"theme":"github-light-default"}
> const parallelAgent = createProtectedDeepAgent(fw, {
>   model,
>   tools,
>   silmaril: { parallel: true },
> })
> ```

> [tab] Python
>
> ```python theme={"theme":"github-light-default"}
> parallel_agent = create_protected_deep_agent(
>     fw, model=model, tools=tools,
>     middleware_options={"parallel": True},
> )
> ```

A blocked input replaces the model response with the fixed safe message. Async
Python execution also cancels the model call; TypeScript and synchronous
Python discard its response. The model-output check still runs before the
graph consumes the response.

Tool calls and tool results keep waiting for their verdict, because a denied
result is replaced before it enters agent state. Once the repeated-denial cap
is reached, the input check waits for its verdict again so the cap is decided
before the model runs. In Python, existing Silmaril middleware on the same
stack must use the same `parallel` setting.

## Thread identity and migration

The same agent or middleware instance can serve multiple threads, including
concurrent threads. Silmaril resolves identity for each invocation and sends the
native ID as `metadata.conversationId`. Root and nested subagents that share the
native thread use that ID. A separately executed graph uses its own native
thread ID; agent names and checkpoint namespaces do not create new conversation
IDs.

Reuse the thread ID for later turns or checkpoint resume. Use a different native
thread ID for a separate conversation. Without a native thread ID, checks run as
independent events: Silmaril omits `metadata.conversationId` and does not generate
one from an agent instance, run ID, or request ID. A checkpointer may separately
require a native thread ID to save state. Run and request IDs remain separate
correlation identifiers.

SDK 0.8.0 removes constructor-level `conversationId` (TypeScript) and
`conversation_id` (Python) options from the agent integrations. Remove these
options from `silmaril` or `middleware_options`, respectively, and use the
framework's invocation config as shown above. Calls that still supply removed
options are rejected with a migration error. Direct SDK `classify()` calls still
accept caller-owned `metadata.conversationId`; their API is unchanged.

## Verify coverage

[Verify the integration](https://silmaril.security/docs/start/verify.md) on the root and each subagent. Reuse one agent across two native threads and confirm that checks are grouped under the matching thread IDs. Continue a thread and confirm its later checks keep the same identity. Confirm that tool checks happen before execution. Buffer streaming text when delivery requires a completed output verdict.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.