Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
Twitter User (twitterUser)
| Field | Value |
|---|---|
| Category | social / tool (dual-purpose) |
| Backend handler | server/nodes/twitter/twitter_user/__init__.py — dispatch via BaseNode.execute() + @Operation("lookup") -> _do_lookup (helpers in _base.py) |
| Tests | server/tests/nodes/test_twitter.py |
| Skill (if any) | server/skills/social_agent/twitter-user-skill/SKILL.md |
| Dual-purpose tool | yes - tool name twitter_user |
Purpose
Look up Twitter users and their social graph via GET /2/users/me,
GET /2/users/by/username/:username, GET /2/users/:id,
GET /2/users/:id/followers, and GET /2/users/:id/following. Works as a
workflow node and an AI agent tool. Every SDK call is wrapped in
asyncio.to_thread(...) since XDK is sync-only.
Inputs (handles)
| Handle | Connection type | Required | Purpose |
|---|---|---|---|
input-main |
main | no | Upstream data; not consumed directly - all inputs come from parameters |
Parameters
| Name | Type | Default | Required | displayOptions.show | Description |
|---|---|---|---|---|---|
operation |
options | me |
yes | - | me / by_username / by_id / followers / following |
username |
string | "" |
yes (by_username) | operation: ['by_username'] |
Handle without @. |
user_id |
string | "" |
yes (by_id), optional (followers/following) | operation: ['by_id','followers','following'] |
If omitted for followers/following, the authenticated user is used via get_my_user_id. |
max_results |
number | 100 |
no | operation: ['followers','following'] |
Clamped max(1, min(requested, 1000)). |
Outputs (handles)
| Handle | Shape | Description |
|---|---|---|
output-main |
TwitterUserOutput |
Lookup result; also returned to the LLM when invoked via input-tools |
Output payload
_do_lookup returns a TwitterUserOutput(operation, user?, users?, count?) (extra="allow"); validated + dumped by BaseNode._serialize_result.
me / by_username / by_id -> { operation, user } where user is format_user(...):
{
operation: string;
user: {
id: string;
username: string;
name: string;
profile_image_url: string | null;
verified: boolean; // defaults to false when API omits it
description: string | null;
created_at: string; // str(...) - empty string when missing
}
}
followers / following -> { operation, users, count }:
{
operation: string;
users: Array<UserData>; // same shape as user above
count: number;
}
Logic Flow
flowchart TD
A[BaseNode.execute -> @Operation lookup] --> CWR[call_with_retry _do_lookup]
CWR --> B[get_twitter_client]
B -- no access_token --> Eauth[raise RuntimeError<br/>Twitter not connected]
B --> C[_do_lookup]
C --> Dswitch{operation}
Dswitch -- me --> M1[to_thread users.get_me<br/>user_fields=created_at, description]
Dswitch -- by_username --> U1{username?}
U1 -- no --> EV[raise RuntimeError Username is required]
U1 -- yes --> U2[to_thread users.get_by_usernames]
U2 --> U3{data list empty?}
U3 -- yes --> EVn[raise RuntimeError User @handle not found]
Dswitch -- by_id --> I1{user_id?}
I1 -- no --> EV
I1 -- yes --> I2[to_thread users.get_by_ids]
I2 --> I3{data list empty?}
I3 -- yes --> EVn
Dswitch -- followers/following --> F1{user_id present?}
F1 -- no --> F0[to_thread get_my_user_id]
F0 --> F2[to_thread _sync_followers / _sync_following]
F1 -- yes --> F2
Dswitch -- _ --> Eunk[raise RuntimeError Unknown operation]
M1 --> K1[format_user + track_twitter_usage me 1]
U2 --> K2[format_user users 0 + track_twitter_usage by_username 1]
I2 --> K3[format_user + track_twitter_usage by_id 1]
F2 --> K4[map format_user + track_twitter_usage op len users]
K1 --> OK[Return TwitterUserOutput]
K2 --> OK
K3 --> OK
K4 --> OK
C -. raises 401/403 .-> REF[refresh_and_get_client] --> C2[retry _do_lookup once]
C -. other Exception .-> EGEN[propagate -> BaseNode error envelope]
Decision Logic
- Operation dispatch uses an
if/elifchain in_do_lookup. Any value outside the fiveLiteraloperations raisesRuntimeError(f"Unknown operation: {op}")(unreachable via the UI dropdown). - Validation:
by_username: emptyusername->RuntimeError("Username is required").by_id: emptyuser_id->RuntimeError("User ID is required").followers/following: missinguser_idis not an error - falls back toget_my_user_id.
- Not-found handling:
by_username/by_idraiseRuntimeErrorwhen the SDK returns an emptydatalist; it propagates toBaseNode.execute()'s error envelope. - Lazy auth refresh: identical to
twitterSend(call_with_retry) - any exception whosestr(e)contains401/403/Unauthorized/Forbiddentriggers one refresh-and-retry. - max_results clamping:
max(1, min(requested, 1000))for followers / following. Anything else is ignored. - Usage tracking:
me/by_username/by_id: 1 resource.followers/following:len(users)resources; skipped when the result list is empty.
Side Effects
- Database writes: one
api_usage_metricsrow per successful operation (when at least one resource was returned). - Broadcasts: none.
- External API calls:
GET https://api.twitter.com/2/users/me(always onme; also on followers/following whenuser_idomitted).GET https://api.twitter.com/2/users/by?usernames=...(by_username).GET https://api.twitter.com/2/users?ids=...(by_id).GET https://api.twitter.com/2/users/:id/followers(followers).GET https://api.twitter.com/2/users/:id/following(following).- Optional refresh:
POST https://api.twitter.com/2/oauth2/token.
- File I/O: none.
- Subprocess: none.
External Dependencies
- Credentials: OAuth tokens via
auth_service.get_oauth_tokens("twitter"). - Services:
PricingService,Database,TwitterOAuth(refresh). - Python packages:
xdk. - Environment variables: none.
Edge cases & known limits
max_results < 1: silently clamped to 1.max_results > 1000: silently clamped to 1000. The SDK may still paginate internally; only the first page is returned regardless.- Only first page for followers/following:
_sync_followers/_sync_followingreturn after the first page -next_tokenis discarded. - Not-found vs. empty: when the target user exists but has zero
followers/following, the handler returns
{users: [], count: 0}- it does NOT raise.by_username/by_idtreat empty data as an error. get_my_user_idcost not tracked: the implicitusers/mecall made on followers/following with emptyuser_idis not reflected inapi_usage_metrics.verifieddefault isFalse: even when the API omits the field the output will claim the user is not verified. Treat as unreliable unless expansions guaranteed.
Related
- Skills using this as a tool:
twitter-user-skill/SKILL.md - Sibling nodes:
twitterSend,twitterSearch,twitterReceive - Architecture docs: Pricing Service