naturali-ai/naturali

Build, run and audit AI agents on naturali.ai over its REST API, CLI, TypeScript SDK or MCP server. Use when a task involves naturali.ai, an agent that must answer on WhatsApp or Discord, grounding an agent in uploaded documents, gating it with guardrails or human approvals, scoring a change with evals, or reading back what an agent generated and what it cost.

Attribute a naturali.ai project's agent spend to each end user with one actor per user and sessions opened as that actor, then read usage grouped by actor. Use when asked to track, report or bill usage or cost per customer or end user, create actors, open a session for an end user, find which user spent the tokens, or explain the null bucket in usage grouped by actor.

Make a naturali.ai orchestration route each message on a classification - a triage agent with output_schema feeds a condition node that runs only the matching agent. Use when asked to route or branch on a classification, add a condition node or conditional edges, read a structured field with output.object, or explain a node skipped in node_executions.

Use your own model vendor credential (OpenAI, Anthropic, Google, Bedrock, Vertex, Azure, Groq, xAI, a gateway or a self-hosted endpoint) in a naturali.ai project as a secret and an ai_provider. Use when asked to bring your own key (BYOK), add or rotate a vendor API key, check which models a key can reach, or when a provider answers 502 MODEL_LISTING_FAILED, 400 MODEL_LISTING_UNSUPPORTED or a 400 for bedrock or vertex without a credential.

Build a naturali.ai eval dataset from declared test cases and from real completed generations, so production mistakes become regression tests. Use when asked to create a dataset, test cases or fixtures for evals, write a regression suite, turn a bad answer into a test case, or when curating answers 409 GENERATION_NOT_COMPLETED, GENERATION_CONTENT_UNAVAILABLE or QUOTA_STORAGE_EXCEEDED.

Call a naturali.ai tool with no agent or model in the path to tell a broken tool from a model misusing a working one, reading the target's real status, URL and body from the error. Use when a tool call fails, an agent says a service is down, to test a tool's URL, headers or mapping before binding it, or on 502 TOOL_HTTP_ERROR, 403 TOOL_EGRESS_BLOCKED or 422 TOOL_DISPATCH_FAILED.

Put a token budget on a whole naturali.ai project - size it from daily usage, watch a project-scope quota in monitor mode, then enforce it. Use when asked to cap, limit or budget a project's spend or tokens, set a daily or monthly limit, stop a runaway agent, or explain a 429 QUOTA_EXCEEDED, a 409 QUOTA_CONFLICT, a quotas:MonitorBreach audit entry or a cost_usd cap that never fires.

Give every end user of a naturali.ai project their own token budget with one actor-scope quota, and a different one for a single user. Use when asked to limit, budget or rate-limit spend per customer or end user, set a per-user monthly token allowance, stop one user exhausting the project's budget, or explain 429 QUOTA_EXCEEDED "Quota exceeded for actor." or 400 "scope actor is not valid for metric requests".

Connect a Discord bot to a naturali.ai agent through a discord channel and prove the round trip on a real direct message. Use when asked to connect Discord, put an agent behind a Discord bot, answer Discord DMs with an agent, or find why a naturali Discord bot does not reply, and on 400 invalid_bot_token, 400 application_mismatch, 409 application_in_use or a channel gateway_error.

Hold a multi-turn conversation with a naturali.ai agent in a session, answered automatically or on demand, and read its transcript, cost and the model input of any turn. Use when asked to chat with an agent over several turns, open or resume a session, keep context between messages, attribute turns to a customer, read what the agent saw on a turn, or when a session call answers 409 (generation in progress), 410 (expired) or 429 QUOTA_EXCEEDED.

Create a naturali.ai project, the boundary every provider, secret, agent and formation lives in, and export its id as PROJECT. Use when starting on naturali from scratch, when asked to create or name a project or environment, when no PROJECT id is known yet, or when creating one answers 403 access_denied (project-scoped key) or 403 plan_limit_reached.

Declare a naturali.ai agent (instructions, model, step and sampling limits) in naturali.yaml, change it by editing the template, and list its versions. Use when asked to create, configure, rename or change an agent or its instructions or model, see its version history, try a fix on a second agent beside the original, or on 400 bad_request for a model, 400 SYSTEM_MESSAGE_NOT_ALLOWED or 409 AGENT_HAS_DEPENDENTS.

