Skip to main content
A context provider reads information before the model runs. Use it when every answer needs a small, known source. Use a tool or retrieval when the model should request only the information relevant to a question.

ContextProvider interface

The public interface exposes name and fetchContext(query, ctx): Promise<string>. Return an empty string to contribute nothing. resolveContextProviders() calls the providers in parallel and joins their results under Markdown ## Context: <name> headings. Thrown errors become labeled context text; they are not silently omitted. There is no AgentConfig.context or RunOpts.context field in v4. Assemble context in host code before calling the Agent.

Built-in providers

Filesystem paths are checked against basePath; unreadable files are skipped. Prefer an explicit files list. The v4 glob implementation matches immediate file names; do not assume recursive ** traversal. Character caps are not token budgets. HTTP non-2xx responses produce a status message; network errors propagate to the resolver’s labeled error text. There is no built-in TTL cache, request timeout, POST body, or retry option. Wrap the public provider contract if your host requires those behaviors.

Plugging into an Agent

This complete host function accepts a model and a verified user ID. Create ./agent-notes/returns.md before calling it. It reads the file and a local preferences map, places the resolved text in run metadata, and reads that value through the supported instructions resolver.
The map stands in for an application-owned database query. Replace it with a query scoped to the verified identity, and preserve the string return contract. This function creates one isolated session per call; a conversational host can reuse owned sessions instead.

resolveContextProviders(providers, query, ctx)

The helper returns one combined string. Inspect required sources before invoking the model if missing or failed data should block an answer. Its default error-as-text behavior is useful for optional context, but does not establish that a required lookup succeeded.

Caching strategies

Cache only data with an explicit owner and expiry. Include tenant, user, query, and relevant permissions in cache keys when they affect the result. A single cached string on a shared provider can leak one user’s context into another run. A wrapper must still implement fetchContext, not fetch.

Per-user context

Use ctx.userId and ctx.tenantId to scope application queries. Passing an identity is not authentication, and file/HTTP providers do not infer access rights. A host may select a different base directory or endpoint after authorizing the caller.

Token cost considerations

Prefetched context is sent with each run. Set character limits, inspect actual token usage, and keep large corpora in retrieval. See memory budgets and cost tracking; do not estimate model cost from file bytes alone.