Add Context

Context providers are the primary way to inject runtime context into hosted requests.

Prerequisites

Read this guide after:

• Quickstart
• Build a Profile
• Concepts: Memory and Context

They are the main way to answer questions like:

• what should be prepended before runtime history?
• which identity or tenant hints should the agent see?
• which memory, knowledge, or workspace summaries should be visible?

If profiles define who the agent is, context providers define what the agent knows at request time.

Typical Context Inputs

Common context inputs include:

• user identity
• memory summaries
• knowledge summaries
• skills summaries
• workspace snapshots
• date or runtime metadata

These are usually injected as synthetic user messages ahead of the conversation history.

Two Ways To Add Context

1. Add direct ContextProviders

Use a provider when you want a simple, explicit injection function:

import type { ContextProvider } from "@agentrail/host";

const identityProvider: ContextProvider = async (context) => {
  return [
    {
      role: "user",
      content: `Current tenant: ${context.tenantId}\nCurrent user: ${context.userId}`,
      timestamp: Date.now(),
    },
  ];
};

This is the cleanest path when the logic is already easy to express as “return some messages”.

2. Adapt a transformContext function

Use createTransformContext or createContextProviderFromTransform when:

• you already have transform-style context logic
• you want to reuse older runtime-style context code
• you need one composition point that works over the full message array

This is useful when migrating from a less structured setup into Agentrail’s provider model.

Recommended Path

Use createDefaultCapabilityContextProviders if your host follows the default capability model.

That path is especially useful when you want to compose:

• memory index summaries
• knowledge metadata summaries
• skills inventory context
• workspace snapshots

The current implementation lives in:

• packages/host/src/defaults/capability-context.ts

Repository Example

The playground example builds request context here:

• examples/playground-server/src/context/index.ts

That file is a good example of how to:

• keep manager singletons outside route files
• build context providers per request
• combine framework defaults with example-specific runtime wiring

Ordering Matters

Context providers are not just a bag of helpers. Their order affects the final prompt seen by the model.

In general:

• identity/date/context headers should come first
• memory and knowledge summaries should come before current request history
• workspace snapshots should come late enough to reflect the current state

If providers start depending on subtle ordering assumptions, that is a sign to group or simplify them.

What To Put In Context Providers

Good provider content is:

• compact
• stable across one request
• clearly informational
• safe to prepend as synthetic context

Bad provider content is:

• highly conversational text that belongs in the actual prompt
• route-specific branching logic
• large raw documents when a summary or index would do

Common Mistakes

Avoid these patterns:

• loading too much raw state into every request
• mixing prompt identity with request-time context
• putting context assembly directly into route handlers
• using providers for behavior that should actually be a tool

Lower-Level API

If the defaults layer is too opinionated, use these primitives directly:

• ContextProvider
• createTransformContext
• createContextProviderFromTransform

These live in the host package and let you build a custom context pipeline without adopting the default capability stack.

Related Docs

• Build a Profile
• Host Defaults Reference
• Session Store Reference

Next Step

If your context pipeline is in place, the next extension point is usually Write a Plugin or Manage Prompts.