Skip to main content

Responses API Agent

This integration calls the OpenAI Responses API with your input text and returns the model's text reply, so you can evaluate an OpenAI-hosted model without writing the client yourself.

Required secrets​

SecretWhat it is
OPENAI_API_KEYAPI key for the OpenAI Responses API.

Where to get the credentials​

Create an API key in your OpenAI account under API keys, then store it as a project secret named OPENAI_API_KEY.

Turn support​

Single-turn. Each evaluation case is sent as an independent request.

Limitations and notes​

  • The model and system instructions are set in the copied agent code. Edit the agent if you need to change them.
  • Calls are billed to your own OpenAI account, subject to its quotas and rate limits.

How the agent works​

The copied agent is a single JavaScript function. This walkthrough follows the real code so you can adapt the same pattern to point at a different service.

The entry point is process(input), where input is the per-case text the platform sends you:

export async function process(input) {
 try {
  const apiKey = String(env.OPENAI_API_KEY ?? "").trim();
  const { text, model, instructions } = parseInput(input);
  // ...

The secret is read from the ambient env object by key — env.OPENAI_API_KEY — and trimmed. That is the only place credentials enter the function. See Required secrets for the key you must declare.

parseInput accepts either plain text or a JSON object. A bare string is used as-is; a JSON object lets a case override the prompt, model, and instructions:

const parsed = JSON.parse(raw);
// ...
if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
 return {
  text: String(parsed.text ?? parsed.prompt ?? parsed.input ?? "").trim(),
  model: String(parsed.model ?? DEFAULT_MODEL).trim() || DEFAULT_MODEL,
  instructions: String(parsed.instructions ?? parsed.system ?? "").trim(),
 };
}

The HTTP request is a POST to the Responses endpoint with a Bearer auth header and a JSON body of { model, input }, adding instructions only when set:

const body = {
 model,
 input: text,
};

if (instructions) {
 body.instructions = instructions;
}

const response = await fetch(ENDPOINT, {
 method: "POST",
 headers: {
  authorization: `Bearer ${apiKey}`,
  "content-type": "application/json",
 },
 body: JSON.stringify(body),
});

The response text is parsed as JSON, then extractResponseText pulls the reply — preferring a top-level output_text, otherwise walking the output items' content parts:

const extractResponseText = (payload) => {
 if (typeof payload?.output_text === "string" && payload.output_text.trim()) {
  return payload.output_text.trim();
 }

 const outputItems = Array.isArray(payload?.output) ? payload.output : [];
 for (const item of outputItems) {
  const content = Array.isArray(item?.content) ? item.content : [];
  const text = content
   .map(extractTextFromContentPart)
   // ...
  if (text) {
   return text;
  }
 }

 return "";
};

On success the function returns { ok: true, text, id, model }. Every failure path — missing input, a non-2xx status, or an empty reply — returns an object with ok: false rather than throwing, and the outer try/catch converts any unexpected exception into the same shape:

if (!response.ok) {
 return {
  ok: false,
  error: "openai_request_failed",
  status: response.status,
  details: extractErrorMessage(payload, responseText),
 };
}

Adapting it for your own agent​

To repoint this skeleton at a different service, change a handful of things:

  • ENDPOINT — the URL you POST to.
  • The auth header — swap the Bearer scheme or header name for what your service expects.
  • The request body shape — { model, input } here; match your provider's schema.
  • extractResponseText — read the field your provider returns the text in.
  • The secret key read from env (and its entry in Required secrets).

Set it up​

  1. Copy this integration from the registry — see Registry integrations.
  2. Create the project secret above — see Project secrets.
  3. Preview the agent to confirm it works.