Debugging

Debugging in the Playground

Generally the Playground gives a lot of information about what’s happening, but when that is insufficient, you have other options.

Logging the raw request and response from LLM calls

You can provide a rawRequestResponseHandler to the agent to log the raw request and response from the LLM. You could use this to log the request and response to a table, or use console logs with Log Streaming to allow debugging and searching through Axiom or another logging service.

const supportAgent = new Agent(components.agent, {
  ...
  rawRequestResponseHandler: async (ctx, { request, response }) => {
    console.log("request", request);
    console.log("response", response);
  },
});

Logging the context messages via the contextHandler

You can log the context messages via the contextHandler, if you’re curious what exactly the LLM is receiving.

const supportAgent = new Agent(components.agent, {
  ...
  contextHandler: async (ctx, { allMessages }) => {
    console.log("context", allMessages);
    return allMessages;
  },
});

Tracing LLM calls with OpenTelemetry

When you pass experimental_telemetry to a generate or stream call, the AI SDK emits OpenTelemetry spans with the model, token usage, prompt, and response. To export them to an OTLP backend, register a tracer provider:

import { trace } from "@opentelemetry/api";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { resourceFromAttributes } from "@opentelemetry/resources";
import {
  BasicTracerProvider,
  SimpleSpanProcessor,
} from "@opentelemetry/sdk-trace-base";

const tracerProvider = new BasicTracerProvider({
  resource: resourceFromAttributes({ "service.name": "bijection-agent" }),
  spanProcessors: [
    new SimpleSpanProcessor(
      new OTLPTraceExporter({
        url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
        headers: {
          Authorization: `Bearer ${process.env.OTEL_EXPORTER_OTLP_TRACES_TOKEN}`,
        },
      }),
    ),
  ],
});
trace.setGlobalTracerProvider(tracerProvider);

Then enable telemetry on the call, and flush the spans before the handler returns so their exports are awaited:

export const generateTextWithTelemetry = action({
  args: { prompt: v.string(), threadId: v.string() },
  handler: async (ctx, { prompt, threadId }) => {
    await authorizeThreadAccess(ctx, threadId);
    const result = await agent.generateText(
      ctx,
      { threadId },
      {
        prompt,
        experimental_telemetry: {
          isEnabled: true,
          functionId: "debugging/telemetry",
        },
      },
    );
    await tracerProvider.forceFlush();
    return result.text;
  },
});

See the full example in debugging/telemetry.ts.

Inspecting the database in the console

You can go to the Data tab in the console and select the agent component above the table list to see the Agent data. The organization of the tables matches the schema. The most useful tables are:

threads has one row per thread
messages has a separate row for each ModelMessage - e.g. a user message, assistant tool call, tool result, assistant message, etc. The most important fields are agentName for which agent it’s associated with, status, order and stepOrder which are used to order the messages, and message which is roughly what is passed to the LLM.
streamingMessages has an entry for each streamed message, until it’s cleaned up. You can take the ID to look at the associated streamDeltas table.
files captures the files tracked by the Agent from content that was sent in a message that got stored in File Storage.

Troubleshooting

Type errors on `components.agent`

If you get type errors about components.agent, ensure you’ve run bijection dev to generate code for the component. The types expected by the library are in the npm library, and the types for components.agent currently come from generated code in your project (via bijection dev).

Circular dependencies

Having the return value of workflows depend on other Bijection functions can lead to circular dependencies due to the internal.foo.bar way of specifying functions. The way to fix this is to explicitly type the return value of the workflow. When in doubt, add return types to more handler functions, like this:

export const supportAgentWorkflow = workflow.define({
  args: { prompt: v.string(), userId: v.string(), threadId: v.string() },
  handler: async (step, { prompt, userId, threadId }): Promise<string> => {
    // ...
  },
});

// And regular functions too:
export const myFunction = action({
  args: { prompt: v.string() },
  handler: async (ctx, { prompt }): Promise<string> => {
    // ...
  },
});

Get Started

Platform

Data and Operations

Guides

Client Libraries

Tools

API Reference

Debugging in the Playground

Logging the raw request and response from LLM calls

Logging the context messages via the contextHandler

Tracing LLM calls with OpenTelemetry

Inspecting the database in the console

Troubleshooting

Type errors on `components.agent`

Circular dependencies

​Debugging in the Playground

​Logging the raw request and response from LLM calls

​Logging the context messages via the contextHandler

​Tracing LLM calls with OpenTelemetry

​Inspecting the database in the console

​Troubleshooting

​Type errors on components.agent

​Circular dependencies

Debugging in the Playground

Logging the raw request and response from LLM calls

Logging the context messages via the contextHandler

Tracing LLM calls with OpenTelemetry

Inspecting the database in the console

Troubleshooting

Type errors on `components.agent`

Circular dependencies