> ## 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.

# Events and conversations

> Label execution boundaries and preserve ordered context across an agent sequence.

Send one complete event at each boundary you protect. Apply its verdict before the application consumes that event or performs the proposed action.

## Choose a hook

| Boundary | API hook | Check before |
| - | - | - |
| User input | `user_input` | The model consumes the input |
| Tool call | `tool_call` | The tool executes |
| Tool response | `tool_response` | The model consumes the tool output |
| Model output | `llm_output` | The application returns or consumes generated content |

Supply the tool name for tool calls and tool responses. SDKs expose typed hook labels for these values.

## Preserve conversation order

Use a caller-owned `metadata.conversationId` for one agent sequence. Send ordered individual `classify()` calls with that ID, waiting for and handling each verdict or error before sending the next event.

`protect()` in the [Python](https://silmaril.security/docs/sdk/python.md#classify-in-parallel) and [TypeScript](https://silmaril.security/docs/sdk/typescript.md#classify-in-parallel) SDKs and the `parallel` option on the [LangChain](https://silmaril.security/docs/sdk/langchain.md#run-checks-in-parallel), [Deep Agents](https://silmaril.security/docs/integrations/deep-agents.md#classify-input-in-parallel), and [Vercel AI SDK](https://silmaril.security/docs/sdk/vercel-ai.md#run-the-input-check-in-parallel) integrations start a check without waiting for it. The SDK sends checks that share a conversation ID in the order they started, so those paths preserve the sequence for you.

Each SDK event also receives a `metadata.silmaril.request_id`. Use the request ID to correlate a classification and the conversation ID to group the sequence. Let the SDK manage request identity.

Use the client initialized in your SDK's setup guide. In Block mode, Python, Go, and Java stop blocked events with an exception or error. TypeScript returns the verdict for your application to enforce.

```typescript TypeScript theme={"theme":"github-light-default"}
import { HookLabel } from "@silmaril-security/sdk"

const metadata = { conversationId: "build-repair-123" }

const inputVerdict = await fw.classify(userInput, {
  hook: HookLabel.USER_INPUT,
  metadata,
  mode: "block",
})

if (inputVerdict.prediction === "MALICIOUS" || inputVerdict.governance?.action === "block") {
  throw new Error("Input blocked by Firewall")
}
```

```python Python theme={"theme":"github-light-default"}
from silmaril_security.sdk import HookLabel

metadata = {"conversationId": "build-repair-123"}

input_verdict = fw.classify(
    user_input,
    hook=HookLabel.USER_INPUT,
    metadata=metadata,
    mode="block",
)
```

```go Go theme={"theme":"github-light-default"}
metadata := firewall.ClassificationMetadata{"conversationId": "build-repair-123"}

inputVerdict, err := fw.Classify(ctx, userInput,
    firewall.WithHook(firewall.HookUserInput),
    firewall.WithMetadata(metadata),
    firewall.WithMode(firewall.ModeBlock),
)
if err != nil {
    return err // Stop this sequence on a block or request failure.
}
log.Printf("prediction=%s", inputVerdict.Prediction)
```

```java Java theme={"theme":"github-light-default"}
import java.util.Map;
import dev.silmaril.security.ClassifyOptions;
import dev.silmaril.security.FirewallMode;
import dev.silmaril.security.HookLabel;

var metadata = Map.<String, Object>of("conversationId", "build-repair-123");

var inputVerdict = fw.classify(
    userInput,
    ClassifyOptions.builder()
        .hook(HookLabel.USER_INPUT)
        .metadata(metadata)
        .mode(FirewallMode.BLOCK)
        .build()
);
System.out.println(inputVerdict.prediction());
```

The Go fragment runs inside your request handler, which supplies `ctx`, `fw`, and `userInput` and returns an error. Import `log` and `github.com/Silmaril-Security/sdk-go/firewall`. The Java fragment runs inside a method that propagates classification exceptions. Handle the verdict or error according to the [effective mode](https://silmaril.security/docs/guides/enforcement.md) before continuing the sequence.

## Batch independent events

Use batch classification for independent inputs. Responses preserve input order. Batch calls preserve per-item metadata while leaving conversation history unchanged. The same conversation ID on batch items leaves those items independent.

Use concurrency for independent events or different conversations. Keep direct `classify()` calls within one conversation sequential: overlapping calls you start yourself are sent as they are made, and only `protect()` and the `parallel` integrations order them for you.

## Field names

| API field | TypeScript option | Python option | Go option | Java builder |
| - | - | - | - | - |
| `hook` | `hook` | `hook` | `WithHook` | `hook(...)` |
| `tool_name` | `toolName` | `tool_name` | `WithToolName` | `toolName(...)` |
| `metadata` | `metadata` | `metadata` | `WithMetadata` | `metadata(...)` |

See the [single-event API](https://silmaril.security/docs/api-reference/classify.md) and [SDK reference](https://silmaril.security/docs/sdk/typescript.md) for complete request options.


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