IVYXSTUDIO · IVY AGENT

Social listen

ivy.agent.social-listen · v0.1.0

ivyx

Listens for a brand's keywords: X's recent search and the web's news feeds, each mention read by a model for its mood (positive, neutral, negative; estimated, and IVYX Social says so), and up to two competitors' X sizes beside, as one answer of kind mentions that IVYX Social's listening shows and the mention-spike rule reads. Reads only; the model sees public posts, nothing of the brand's own.

Steps

In the order the agent's file lists them, each with where its inputs come from and the values the file fixes. A branch or a loop is a step too.

01
Is there an X connection?
ivy.node.social-plan
Reads an IVYX Social collect or inbox agent's input (a connection and an id per platform) and says which platforms are there, so the agent's if-branches run only those steps.
takes
x_connection from the agent's input
client from the agent's input
Ivy Node
02
The web's news feeds
ivy.node.rss-mentions
Reads RSS or Atom feeds (Google News' search feed for the query when no feed is given) with the standard library and answers each item as a mention of source web: the title, the link, the publisher, when.
takes
name from the agent's input
query from the agent's input, news_query
feeds from the agent's input
lang from the agent's input
country from the agent's input
Ivy Node
03
Read each mention's mood
The context is a JSON list of public social media posts and news items about a brand, each with an id and a text. For each item say whether it speaks of the brand positively, neutrally or negatively. Return a JSON object with items: a list of {id, sentiment} where sentiment is one of positive, neutral, negative, one entry per item, the ids copied exactly. Answer with the JSON object only.
takes
context from step 4, mentions
Model turn
04
Every mention, once
ivy.node.mentions-pack
Gathers the search nodes' mentions into one answer of kind mentions, the model's sentiment attached to each by id, and the competitors' sizes beside; what IVYX Social's listening takes.
Runs only on the else branch of step 6.
takes
name from the agent's input
mentions_a from step 7, mentions
mentions_b from step 2, mentions
Ivy Node
05
One list of mentions
ivy.node.mentions-pack
Gathers the search nodes' mentions into one answer of kind mentions, the model's sentiment attached to each by id, and the competitors' sizes beside; what IVYX Social's listening takes.
Runs only on the else branch of step 6.
takes
client from the agent's input
name from the agent's input
mentions from step 4
sentiments from step 3, output
competitor_a from step 8
competitor_b from step 9
returns
kind, mentions, competitors, count, negative, client
Ivy Node
06
X?
Lets what follows run only when has_x of step 1 is true.
Branch
07
X recent search
ivy.node.x-search
Searches the last seven days of X for a query (keywords, a brand name, a hashtag) through the X API v2 with an X connection, as the mentions IVYX Social's listening shows: the post, who wrote it, when, and its impressions as reach.
Runs only on the then branch of step 6.
takes
connection from the agent's input, x_connection
query from the agent's input
name from the agent's input
Ivy Node
08
Competitor A on X
ivy.node.x-user
Reads an X account's public counts (followers, following, posts, listed) through the X API v2 with an X connection, as today's instant values in the collector's daily block; the signed-in account when no handle is given.
Runs only on the then branch of step 6.
takes
connection from the agent's input, x_connection
handle from the agent's input, competitor_a
Ivy Node
09
Competitor B on X
ivy.node.x-user
Reads an X account's public counts (followers, following, posts, listed) through the X API v2 with an X connection, as today's instant values in the collector's daily block; the signed-in account when no handle is given.
Runs only on the then branch of step 6.
takes
connection from the agent's input, x_connection
handle from the agent's input, competitor_b
Ivy Node

Nodes it brings

Adding this agent in IVYX Studio adds these nodes with it. A node your workspace already has is kept as it is, even at another version.

What it touches

Collected from what each of its nodes declares, plus the model call when a step is a model turn. A declaration is the author's statement, and it is what policy rules select on.

Calls a modelNetwork

Inputs

Field	Type	Description
firm	string	The firm's slug in IVYX Social; the destination routes the delivery by it.
client	string	Not declared
namerequired	string	The listening query's name in IVYX Social.
queryrequired	string	X's search query.
news_query	string	The news search, when it differs from the query.
feeds	array	Feed URLs instead of the news search.
lang	string	The news language.
country	string	The news edition.
x_connection	Not declared	The platform's connection, as the stored secret connection.<id>.
competitor_a	string	A competitor's X handle.
competitor_b	string	Another.

Outputs

Field	Type	Description
kindrequired	string	mentions
mentionsrequired	array	Not declared
competitors	array	Not declared
count	integer	Not declared
negative	integer	Not declared
client	string	Not declared

Tests

2 of 2 test cases passed on Oct 25, 2026, in the publisher's own environment, before this version was published. The registry keeps that record; it does not run the cases again.

Requires: python:3.9, a model core, tools/connectors-standin.py on 127.0.0.1:18911, its connections stored as the secrets connection.standin-<platform>

web-only
Two news items about the brand are two mentions, each with a sentiment the model gave.
given
firm ivyx
client IVYX
name ivyx
query ivyx
feeds ["http://127.0.0.1:18911/feed.xml"]
expects
kind equals mentions
count equals 2
mentions.0.source equals web
mentions.0.sentiment matches ^(positive|neutral|negative)$
with-x
With X connected, the search's post joins the news and the competitor's size rides beside.
given
firm ivyx
client IVYX
name ivyx
query ivyx
feeds ["http://127.0.0.1:18911/feed.xml"]
x_connection {"$secret":"connection.standin-x"}
competitor_a semrush
expects
kind equals mentions
count equals 3
competitors.0.handle equals semrush