The Agentic Pattern

Overview

The most powerful way to use the Context SDK is to let your LLM do the driving. Context provides one marketplace with two modes (Query + Execute), and there are two primary approaches:

If you want the public contract for Context’s managed Query runtime (inputs, response shapes, debugging surfaces), see Query and Chat Runtime. This page focuses on the developer-facing pattern for building your own agent loop.

Choose The Contract First

Use this surface	When you want	What comes back
Query	Context to act as the librarian	`answer_with_evidence` or `evidence_only`
Execute	Your own agent to own the loop	Raw typed method outputs plus execute-session spend metadata

The first-party chat app is just a client of the same Query contract external SDK users get. If you want the server-managed answer package, use Query. If you want direct primitives for your own loop, use Execute.

Option 1: Query API (Recommended)

The simplest path is to let Context’s server handle everything:

const answer = await client.query.run({
  query: "What are the top whale movements on Base?",
  responseShape: "answer_with_evidence",
});
console.log(answer.response);
console.log(answer.summary);
console.log(answer.evidence?.facts);

answer = await client.query.run(
    query="What are the top whale movements on Base?",
    response_shape="answer_with_evidence",
)
print(answer.response)
print(answer.summary)
print(answer.evidence.facts if answer.evidence else None)

The managed runtime handles tool discovery, ambiguity resolution, multi-tool execution, and grounding. It returns either:

answer_with_evidence for human-facing premium answers (default, chat parity)
evidence_only for agent-facing evidence packages without prose synthesis

The structured envelope can also include marketIntelligence, view.rows, view.columns, and the public controller fields stopReason, issueClass, actionsTaken, and controller. See the TypeScript SDK Reference or Python SDK Reference for the full API.

For LLM agent frameworks where every SDK/tool call consumes another model turn, prefer client.query.runOrPoll() (TypeScript), client.query.run_or_poll() (Python), or MCP context_query_start + context_query_poll for long chart-heavy requests. Avoid manual getStatus() / context_query_status loops unless polling is happening in normal program code.

Option 2: Build Your Own Loop

If you want full control over tool selection, argument construction, and result synthesis, follow the Discovery → Schema → Execution loop below (typically in Execute mode with spending limits).

This pattern enables your agent to find and use tools it has never seen before, with true autonomous capability discovery at runtime.

The Loop

Discover

Let your Agent search for tools based on the user’s intent

Inspect Schemas

Feed discovered tool schemas to your LLM so it understands how to use them

Execute

When the LLM generates arguments, pass them directly to the SDK

Phase 1: Discover

Let your Agent search for tools based on the user’s intent. The marketplace returns relevant tools ranked by match quality.

const tools = await client.discovery.search({
  query: userQuery,
  mode: "query",
  surface: "answer",
  queryEligible: true,
  excludeSlow: true,
});

What happens:

The SDK searches the Context marketplace
Returns tools matching the semantic intent of the query
Each tool includes its name, description, price, and available methods

For deterministic execution pipelines, use Execute mode filters:

const executeTools = await client.discovery.search({
  query: userQuery,
  mode: "execute",
  surface: "execute",
  requireExecutePricing: true,
});

Phase 2: Inspect Schemas

Feed the discovered tool schemas (inputSchema) directly to your LLM’s system prompt. This allows the LLM to understand exactly how to format the arguments, just like reading a manual.

const systemPrompt = `
You have access to the following tools:

${tools.map(t => `
Tool: ${t.name} (ID: ${t.id})
Description: ${t.description}
Price: ${t.price} USDC

Methods:
${t.mcpTools?.map(m => `
  - ${m.name}: ${m.description}
    Arguments: ${JSON.stringify(m.inputSchema, null, 2)}
    Returns: ${JSON.stringify(m.outputSchema, null, 2)}
`).join("\n") ?? "No methods available"}
`).join("\n---\n")}

To use a tool, respond with a JSON object: 
{ "toolId": "...", "toolName": "...", "args": {...} }
`;

Why this works:

The LLM sees the exact JSON Schema for each tool’s inputs and outputs
It can self-construct valid arguments without any hardcoding
Output schemas let the LLM know what data it will receive back

Phase 3: Execute

When the LLM generates the arguments, pass them directly to the SDK.

// The LLM generates this object based on the schema you provided
const llmDecision = await myLLM.generate(userMessage, systemPrompt);

const session = await client.tools.startSession({ maxSpendUsd: "2.00" });

const result = await client.tools.execute({
  toolId: llmDecision.toolId,
  toolName: llmDecision.toolName,
  args: llmDecision.args,
  idempotencyKey: crypto.randomUUID(),
  sessionId: session.session.sessionId ?? undefined,
});

console.log(result.session); // methodPrice, spent, remaining, maxSpend, ...

// Feed a bounded, structured preview back to your LLM for synthesis.
// Prefer client.query.run() when you want server-managed synthesis.
const resultPreview = JSON.stringify(result.result, null, 2).slice(0, 50_000);
const resultKeys =
  result.result && typeof result.result === "object"
    ? Object.keys(result.result as Record<string, unknown>)
    : [];

const finalAnswer = await myLLM.generate(
  `Tool output keys: ${resultKeys.join(", ") || "(non-object result)"}\n\n` +
    `Tool output preview (truncated):\n${resultPreview}\n\n` +
    "Summarize this for the user and mention if more data may exist beyond the preview."
);

