🤖 Agent AI API

Dedicated endpoint to use Neuralai Agent AI from your applications: create, run and manage your agents and read the execution history. Requires an API key with the agents scope (opt-in, selectable in API Hub → API Keys).

📡 Endpoint

POST https://app.neuralaiweb.com/functions/agentApi
Authentication & scope

🔑 agents scope required

The key must have the "agents" scope (opt-in, not preselected at creation): it enables execution, creation, update, deletion of agents and history reading. The key is verified via SHA-256: always send it in clear in the header or body, never its hash.

# Header (consigliato)
x-api-key: nai_...

# oppure nel body JSON
{ "api_key": "nai_...", "operation": "list_agents" }
Operations

operation field in the JSON body. Write = modifies your agents (requires the agents scope).

👁️

list_agents

List your agents

—

👁️

get_agent

Full agent detail

agent_id

✍️

create_agent

Create a custom agent

name, role, synthesis, general_prompt, …

✍️

update_agent

Partial update (also status, api_key_id)

agent_id + campi

✍️

delete_agent

Delete an agent

agent_id

👁️

execute

Run the agent (task or playground)

agent_id, input, mode?, session_id?

👁️

list_tasks

Execution history (AgentTask)

agent_id?, limit? (max 100)

👁️

get_task

Single execution with full result

task_id

👁️

get_cad_job

Status and files of an agent-generated 3D model (polling)

job_id

👁️

get_calc_job

Status and report of an agent-generated engineering calculation (polling)

job_id

Where to find the agent ID
  • In the app: in the Agent AI dashboard (/agent-ai) each card shows the agent ID with a Copy button; the ID also appears in the playground URL (/agent-playground/<id>).
  • Via API: the list_agents operation returns each agent's id — the most reliable way to map name → id in your code.
  • IDs are permanent: save them in your integration's configuration. If you delete and recreate an agent the ID changes — never invent an agent_id, always get it from list_agents or the card.
Examples

1) Run an agent (final result in history)

const res = await fetch("https://app.neuralaiweb.com/functions/agentApi", {
  method: "POST",
  headers: { "Content-Type": "application/json", "x-api-key": "nai_..." },
  body: JSON.stringify({
    operation: "execute",
    agent_id: "ag_xxx",
    input: "Prepara il preventivo per il cliente Rossi",
    mode: "task"
  })
});
const data = await res.json();
// { success: true, response: "...", task_id: "...",
//   tokens_consumed: 15, elapsed_s: 4 }

2) Create an agent

{
  "operation": "create_agent",
  "name": "Preventivi Acme",
  "role": "preventivi",
  "synthesis": "Genera preventivi professionali dal listino",
  "general_prompt": "Sei il consulente commerciale di Acme…",
  "welcome_message": "",
  "icon_emoji": "🧾",
  "dynamic_mode": false,
  "doc_folders": ["Listini"],
  "web_folders": [],
  "kb_ids": [],
  "task_history_ids": [],
  "use_all_task_history": false,
  "direct_files": [],
  "api_key_id": ""
}

Limits (as in the app): name 60, synthesis 200, role 60, general prompt 20,000, welcome 500 chars; max 20 doc folders, 20 web folders, 5 KBs, 50 direct files and 20 agents linked in task_history_ids (professional history). Direct files must already be in Neuralai storage (upload via apiUploadFile): external URLs are rejected (SSRF protection) and Knowledge Bases must belong to the key owner.

3) History and playground

// Cronologia (origin "api")
{ "operation": "list_tasks", "agent_id": "ag_xxx", "limit": 20 }
{ "operation": "get_task", "task_id": "task_xxx" }

// Playground: chat con sessione persistente
{ "operation": "execute", "agent_id": "ag_xxx",
  "input": "Ciao, presenta le tue funzioni", "mode": "playground" }
// → { session_id: "...", response: "..." }
// ripeti con session_id per continuare la conversazione
🤝 Professional history (agent collaboration)

