Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

6.3 KB
Raw Blame
/**
 * The conversation AG-UI carries, as the shape the model provider expects.
 *
 * Its own module so it can be tested without starting a server: `index.ts` calls `serve()` at module
 * scope, so importing it to reach one pure function binds a port. `agent-langgraph/src/history.ts`
 * and `agent-computer/src/control.ts` were split out for the same reason.
 */
import type { RunAgentInput } from "@ag-ui/core";
import type OpenAI from "openai";
import { computerGuidance, NO_ANSWER_CAME } from "../../shared/bot-prompt";
import { researchRoleOfToolName } from "../../shared/research";
import { userContent } from "../../shared/user-content";

export { NO_ANSWER_CAME };

/** Translate the conversation AG-UI carries into the shape the model provider expects. */
export function toProviderMessages(
  input: RunAgentInput,
): OpenAI.Chat.ChatCompletionMessageParam[] {
  const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [
    /*
     * Worded for the tools this run offers, which is all this Bot can see of its grants: the names
     * say whether one of them is a search tool, and that decides whether the browser is told to
     * leave searching to it or never to search at all.
     */
    {
      role: "system",
      content: computerGuidance({
        search: (input.tools ?? []).some(
          (tool) => researchRoleOfToolName(tool.name) === "search",
        ),
      }),
    },
    // AG-UI application context is separate from history. The A2UI catalog and tool instructions
    // arrive here; omitting them leaves the model guessing component names and action schemas.
    ...(input.context ?? []).map(({ description, value }) => ({
      role: "system" as const,
      content: `${description}\n${value}`,
    })),
  ];

  /*
   * Which calls in this history were ever answered.
   *
   * Collected up front because an answer arrives as a later message than the call it answers. See
   * `NO_ANSWER_CAME` for what happens to a conversation carrying a call nothing ever answered.
   */
  const answered = new Set(
    input.messages
      .filter((message) => message.role === "tool")
      .map((message) => (message as { toolCallId?: string }).toolCallId)
      .filter((id): id is string => Boolean(id)),
  );

  /*
   * Tool results, by the call they answer.
   *
   * The history is not guaranteed to arrive with a result after the call it belongs to. Read back
   * from the durable thread store it arrives the other way round, result first, which is a payload
   * no provider accepts: a tool message with no preceding call, and then a call with nothing
   * following it. The model answers that with silence rather than an error, which is the worst of
   * both, so the pairing is rebuilt here instead of trusted.
   */
  const resultsByCall = new Map<string, string>();
  for (const message of input.messages) {
    if (message.role !== "tool") continue;
    const id = (message as { toolCallId?: string }).toolCallId;
    if (id) resultsByCall.set(id, String(message.content ?? ""));
  }

  for (const message of input.messages) {
    // Placed with the call they answer, below, rather than wherever they arrived.
    if (message.role === "tool") continue;
    if (message.role === "user") {
      messages.push({ role: "user", content: userContent(message.content) });
      continue;
    }
    if (message.role === "system" || message.role === "developer") {
      messages.push({ role: "system", content: String(message.content ?? "") });
      continue;
    }
    if (message.role === "assistant") {
      const toolCalls = message.toolCalls?.map((call) => ({
        id: call.id,
        type: "function" as const,
        function: callDetails(call),
      }));
      messages.push({
        role: "assistant",
        content: message.content ?? null,
        ...(toolCalls?.length ? { tool_calls: toolCalls } : {}),
      });

      /*
       * Close any of its calls that nothing ever answered, immediately after it.
       *
       * Position is not cosmetic: a tool result has to follow the assistant message that made the
       * call, so these go here rather than being appended at the end. A call answered later in the
       * history is left alone and its real answer arrives in its own turn.
       */
      /*
       * Every call this message made, answered, immediately after it.
       *
       * The real result where there is one, wherever it arrived in the input, and `NO_ANSWER_CAME`
       * where there is not. Both cases are the same requirement: a call must be followed by its
       * result, and the provider rejects the message outright otherwise.
       */
      for (const call of message.toolCalls ?? []) {
        if (!call.id) continue;
        messages.push({
          role: "tool",
          tool_call_id: call.id,
          content: answered.has(call.id)
            ? (resultsByCall.get(call.id) ?? "")
            : NO_ANSWER_CAME,
        });
      }
    }
  }

  return messages;
}

/**
 * A tool call's name and arguments, in whichever dialect it arrived in.
 *
 * TWO SPELLINGS, ONE CALL. AG-UI describes `{id, type: "function", function: {name, arguments}}` and
 * the history store writes `{id, name, args}`. Read back from a thread, every call arrives in the
 * second, so code reaching straight for `call.function` finds nothing there.
 *
 * That was diagnosed here as "the name is not always present" and papered over with a default, which
 * turned every restored call into a tool named `tool` with no arguments. The model is then shown a
 * call it cannot recognise as the one it made, so it makes it again: the exact repetition the
 * fallback was written to prevent.
 */
function callDetails(call: {
  function?: { name?: unknown; arguments?: unknown };
  name?: unknown;
  args?: unknown;
}): { name: string; arguments: string } {
  const name = call.function?.name ?? call.name;
  const args = call.function?.arguments ?? call.args;
  return {
    // Still defaulted, because a call with no name at all is rejected outright by the provider and
    // showing the model something is better than losing the turn. It is now the last resort it was
    // meant to be rather than the ordinary path.
    name: typeof name === "string" && name ? name : "tool",
    arguments:
      typeof args === "string"
        ? args
        : args === undefined || args === null
          ? "{}"
          : JSON.stringify(args),
  };
}