Agent SDK

Options

The SDK works with no options at all. These let you tune budgets per tool, keep some tools whole, and plug in your own storage.

Example#

const cw = createContextwaise({
  agent: "code-review",
  maxTokens: 600,
  budgets: { read_file: 1500, search_logs: 800 },
  full: ["get_user_profile"],
  onEvent: (e) => logger.debug(e),
});

All options#

agentstringoptional

Groups this agent's results in the dashboard, like code-review.

maxTokensnumberoptionalDefault: 600

Token budget for the model's view of one tool result. Results that fit pass whole, and so do results where a cut would save under 1,000 tokens or under 30%: a small cut isn't worth the extra model call an expand would cost.

budgetsRecord<string, number>optional

Per-tool budgets that override maxTokens, like { read_file: 1500 }.

fullstring[]optional

Tools whose output always reaches the model whole, never trimmed.

apiKeystringoptionalDefault: CONTEXTWAISE_API_KEY

Your Contextwaise key. With it, relevance is judged by the API and results are reported to your dashboard (tool names and sizes only). Without it, only the local cleanup runs: nothing relevant is ever cut.

baseUrlstringoptionalDefault: CONTEXTWAISE_URL

The Contextwaise app's URL. Required when a key is set.

ledgerLedgeroptionalDefault: in memory, last 5,000 calls

Where originals and decisions are kept, so views can be replayed and expanded. Plug in Redis or a database for agents that run across several processes. See Ledger.

onEvent(event) => voidoptional

Called for every decision, for your logs. See Events.

Choosing budgets#

File readers (read_file, get_document): give them a larger budget, around 1,500 tokens, so typical files reach the model whole. An agent that edits a file needs all of it.
Noisy tools (logs, test runs, search, listings): the default works well; cleanup alone often removes most of their output.
Small structured lookups (a user profile, an order): list them in full if the model must always see every field.

Then watch the expand rate per tool in the dashboard: a tool the agent often expands needs a bigger budget.

Reliability#

The API is never in your agent's way. If scoring takes more than 4 seconds or fails, the model reads that result's cleaned output whole, and so do later results for 30 seconds, before the SDK tries the API again. Nothing is cut on a guess. Dashboard reports are batched in the background and dropped if they can't be sent.