The agent can receive the completed results of your other agents as a knowledge source: set task_history_ids (array of agent IDs, max 20, must belong to the key owner) on create_agent/update_agent, or use_all_task_history: true to use the entire history. At every execute, the completed results (status succeeded) of the selected agents are injected into the knowledge block together with documents, web sources and KBs: the 50 most recent, 6,000 chars each, within the 40,000-char global cap (extended context = 30 tokens per run). Empty = unchanged behavior. list_agents and get_agent return both fields.

// Collega 2 agenti come fonte di cronologia professionale
{
  "operation": "update_agent",
  "agent_id": "ag_xxx",
  "task_history_ids": ["ag_yyy", "ag_zzz"]
}

// Oppure: l'intera cronologia dell'utente
{ "operation": "update_agent", "agent_id": "ag_xxx",
  "use_all_task_history": true }

// create_agent accetta gli stessi campi
// (task_history_ids vuoto = nessuna cronologia collegata)
  • One-way flow: the agent reads the other agents' completed results as reference material; its run produces a new task in the history, which can feed other agents in turn.
  • Results are treated as data in the same SOURCES block as the other sources (prompt injection resistance): they change the reference context, never the agent's behavior or role.
Test from your PC terminal (Windows CMD)

curl.exe is preinstalled in Windows 10 and 11: open the Command Prompt (cmd) and paste the commands below. Replace nai_YOUR_TOKEN with your API key (agents scope) and ag_xxx with the agent ID (see the previous section). No installation needed.

1) List your agents (you get the ID here)

curl.exe -X POST "https://app.neuralaiweb.com/functions/agentApi" -H "Content-Type: application/json" -H "x-api-key: nai_IL_TUO_TOKEN" -d "{\"operation\":\"list_agents\"}"

2) Run an agent

curl.exe -X POST "https://app.neuralaiweb.com/functions/agentApi" -H "Content-Type: application/json" -H "x-api-key: nai_IL_TUO_TOKEN" -d "{\"operation\":\"execute\",\"agent_id\":\"ag_xxx\",\"input\":\"Prepara il report di oggi\",\"mode\":\"task\"}"

3) Create a new agent

curl.exe -X POST "https://app.neuralaiweb.com/functions/agentApi" -H "Content-Type: application/json" -H "x-api-key: nai_IL_TUO_TOKEN" -d "{\"operation\":\"create_agent\",\"name\":\"Assistente Report\",\"role\":\"report\",\"synthesis\":\"Genera report quotidiani\",\"general_prompt\":\"Genera un report professionale dai dati forniti\",\"icon_emoji\":\"📊\"}"

PowerShell / macOS / Linux variant

In PowerShell and in the macOS/Linux Terminal, wrap the JSON in single quotes without backslashes. In the Windows CMD use double quotes with backslashes as in the examples above. If you get a JSON error, check the quotes.

curl.exe -X POST "https://app.neuralaiweb.com/functions/agentApi" -H "Content-Type: application/json" -H "x-api-key: nai_IL_TUO_TOKEN" -d '{"operation":"list_agents"}'
🧊 3D models (CAD) via API

Agents with the cad tool generate REAL parametric 3D models on request. Create an agent with allowed_tools: ["cad"] (or leave it empty = all tools), then run it with operation execute asking for a 3D model: when the model emits the [[GENERACAD:Title]] marker, the API replies immediately with a pending deliverable and a job_id. Generation takes 2-5 minutes for simple models, up to 14 minutes for complex ones: poll operation get_cad_job every 5-10 seconds until status is "succeeded", then download the files directly from the public URLs in result.files.

// 1) Esecuzione: la risposta arriva subito, con il job in avvio
{ "operation": "execute", "agent_id": "ag_xxx",
  "input": "Crea un pignone a 24 denti con foro da 10 mm", "mode": "task" }
// → { success: true, response: "scheda tecnica ...", deliverable: {
//     type: "cad", status: "pending", title: "Pignone 24 denti", job_id: "..." } }

