Skip to main content

Before you begin

Initialize the TypeScript or Python 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 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.
For a compiled subagent, use the verified factory before creating the parent:
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.
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 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.