Write, validate, deploy, plan, update and tear down a naturali.ai formation template (naturali.yaml); every naturali skill that creates or changes a resource defers here. Use when asked to deploy, apply, plan, diff, update, inspect, roll back or delete a formation, stack or infrastructure as code, or on unsupported_resource_type, VALIDATION_FAILED, status failed, FORMATION_REPLACE_CLEANUP_FAILED, FORMATION_DELETE_FAILED, FORMATION_INVALID_METADATA, plan_feature_not_included or plan_limit_reached.

Give a naturali.ai project every naturali-managed model with no vendor account or credential through one naturali_ai_provider, and read the catalog and its prices. Use when asked to use naturali, managed or catalog models, set up a provider with no API key, list available models or their prices, or when a deploy fails with catalog_not_ready, managed_source_unavailable or 400 bad_request on a model from another source.

Make a naturali.ai staged rollout refuse to promote until an eval run pinned to the new agent version passes (promotion_gate). Use when asked to gate, block or protect a release or canary on a test suite, require a passing eval before promotion, or when promote answers 409 PROMOTION_GATE_UNMET or the eval passed but the gate stays closed.

Put a JSON Logic guardrail on a risky naturali.ai tool so small calls run on their own and large ones wait for a person. Use when asked to gate, govern or threshold a tool, require human sign-off above an amount, write, test or attach a guardrail, classify tool calls A/B/C/D, or on 403 plan_feature_not_included, a pending_approval tool result or a direct call refused with 422 TOOL_DISPATCH_FAILED.

Declare an http tool (URL placeholders, method, headers, argument JSON Schema) and bind it to a naturali.ai agent, optionally forcing the call with tool_choice. Use when an agent must call an API, webhook or HTTP endpoint, when asked to create, add or bind a tool, put a token in a tool header, force a tool call, or on 422 FORCED_TOOL_CHOICE_CANNOT_STOP or TOOL_EGRESS_BLOCKED.

Give a naturali.ai agent long-term memory - a memory store, a memory rule that extracts facts from every completed turn, and recall through knowledge_config.memory_store_ids. Use when asked to make an agent remember users or customers across conversations, add persistent memory, learn facts from conversations automatically, create a memory store or memory rule, or check what an agent has learned.

Give a naturali.ai agent retrieval over the project's documents with knowledge_config (document_paths, limit, min_score). Use when asked to make an agent answer from documents, a handbook, PDFs, photos or recordings, add RAG to an agent, stop it guessing beyond its sources, scope it to part of the corpus, or when an agent ignores documents it should know.

Give a teammate access to a naturali.ai project by email, even with no naturali account, as member or admin, then change their role or remove them. Use when asked to invite, add or share a project with a colleague, list members, promote someone to admin, remove a member or leave a project, explain a pending member, or on 403 access_denied with a project-scoped key or 409 for an address already in the project.

Give a naturali.ai agent a write_memory tool on a memory store (knowledge_config.write_memory_store_id) so it saves what it is asked to remember. Use when asked to let an agent save notes or remember things on request, give it a write_memory tool, have it decide what to store mid-conversation, or check what an agent saved to memory.

Put a boundary_policy on a naturali.ai agent so the platform refuses actions it would take on the agent's behalf, such as writing memories, and read the refusal in the transcript. Use when asked to restrict, sandbox or limit an agent's permissions, stop an agent writing memory, make it read-only, deny an IAM action to an agent, or when a transcript shows "Forbidden: boundary policy denies".

Upload a file (Markdown, text, PDF, photo or voice recording) to a naturali.ai project and ingest it into a searchable document, reading the text conversion wrote for images, audio and scans. Use when asked to upload or index a file, add a handbook, PDF, screenshot, receipt or voice memo to the knowledge base, OCR or transcribe a file, or on 409 FILE_ALREADY_INGESTED, 413, 402 insufficient_credit or a document stuck pending or failed.

Model a naturali.ai review process as a workflow - an agent drafts on entering a state, a person sends the draft back or approves it - through tasks and their history. Use when asked to build a workflow or state machine, add a human review state, run an agent with on_enter, open or move a task, send work back for revision, approve and close a task, edit a task's payload, read who moved a task and why, or debug 409 TASK_TRANSITION_CONFLICT.

Chain several naturali.ai agents into one orchestration (researcher, writer, reviewer), start a run and read what each step produced. Use when asked to build a multi-agent pipeline or squad, chain agents in sequence, pass one agent's output to the next, write input_mapping, state_mapping or output_mapping, validate an orchestration, start or poll a run, or read a run's node_executions.

