Skip to main content

NLP Sentiment Agent

This integration analyzes the sentiment of your input text with the Google Cloud Natural Language API. Use it to evaluate a sentiment-classification task rather than a conversational agent.

Required secrets​

SecretWhat it is
GOOGLE_NLP_API_KEYAPI key for the Google Natural Language API.

Where to get the credentials​

Enable the Natural Language API in your Google Cloud project and create an API key, then store it as a project secret named GOOGLE_NLP_API_KEY.

Turn support​

Single-turn. Each evaluation case is classified independently.

Limitations and notes​

  • This integration returns a sentiment label, not free-form chat text. Pair it with a specification and evaluation method that check a sentiment classification.
  • Calls are billed to your own Google Cloud project, subject to its quotas and rate limits.

How the agent works​

The agent you copy is a single JavaScript function. This walkthrough explains the pattern so you can adapt it for your own custom agent connection.

The entry point is an exported process function. Its input is the text to classify. The agent reads its API key from the env object, using the secret name from the Required secrets table above:

export async function process(input) {
 try {
  const apiKey = String(env.GOOGLE_NLP_API_KEY ?? "").trim();
  const { text } = parseInput(input);

  if (!apiKey || !text) {
   return "missing_required_input";
  }

Input is normalized by a parseInput helper. It trims the raw value, and if that value happens to be a JSON string or object it pulls the text out of a text, prompt, or input field; otherwise it treats the raw string as the text:

const parseInput = (input) => {
 const raw = String(input ?? "").trim();
 if (!raw) {
  return { text: "" };
 }

 try {
  const parsed = JSON.parse(raw);
  // ... pulls parsed.text ?? parsed.prompt ?? parsed.input
 } catch {}

 return { text: raw };
};

The HTTP request is a POST to the Natural Language API's analyzeSentiment endpoint. The API key is passed as a query-string parameter, and the body wraps the text in a document object:

const response = await fetch(
 `${ENDPOINT}?key=${encodeURIComponent(apiKey)}`,
 {
  method: "POST",
  headers: {
   "content-type": "application/json",
  },
  body: JSON.stringify({
   document: {
    type: "PLAIN_TEXT",
    content: text,
   },
  }),
 },
);

It reads the response as text and parses it as JSON, then extracts the sentiment score and magnitude from documentSentiment:

const score = Number(payload?.documentSentiment?.score);
const magnitude = Number(payload?.documentSentiment?.magnitude);

if (!Number.isFinite(score) || !Number.isFinite(magnitude)) {
 return `missing_sentiment_scores: ${response.status}: ${responseText.slice(0, 500)}`;
}

return toSentimentText(score);

A toSentimentText helper turns the numeric score into a label, so the agent returns a sentiment classification, not free-form chat text:

const toSentimentText = (score) => {
 if (!Number.isFinite(score)) {
  return "unknown";
 }
 if (score >= 0.25) {
  return "positive";
 }
 if (score <= -0.25) {
  return "negative";
 }
 return "neutral";
};

For error handling, the function returns descriptive strings rather than throwing. A missing key or text returns "missing_required_input", a failed HTTP response returns a google_nlp_request_failed: ... string, and any caught exception returns its message. The output is always a label (or a diagnostic string), never conversational text.

Adapting it for your own agent

To point this skeleton at a different service, you would change:

  • The ENDPOINT URL you POST to.
  • The authentication mechanism (here, an API key on the query string).
  • The request body shape sent to that service.
  • The response field you extract the result from (here, documentSentiment.score) and the logic that turns it into a label.
  • The secret key you read from env and declare in your project 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.