The command line

One file, and it needs only Node.js 22 or later:

curl -O https://developers.aigently.ai/aigently.mjs
export AIGENTLY_API_KEY=ag_test_...
node aigently.mjs conversations list --limit 5

Any API operation

Every operation in the reference is a command: its resource, its method, its ids in order, and its fields as flags — the field's name with dashes.

node aigently.mjs agents retrieve 8a1f3c2e-…
node aigently.mjs conversations retrieve 5f0c9a52-… --include transcript
node aigently.mjs calls create --agent-id 8a1f3c2e-… --to-number +966501234567 \
  --variables '{"first_name": "Sara"}'
node aigently.mjs conversations list --agent-id 8a1f3c2e-… --all > conversations.jsonl

• Lists take commas (--include transcript,cost), or a JSON array when an item has a comma in it (--turns '["Hi, are you open on Sunday?"]'). Objects take JSON, and a file takes its path (--file ./faq.pdf). null sends null, which is how a number is detached from its agent.
• --json '{…}', or --json @body.json, sends a whole body; flags add to it.
• --all walks every page of a list, printing one JSON object a line.
• A request that takes an Idempotency-Key gets one, unless you pass your own with --idempotency-key.
• The answer is printed as JSON. A refusal prints its code, detail and request id, and exits 1.

node aigently.mjs operations lists every command.

An agent's fields as types

node aigently.mjs types --agent 8a1f3c2e-… > agent.ts
node aigently.mjs types --agent 8a1f3c2e-… --lang python > agent_fields.py

It writes the agent's three lists of fields — what a conversation can start with, what it collects, and what its analysis writes — as TypeScript interfaces or Python TypedDicts, required fields marked. Write them again when the agent's fields change: the agent.updated event says when. A field named like a Python keyword, such as from, is written in the TypedDict("…", {…}) form, which takes any name.

Evaluations in a build step: evaluate

node aigently.mjs evaluate 8a1f3c2e-…

It rehearses the agent's saved conversations, waits for the verdict, prints every conversation's outcome, and exits 0 when all passed, 1 when one failed, and 3 when none failed but some could not be checked. --json prints the whole run instead, and --timeout says how many seconds to wait (25 minutes unless you say). See Evaluations in your pipeline.

A call, followed live: follow

node aigently.mjs follow 5f0c9a52-…

It prints what is said on a call as it is said — Caller: and Agent: lines — and stops when the call ends. --json prints each line as the API sends it. See Live calls.

Test events on your machine: listen

The platform cannot reach localhost. listen keeps a connection open to the API with a test key and passes on everything a test webhook receiver would be sent — and, if you ask, the context lookups of test calls — to a server on your machine.

node aigently.mjs listen --forward-to localhost:3000/hooks

• Events. Each test event is POSTed to --forward-to with the headers a webhook carries, signed with the session's own secret, which it prints when the connection is ready. Check them exactly as you would a receiver's (how). What your server answers is only printed.
• Lookups. With --forward-lookups-to, a test call's context lookup is POSTed there, and your server's status and body go back to the call as its answer — so a test inbound call reaches your own code. An open session is asked before the agent's test address or its sample answer.
• Only what the key reaches. A key limited to some projects or agents hears only about those, and is asked only their test calls' lookups.
• Only what the key may read. Listening needs conversations:read, and a conversation.transcript event also needs transcripts:read. Every key preset has both.
• Test keys only. A live key is refused when it connects: real conversations go to receivers whose addresses have been checked, never to a laptop.
• A few at a time. A key may keep 3 sessions open, and an organization 10.
• It stops when the key does. Revoke the key, let it expire, or rotate it without an overlap, and the session ends within half a minute.
• Stop it and its session is gone, with everything it was holding: the next test call's events go only to your test receivers.

An AI assistant: mcp

node aigently.mjs mcp carries an assistant's MCP messages from standard input to the API's MCP server, and the answers back — for an assistant that runs its tools as a local program.

Options

Your key travels in a header, never in an address, where a proxy would log it.