Before you begin
Initialize the TypeScript or Python client asfw. 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.- TypeScript
- Python
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, setparallel so the user-input check runs while the model
call is in flight instead of ahead of it.
- TypeScript
- Python
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 asmetadata.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.