Add an approval step to a naturali.ai orchestration so each run parks as awaiting_input until a person approves the proposed tool call. Use when asked to add human-in-the-loop or an approval node to an orchestration, hold a reply or tool call for review before it is sent, route on approved, rejected or expired, read required_action on an awaiting_input run, or check what a parked run did after approval.

Read back what a naturali.ai agent run did - status, error, version, usage and cost, each tool call and its result, the trace tree, continuations and an agent's failed runs. Use when asked why an agent said something, what a run cost, which version answered, which tool call failed, to debug a failed or wrong run, follow a continuation after an approval or tool output, or when a transcript is empty with content_redacted_at set.

Re-answer one turn of a real naturali.ai conversation on its exact history by forking the session onto a fixed agent, leaving the original intact. Use when an agent gave a bad, wrong or evasive answer in a real session, when asked to replay, reproduce, retry or branch a turn, fork a session, test a prompt fix on the context the agent actually saw, compare two agents on one conversation, or list a session's forks.

Constrain a naturali.ai agent to a JSON Schema with output_schema so its generations return a validated object in output.object instead of prose. Use when asked for structured, JSON, typed or schema-validated output, to extract fields with an agent, when prose comes back after setting a schema, or on 502 OUTPUT_SCHEMA_VALIDATION_FAILED or a missing output.object.

Serve a new naturali.ai agent version to a share of traffic beside the current one, then promote or abort it. Use when asked for a canary, staged, gradual or percentage rollout, an A/B split between agent versions, to raise the canary share, see which version served a run, promote or roll back a release, or when promote answers 409 NO_ACTIVE_RELEASE.

Run a naturali.ai agent once, in the background (202 and a generation id to poll) or with wait=true for the result inline. Use when asked to run, call, test or ask a naturali agent something without a session, poll a generation, or when generate answers 502 AI_PROVIDER_ERROR, OUTPUT_SCHEMA_VALIDATION_FAILED, TEXT_ENCODED_TOOL_CALL, 503 model_not_priced, 402 insufficient_credit, 403 plan_limit_reached, 429 QUOTA_EXCEEDED, 409 IDEMPOTENCY_KEY_REUSED or 400 SYSTEM_MESSAGE_NOT_ALLOWED.

Put a naturali.ai agent on a cron schedule with a schedule trigger, fire it by hand, read the firing log and pause it. Use when asked to run an agent every morning, daily, hourly or nightly, create a cron or schedule trigger, fire a trigger by hand, check whether a scheduled run happened, pause or resume a schedule, find why a schedule went inactive, or on 403 plan_limit_reached for trigger or trigger_interval.

Give a naturali.ai agent a client tool that your own code runs - the generation pauses at requires_action, your code submits the result to tool-outputs, and it resumes. Use when an agent must reach a database, internal service or person the platform cannot, when asked for client-side or local function calling, to handle requires_action or required_action.tool_calls, submit tool outputs, or on 409 GENERATION_NOT_AWAITING_TOOL_OUTPUTS.

Measure whether a naturali.ai agent change is good enough to ship with an eval (dataset, llm_judge scorer, pass threshold) run before and after, compared per scorer. Use when asked to test or regression-test an agent, check a prompt change before shipping, compare two eval runs or agent versions, get a pass/fail verdict, read why items failed, or when creating an eval answers 400 VALIDATION_FAILED or a run reports pass_rate null.

Grade naturali.ai agent replies that have no single correct wording with an llm_judge rubric plus a json_logic floor, run in the background. Use when asked to write a rubric or LLM-as-judge, score free-text or open-ended answers, check a rule a string match cannot (tone, no promises), run or poll an eval in the background or over 25 items, read judge reasoning, cancel an eval run, or when items error from an unparseable judge reply.

Search a naturali.ai project's ready documents and memories and read the ranked passages with their score and similarity_score - the retrieval an agent runs before every generation. Use when asked to search the knowledge base, test retrieval or RAG, see what an agent will be shown, pick a min_score or limit, check why an agent ignores its documents, or find which document or chunk answers a question.

Approve, edit or reject a held naturali.ai action from the approvals queue, and find what ran next. Use when asked to approve, reject, sign off, review or edit a pending approval, clear the approvals queue, find why a run is awaiting_input or a tool result says pending_approval, or when approve answers 409 because the item expired or was already settled.

Declare a zero-retention naturali.ai agent (trace_content_mode none) so its prompts, replies and tool payloads are never stored, while tokens and cost still are. Use when asked for zero retention, not storing prompts or replies, PII or compliance-safe agents, no conversation logs, an empty transcript with content_redacted_by_principal_id zero_retention, or erasing content an agent already stored.