// 2) Polling ogni 5-10 s finché status = "succeeded"
{ "operation": "get_cad_job", "job_id": "job_xxx" }
// → { status: "succeeded", result: {
//     files: [ { filename: "model.stl", url: "https://...", ext: "stl" },
//              { filename: "model.step", url: "https://...", ext: "step" },
//              { filename: "model.dwg", url: "https://...", ext: "dwg" },
//              { filename: "model.glb", url: "https://...", ext: "glb" }, ... ],
//     preview_url, dims, summary, warnings } }
  • files contains publicly downloadable URLs (STL for 3D printing, STEP for CAD software, DWG/DXF compatible with AutoCAD 2000/2002, GLB for viewing), plus preview_url (render image), dims (bounding box) and summary (technical sheet).
  • Cost: 40 tokens charged at submission, with automatic refund if the generation fails. Complex models generated in multiple modular components cost +20 tokens per extra component beyond the first (max 6 components, up to 140 total), charged on delivery. The technical sheet of the model arrives in data.response before generation completes.
  • Agents without the cad tool ignore the marker: 3D generation is never started for them.
📐 Engineering calculations via API

Agents with the calcolo tool run REAL engineering calculations (scientific Python in a sandbox: numpy, scipy, sympy, anastruct) and deliver a full calculation report with plots. Create an agent with allowed_tools: ['calcolo'] (or leave it empty = all tools), then run it with operation execute asking for a calculation: when the model emits the [[GENERACALC:Title]] marker, the API replies immediately with a pending deliverable and a job_id. The pipeline (Python script, isolated execution, report generation) takes 2-4 minutes: poll operation get_calc_job every 5-10 seconds until status is 'succeeded', then read report, results and downloadable files from the response. Pass the optional lang field in the execute body (e.g. 'it', 'en') to set the report language.

// 1) Esecuzione: la risposta arriva subito, con il job in avvio
{ "operation": "execute", "agent_id": "ag_xxx",
  "input": "Verifica a flessione una trave HEA200 in S275 con schiera 5 kN/m, luce 6 m",
  "mode": "task", "lang": "it" }
// → { success: true, response: "scheda breve del calcolo ...", deliverable: {
//     type: "calc", status: "pending", title: "Verifica trave HEA200", job_id: "..." } }

// 2) Polling ogni 5-10 s finché status = "succeeded"
{ "operation": "get_calc_job", "job_id": "job_xxx" }
// → { status: "succeeded", result: {
//     title, standard: "NTC 2018", approach: "...",
//     report: "## Dati e ipotesi ... (markdown completo)",
//     results: [ { name: "M_max", value: 123.45, unit: "kNm" }, ... ],
//     figures: 3,
//     files: [ { filename: "figura-1-chiara.png", url: "https://..." },
//              { filename: "calcolo.py", url: "https://..." },
//              { filename: "relazione.md", url: "https://..." }, ... ] } }
  • Cost: 30 tokens charged at submission (15 base + 15 for the in-depth step with load combinations and fatigue checks), with automatic refund if the calculation fails. The full report in data.response arrives before generation completes.
  • Agents without the calcolo tool ignore the marker: no calculation is ever started for them.
Tokens & attribution
  • Same pricing as in the app: 15 tokens per run, 30 if the knowledge context exceeds 40,000 chars, +5 if the agent has dynamic behavior. Atomic charge on the owner's NeuralAI balance, with automatic refund if the model fails.
  • Attribution: API executions are attributed to the key used in the request (usage log, API Hub → Stats). If an agent has an associated key (api_key_id field, settable via API or from the agent drawer), executions made FROM THE APP (playground, tasks, scheduled) are attributed to that key.
Security
  • Isolation: each key sees and modifies ONLY the agents of its owner (key-owner check on every operation).
  • SSRF protection: direct files accept only Neuralai storage URLs (media.base44.com, base44.app, storage.googleapis.com/neuralai-canvas-sites bucket).
  • The agent's knowledge is wrapped in dedicated delimiters and treated as data, not instructions (prompt injection resistance).
  • Store the key server-side (environment variables or Secret Manager), never in client code: see the API Key Security section.

Cookies & Privacy

We use technical cookies necessary for the site to function and, only with your consent, Google and Meta measurement and marketing cookies. You may accept or reject.