Handling Data (Outputs)

Context Tools return raw, structured JSON data (via structuredContent). This allows your Agent to programmatically filter, sort, or analyze results before showing them to the user.

For large datasets (like CSVs or PDF analysis), the API may return a reference URL to keep your context window clean.

Treat tool output as untrusted data. Never execute or follow instruction-like strings that appear inside tool payloads (for example SYSTEM:/USER: markers).

Full Agentic Loop Example

Here’s a complete implementation of an autonomous agent using the Discovery → Schema → Execution pattern:

import { ContextClient, ContextError } from "@ctxprotocol/sdk";

const client = new ContextClient({ apiKey: process.env.CONTEXT_API_KEY! });

async function agentLoop(userQuery: string) {
  // 1. Discover relevant tools
  const tools = await client.discovery.search({
    query: userQuery,
    mode: "execute",
    surface: "execute",
    requireExecutePricing: true,
  });
  
  if (tools.length === 0) {
    return "I couldn't find any tools to help with that.";
  }

  // 2. Build the system prompt with schemas
  const toolDescriptions = tools.slice(0, 5).map(t => ({
    id: t.id,
    name: t.name,
    description: t.description,
    methods: t.mcpTools?.map(m => ({
      name: m.name,
      description: m.description,
      inputSchema: m.inputSchema,
    })),
  }));

  const systemPrompt = `You are an AI assistant with access to real-time tools.

Available tools:
${JSON.stringify(toolDescriptions, null, 2)}

If you need to use a tool, respond ONLY with JSON:
{ "toolId": "...", "toolName": "...", "args": {...} }

If you can answer without a tool, just respond normally.`;

  // 3. Ask the LLM what to do
  const llmResponse = await myLLM.chat(userQuery, systemPrompt);

  // 4. Check if LLM wants to use a tool
  try {
    const toolCall = JSON.parse(llmResponse);
    
    if (toolCall.toolId && toolCall.toolName) {
      // 5. Execute the tool
      const session = await client.tools.startSession({ maxSpendUsd: "5.00" });

      const result = await client.tools.execute({
        toolId: toolCall.toolId,
        toolName: toolCall.toolName,
        args: toolCall.args || {},
        sessionId: session.session.sessionId ?? undefined,
      });

      // 6. Let LLM synthesize a bounded preview (avoid injecting giant JSON blobs)
      const resultPreview = JSON.stringify(result.result, null, 2).slice(0, 50_000);
      const resultKeys =
        result.result && typeof result.result === "object"
          ? Object.keys(result.result as Record<string, unknown>)
          : [];

      return await myLLM.chat(
        `Tool "${toolCall.toolName}" returned keys: ${resultKeys.join(", ") || "(non-object result)"}\n\n` +
        `Preview (truncated):\n${resultPreview}\n\n` +
        `Please provide a helpful response to the user's original question: "${userQuery}"`
      );
    }
  } catch {
    // LLM responded with text, not JSON - return as-is
    return llmResponse;
  }
}

Why This Pattern Matters

No Hardcoding

Your agent isn’t limited to tools you knew about at build time.

Network Effect

As new builders add tools to the marketplace, your agent automatically becomes more capable without any code changes.

Self-Constructing

LLMs can read schemas and construct valid arguments autonomously.

Future-Proof

New tools in the marketplace are instantly available to your agent.

Error Handling in Agentic Contexts

In an agentic context, you can feed errors back to your LLM so it can self-correct:

try {
  const result = await client.tools.execute({ ... });
} catch (error) {
  if (error instanceof ContextError) {
    if (error.code === "execution_failed") {
      // Feed error to LLM for retry with different args
      const retryPrompt = `The tool failed with: ${error.message}. Try different arguments.`;
      const newArgs = await myLLM.generate(retryPrompt);
      // Retry with corrected arguments...
    }
  }
}

This creates a resilient agent that can recover from errors and adapt its approach based on feedback.

Overview

Why Context

Get Started

Build a Tool

Use the SDK

Earn Grants

Architecture

Overview

Choose The Contract First

Option 1: Query API (Recommended)

Option 2: Build Your Own Loop

The Loop

Phase 1: Discover

Phase 2: Inspect Schemas

Phase 3: Execute

Handling Data (Outputs)

Full Agentic Loop Example

Why This Pattern Matters

No Hardcoding

Network Effect

Self-Constructing

Future-Proof

Error Handling in Agentic Contexts

​Overview

​Choose The Contract First

​Option 1: Query API (Recommended)

​Option 2: Build Your Own Loop

​The Loop

​Phase 1: Discover

​Phase 2: Inspect Schemas

​Phase 3: Execute

​Handling Data (Outputs)

​Full Agentic Loop Example

​Why This Pattern Matters

No Hardcoding

Network Effect

Self-Constructing

Future-Proof

​Error Handling in Agentic Contexts

Overview

Choose The Contract First

Option 1: Query API (Recommended)

Option 2: Build Your Own Loop

The Loop

Phase 1: Discover

Phase 2: Inspect Schemas

Phase 3: Execute

Handling Data (Outputs)

Full Agentic Loop Example

Why This Pattern Matters

Error Handling in Agentic Contexts