Skip to content

naturali-ai/naturali

unversioned · e9be4a057fb6Apache-2.0

Build, run and audit AI agents on naturali.ai: one skill per tutorial step, plus the naturali MCP server.

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, Discord or X, 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.

naturali-answer-from-images-and-audio

Make a naturali.ai agent answer from a photo and a voice recording by uploading them, letting managed conversion turn them into text documents, and scoping the agent's retrieval to them. Use when asked to answer from images, screenshots, receipts, scans, voice memos or audio, OCR or transcribe files for an agent, or when conversion seems off, and on 402 insufficient_credit, 409 FILE_ALREADY_INGESTED or a media document failed.

naturali-attribute-spend-to-end-users

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.

naturali-branch-an-orchestration

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 a run's node executions.

naturali-bring-your-own-model-key

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, vertex or anthropic without a credential.

naturali-build-an-eval-dataset

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.

naturali-call-a-tool-directly

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.

naturali-cap-project-spend

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.

naturali-cap-spend-per-end-user

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".

naturali-chain-playbooks-across-cases

Chain naturali.ai playbooks so one case reads another through upstreams and upstream nodes, fill the chain once at its root, and refresh what a correction left stale. Use when asked to share one client's or property's data across many cases, bind a case to a parent case, propagate a correction downstream, delete a chain in order, or on PLAYBOOK_CASE_UPSTREAM_INVALID, UNKNOWN_UPSTREAM, UPSTREAM_CYCLE, PLAYBOOK_CASE_HAS_DEPENDENTS, PLAYBOOK_HAS_DEPENDENTS or PLAYBOOK_SELF_WRITE.

naturali-connect-a-discord-channel

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, 502 discord_unavailable or a channel gateway_error.

naturali-connect-an-x-channel

Connect an X (Twitter) chat bot to a naturali.ai agent through an x channel so it answers encrypted X Chat direct messages, and prove the round trip on a real DM. Use when asked to connect X or Twitter, answer X DMs with an agent, or find why a naturali X bot does not reply, and on 400 invalid_bot_token, 400 invalid_consumer_credentials, 409 bot_in_use, 429 x_key_registration_limited, 502 x_provisioning_failed or 502 x_unavailable.

naturali-converse-in-a-session

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), 409 IDEMPOTENCY_KEY_REUSED, 410 (expired) or 429 QUOTA_EXCEEDED.

naturali-create-a-project

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.

naturali-create-an-agent

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 or model_not_priced for a model, 400 SYSTEM_MESSAGE_NOT_ALLOWED or 409 AGENT_HAS_DEPENDENTS.

naturali-declare-a-playbook

Declare a naturali.ai playbook (collect, execute, confirm nodes and their typed inputs) in naturali.yaml, open a case per subject, ask what it still misses, write inputs against their revision and run a node by hand. Use when asked to model a per-client or per-contract process as a playbook or case, or on PLAYBOOK_VALIDATION_FAILED, PLAYBOOK_EXECUTOR_FORBIDDEN, PLAYBOOK_INPUT_CONFLICT, PLAYBOOK_INPUT_INVALID, PLAYBOOK_NODE_NOT_RUNNABLE or PLAYBOOK_HAS_CASES.

naturali-deploy-a-formation

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 to deploy, apply, plan, diff, update, inspect 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, LITERAL_CREDENTIAL, plan_feature_not_included or plan_limit_reached.

naturali-enable-naturali-models

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 on catalog_not_ready, managed_source_unavailable, managed_provider_read_only, managed_model_listing or 400 bad_request on a model from another source.

naturali-fill-a-case-per-client

Give a naturali.ai agent a naturali tool confined to one playbook case, so it fills each client's case in conversation, asks only for what is missing, and a correction reruns only the steps that read it. Use when asked to have an agent collect onboarding or intake data, chat a client through a case, pin a tool to a case_id or actor_id, attribute an agent's writes, or on MISSING_TOOL_CONTEXT_KEY or 409 PLAYBOOK_INPUT_CONFLICT from an agent's write.

naturali-gate-a-rollout-on-an-eval

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.

naturali-gate-a-tool-with-guardrails

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.

naturali-give-an-agent-an-http-tool

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 400 LITERAL_CREDENTIAL, 422 FORCED_TOOL_CHOICE_CANNOT_STOP or TOOL_EGRESS_BLOCKED.

naturali-give-an-agent-long-term-memory

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.

naturali-ground-an-agent-in-documents

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.

naturali-invite-a-colleague

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.

naturali-let-an-agent-write-memories

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.

naturali-limit-what-an-agent-may-do

Declare a naturali.ai policy and name it in an agent's policy_ids so the platform refuses actions it takes 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 it writing memory, make it read-only, deny it an IAM action, or on 403 POLICY_GRANT_NOT_HELD, 409 POLICY_HAS_DEPENDENTS or a transcript showing "Forbidden: boundary policy denies".

naturali-make-a-file-searchable

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.

naturali-model-a-process-as-a-workflow

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.

naturali-orchestrate-several-agents

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 list a run's node executions.

naturali-pause-a-run-for-a-human-decision

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.

naturali-read-a-run

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.

naturali-recognise-one-user-across-channels

Make one end user the same naturali.ai actor on a messaging channel (WhatsApp, Discord, X) and in your own app, by binding the channel address to your actor with a one-time code from a message.received webhook. Use when asked to link a phone number or chat account to a signed-in user, share quotas, memory or tools across transports, identify who is talking in a tool, or on 409 actor_minted_for_address or a 400 identifier.

naturali-replay-a-turn

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.

naturali-return-structured-output

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.

naturali-roll-out-an-agent-version

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.

naturali-run-a-generation

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.

naturali-run-an-agent-on-a-schedule

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.

naturali-run-tools-in-your-own-code

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.

naturali-score-an-agent-change

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.

naturali-score-open-ended-answers

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.

naturali-search-knowledge

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.

naturali-settle-an-approval

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.

naturali-sign-in-with-a-provider

Build a Sign in with X (or any OAuth provider) flow on naturali.ai that maps each provider account to one actor, using an oauth_client, an http tool with oauth_connection auth, a provisional actor and external_id lookup. Use when asked to log users in with X, Google or GitHub, connect a user's provider account, call a provider API as the user, or on 400 ACTOR_NOT_FOUND, a callback 400, or a connection pending or disconnected.

naturali-stop-storing-conversation-content

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.