# API Reference Source: https://docs.neuralfactory.ai/api-reference/introduction Integrate Neural Factory into your applications with the REST API. # API Reference The Neural Factory REST API lets you programmatically interact with the platform — send messages to agents, manage knowledge bases, and retrieve analytics data. Agent work runs as a **durable run**: `POST /chat` enqueues a run that a background worker executes, so a request can outlive any single HTTP connection. This page documents that contract end-to-end — how to start a run, the three ways to get its result, human-in-the-loop pauses, cancellation, idempotency, and webhooks. ## Base URL All API requests are made to your Neural Factory instance: ``` https://app.neuralfactory.ai/api/v1 ``` For enterprise deployments, replace with your custom domain. ## Authentication All API requests require authentication using an API key. Include it as a Bearer token in the `Authorization` header: ```bash theme={null} curl -X POST https://app.neuralfactory.ai/api/v1/chat \ -H "Authorization: Bearer $NF_API_KEY" \ -F "agent_id=agt_123" \ -F "message=What is our remote work policy?" ``` API keys are created and managed in the [API Keys](/user-guide/admin/api-keys) section of the admin panel. Keys are **organization-scoped**. A key can only reach agents and runs belonging to its organization; a key with no organization can reach only resources that also have none. Every request is also subject to per-user and per-organization concurrency caps (see [Concurrency limits](#concurrency-limits)). ## Request format * `POST /chat` is **`multipart/form-data`** — it accepts file uploads, so send fields as form parts (`-F` in curl), not a JSON body. * Run-control endpoints that take a body (e.g. `POST /runs/{id}/resume`) accept **`application/json`**. * Dates are ISO 8601 strings; IDs are strings. *** ## The durable-run model `POST /chat` **enqueues** a run and returns a `run_id`. How the initial response behaves depends on two form params, `streaming` and `wait`: | Mode | Params | Response | | - | - | - | | **Stream** | `streaming=true` | An NDJSON stream relayed from the run. Response carries an `x-agent-run-id` header so you can reattach later. | | **Observe** (default) | `streaming=false`, `wait=true` | The request holds open and returns the **completed result** (`200`) if the run finishes within the observe window; otherwise a **`202` run handle** (the run keeps executing). | | **Fire-and-forget** | `streaming=false`, `wait=false` | Returns a **`202` run handle immediately**. | Whichever mode you choose, there are **three ways to obtain the result** of a run that is still executing: 1. **Poll** `GET /runs/{run_id}` until the status is terminal. 2. **Stream** `GET /runs/{run_id}/stream` (Server-Sent Events). 3. **Webhook** — pass `callback_url` on `POST /chat` to receive a terminal push. A dropped connection never cancels a run. Whether you stream, poll, or disconnect, the worker finishes, saves the result, and bills exactly once. Reattach any time with the `run_id`. *** ## POST /chat Start (or continue) an agent run. Encode the body as `multipart/form-data`. ### Form fields | Field | Type | Default | Description | | - | - | - | - | | `message` | string | — | **Required.** The user message. | | `agent_id` | string | — | **Required.** Target agent. | | `chat_id` | string | generated | Conversation id. Omit to start a new conversation (the server returns/uses a new UUID); reuse it to continue one. | | `streaming` | bool | `false` | `true` streams the run as NDJSON. | | `wait` | bool | `true` | Non-streaming only. `false` returns a `202` immediately instead of observing. | | `idempotency_key` | string | — | Retried POSTs with the same key re-attach to the existing run — no duplicate run and **no double billing**. | | `callback_url` | string | — | HTTPS URL to receive terminal/HITL webhooks for this run. | | `on_conflict` | string | `reject` | What to do when the chat already has an active run: `reject` → `409`; `enqueue` → park this message behind it (see [One active run per conversation](#one-active-run-per-conversation)). | | `save_interactions` | bool | `true` | `false` redacts the stored message/response. | | `name`, `email`, `client` | string | — | Optional caller/attribution metadata. | | `files` | file\[] | — | Optional file uploads (repeat the part per file). | ### 202 — run handle Returned by `wait=false`, or by the default observe mode when the run outlives the observe window (still `queued`, `running`, or `awaiting_input`): ```json theme={null} { "run_id": "run_a1b2c3", "chat_id": "chat_xyz", "agent_id": "agt_123", "status": "running", "durable": true, "stream_url": "/runs/run_a1b2c3/stream", "interrupts": [] } ``` `interrupts` lists any **pending** human-in-the-loop requests (empty unless the run paused as `awaiting_input`). ### 200 — completed result When `wait=true` and the run finishes within the observe window, the response is the agent's answer object (the same payload as the `result` field of `GET /runs/{id}`), plus `agent_id` and `usage_status`. A run cancelled within the window returns `{ "run_id", "status": "cancelled", "agent_id" }`; a failed run returns `500` with the error in `detail`. ### One active run per conversation A `chat_id` may have only **one** active run (`queued`, `running`, or `awaiting_input`) at a time — the conversation's checkpoint thread has a single writer. Posting to a chat that is already busy returns `409` with the run that holds it: ```json theme={null} { "detail": { "message": "This chat already has a run in progress", "active_run_id": "run_a1b2c3" } } ``` A message arriving into a busy chat is resolved in a fixed order: 1. **It answers a pending clarification.** If the active run is `awaiting_input` on a clarification, your message *is* the answer: posting it resumes that run rather than conflicting. 2. **`on_conflict=enqueue`.** The message is parked on the active run and started as its own turn the moment that run reaches a terminal status. The response is the **active** run's handle plus the parked record — so a client can send without waiting, and without polling for a gap to slot into. Up to 5 messages may be parked per run; past that you get the `409`. 3. **Otherwise** — `409` as above. Handle it by attaching to `active_run_id` (poll or stream it) and sending once it finishes. A matching `idempotency_key` re-attaches to your own existing run rather than conflicting with it. `POST /runs/{run_id}/followups` with `{"message": "…"}` parks a message against a known run directly — the same behavior addressed by run id. It returns `409` if the run is no longer active or its queue is full, in which case send normally. To run work in parallel, use separate `chat_id`s — subject to the [concurrency limits](#concurrency-limits). ### Streaming (`streaming=true`) Returns `application/x-ndjson` — one JSON object per line — with response headers including `x-agent-run-id: `. Capture that header to reattach (poll/stream/cancel) if the connection drops. ```bash theme={null} curl -N -X POST https://app.neuralfactory.ai/api/v1/chat \ -H "Authorization: Bearer $NF_API_KEY" \ -F "agent_id=agt_123" \ -F "message=Summarize the attached report" \ -F "files=@./report.pdf" \ -F "streaming=true" ``` ### Fire-and-forget with a webhook ```bash theme={null} curl -X POST https://app.neuralfactory.ai/api/v1/chat \ -H "Authorization: Bearer $NF_API_KEY" \ -F "agent_id=agt_123" \ -F "message=Draft the Q3 board deck" \ -F "wait=false" \ -F "idempotency_key=draft-q3-2026-0001" \ -F "callback_url=https://example.com/hooks/nf" ``` *** ## Getting the result ### Poll — GET /runs/ Returns the run's public view. Poll while the status is `queued` or `running`; stop when it is terminal, and **act** (don't poll) when it is `awaiting_input`. ```bash theme={null} curl https://app.neuralfactory.ai/api/v1/runs/$RUN_ID \ -H "Authorization: Bearer $NF_API_KEY" ``` | Field | Description | | - | - | | `run_id`, `chat_id`, `agent_id` | Identifiers. | | `status` | Lifecycle status (see [Run status lifecycle](#run-status-lifecycle)). | | `question` | The initiating message. | | `result` | The agent's answer object once `completed`. | | `files` | Files produced by the run. | | `interrupts` | Pending/decided human-in-the-loop requests. | | `error` | Failure reason when `failed`/`timed_out`. | | `usage` | `{ prompt_tokens, completion_tokens }`. | | `cost` | Billed cost breakdown. | | `resume_attempts` | Times the run was re-dispatched (resume/recovery). | | `active_seconds` | Accumulated active execution time (paused time excluded). | | `child_run_count` | Number of sub-agent tasks this run completed. | | `live_state` | Latest truncated in-flight state snapshot (for rendering an in-progress turn). | | `created_at`, `updated_at` | Timestamps. | Returns `404` if the run does not exist, `403` if it is outside your org scope. ### Stream — GET /runs//stream Server-Sent Events over the run's lifecycle. Heartbeat comments arrive roughly every 15 s to keep proxies open. ```bash theme={null} curl -N https://app.neuralfactory.ai/api/v1/runs/$RUN_ID/stream \ -H "Authorization: Bearer $NF_API_KEY" ``` | Event | Payload | Meaning | | - | - | - | | `init` | `{ run_id, chat_id, agent_id, status, live_state, interrupts }` | Full snapshot sent first (also on every reconnect). | | `step` | `{ run_id, live_state }` | The in-flight state advanced. | | `awaiting_input` | `{ run_id, interrupts }` | The run paused for human input. | | `status` | `{ run_id, status }` | A non-terminal status change. | | `done` | `{ run_id, status, error, cost, files }` | Terminal — fires exactly once, then the stream ends. | | `stream_error` | `{ run_id, error }` | Run not found, or the connection cap (\~1 h) was reached — reconnect or poll. | `Last-Event-ID` is tolerated but is **not** a replay cursor: every reconnect gets a fresh `init` snapshot that supersedes prior state, so clients merge idempotently. There is no missed-event gap to backfill. ### Webhook — callback\_url Pass `callback_url` (HTTPS) on `POST /chat` to receive a push at each **terminal** transition (`completed`, `failed`, `cancelled`, `timed_out`) and at each **pause** (`awaiting_input`). Delivery is exactly-once per state, best-effort with bounded retry on `5xx`, and can never affect the run. ```json theme={null} { "event": "agent_run.terminal", "run_id": "run_a1b2c3", "chat_id": "chat_xyz", "agent_id": "agt_123", "status": "completed", "record_id": "rec_789", "error": null, "cost": { "total_cost": 0.0123 }, "interrupts": [], "ts": "2026-07-22T10:00:00Z" } ``` `event` is `agent_run.awaiting_input` when the run pauses (with `interrupts` populated), otherwise `agent_run.terminal`. **Verify the signature.** When a webhook secret is configured, each delivery carries an HMAC over the raw request body: ``` X-NF-Event: agent-run X-NF-Signature: sha256= ``` Recompute `HMAC-SHA256(secret, raw_body)` and compare (constant-time) against the `sha256=` value before trusting the payload. *** ## Idempotency Network retries of `POST /chat` can otherwise create duplicate runs — and duplicate billing. Send a stable `idempotency_key` and a retried enqueue re-attaches to the original run instead of starting a new one. Use a key derived from the unit of work (e.g. a request id), not a random value per attempt. *** ## Human-in-the-loop (HITL) An agent can pause mid-run for a human decision. The run's status becomes `awaiting_input` and its `interrupts` array lists what is pending. There are two ways to continue, depending on what the agent asked for: **Approvals** — resume with the decision(s): ```bash theme={null} curl -X POST https://app.neuralfactory.ai/api/v1/runs/$RUN_ID/resume \ -H "Authorization: Bearer $NF_API_KEY" \ -H "Content-Type: application/json" \ -d '{"resumes": {"": "approve"}}' ``` The body must decide **exactly** the currently pending interrupt ids — a partial or mismatched set returns `409`, as does a double-submit or a resume that races a cancel. On success the run flips back to `queued` and re-dispatches. An optional `decided_by` records who decided. **Clarifications** — when the agent asked a follow-up question, simply `POST /chat` the next `message` with the **same `chat_id`**; the conversation continues. *** ## Cancelling a run ```bash theme={null} curl -X POST https://app.neuralfactory.ai/api/v1/runs/$RUN_ID/cancel \ -H "Authorization: Bearer $NF_API_KEY" ``` Cancellation is **idempotent** and always returns the run's public view. A `queued` or `awaiting_input` run stops immediately; a `running` run receives a cooperative stop and settles to `cancelled` shortly after; a terminal run is unchanged. *** ## Run status lifecycle ``` queued ──▶ running ──▶ completed | failed | timed_out │ ▲ ▼ │ (resume) awaiting_input ──▶ cancelled ``` | Status | Kind | Meaning | | - | - | - | | `queued` | active | Enqueued, awaiting a worker. | | `running` | active | Executing. | | `awaiting_input` | active | Paused for human input (resume or reply). | | `completed` | terminal | Finished successfully; `result` is populated. | | `failed` | terminal | Errored; see `error`. | | `cancelled` | terminal | Cancelled by request. | | `timed_out` | terminal | Exceeded its active-time cap (1 h by default) **or** its per-run token ceiling. `error` reads "Run stopped at its execution limit." | `awaiting_input` is an active status but does **not** count against concurrency caps — it is a human queue, not worker load. A pause left undecided for 72 hours expires and the run is cancelled. Time limits apply to **active** execution only: a run accrues no time while paused for input, and a crashed-then-resumed run is not charged for the gap. ### List a chat's runs — GET /chats//runs Returns the chat's most recent runs (public view). Pass `active=true` to return only runs that are `queued`, `running`, or `awaiting_input` — useful to reattach to an in-flight turn. ```bash theme={null} curl "https://app.neuralfactory.ai/api/v1/chats/$CHAT_ID/runs?active=true" \ -H "Authorization: Bearer $NF_API_KEY" ``` *** ## Error handling Error responses carry an HTTP status and a `detail` message: ```json theme={null} { "detail": "Description of what went wrong" } ``` ### Common status codes | Code | Meaning | | - | - | | `200` | Success (completed result, or an idempotent cancel/resume view). | | `202` | Accepted — durable run enqueued; use the `run_id` handle to poll/stream/await. | | `400` | Bad request — invalid parameters or malformed resume body. | | `401` | Unauthorized — missing or invalid API key. | | `403` | Forbidden — resource outside your organization scope. | | `404` | Not found. | | `409` | Conflict — the chat already has an active run (body carries `active_run_id`), or a resume did not match the pending interrupts / lost a race. | | `429` | Concurrency/rate limited — includes a `Retry-After` header. | | `500` | Internal server error (also returned when a synchronously observed run failed). | ## Concurrency limits Each API key is capped on concurrently active runs **per user** and **per organization** (`queued` + `running`; `awaiting_input` is excluded). For direct-API keys the per-user cap is attributed to the key owner, so varying `name`/`email` cannot escape it. Exceeding a cap returns `429 Too Many Requests` with a `Retry-After` header (seconds): ``` HTTP/1.1 429 Too Many Requests Retry-After: 30 ``` Back off for the indicated interval, or wait for an in-flight run to finish, before retrying. # Contact Support Source: https://docs.neuralfactory.ai/help/contact Get in touch with the Neural Factory support team. # Contact Support Can't find what you need in the documentation? Our support team is here to help. ## Support channels Send us an email at **[support@neuralfactory.ai](mailto:support@neuralfactory.ai)** We typically respond within one business day. Visit **[neuralfactory.ai](https://neuralfactory.ai)** for the latest product information, blog posts, and announcements. ## When contacting support To help us resolve your issue quickly, please include: 1. **Your organization name** and deployment type (Enterprise or SaaS) 2. **A clear description** of the issue or question 3. **Steps to reproduce** — What were you doing when the issue occurred? 4. **Screenshots or error messages** — Include any error codes or messages you saw 5. **Browser and device info** — Which browser and operating system you're using 6. **Agent/KB names** — If the issue involves specific agents or knowledge bases ## Reporting bugs If you've found a bug, we want to know about it. Email [support@neuralfactory.ai](mailto:support@neuralfactory.ai) with: * What you expected to happen * What actually happened * Steps to reproduce the bug * Screenshots if possible ## Feature requests Have an idea for how we can improve Neural Factory? We'd love to hear it. Send feature requests to [support@neuralfactory.ai](mailto:support@neuralfactory.ai) with a description of the feature and how it would help your workflow. ## Enterprise support Enterprise customers have access to dedicated support channels as defined in their service agreement. Contact your account manager for priority support. # Account & Access FAQ Source: https://docs.neuralfactory.ai/help/faq/account-and-access Questions about signing in, SSO, organizations, and invitations. # Account & Access FAQ It depends on your deployment: * **Enterprise**: Use your organization's Azure AD single sign-on (SSO). Click "Sign in with Microsoft" and use your corporate credentials. * **SaaS**: Sign in with your email and password at [app.neuralfactory.ai](https://app.neuralfactory.ai). On the sign-in page, click **"Forgot password?"** and enter your email address. You'll receive a password reset link. Enterprise users should contact their IT department, as passwords are managed through Azure AD. * **Enterprise**: You're automatically added when you sign in with Azure AD for the first time. * **SaaS**: An administrator must invite you. Check your email for an invitation link. If you don't have one, ask your organization's Neural Factory admin to send an invite. Sign up at [app.neuralfactory.ai](https://app.neuralfactory.ai) and follow the onboarding flow. The first user who signs up creates the organization and becomes its Admin. Each account belongs to one organization. If you need access to multiple organizations, you would use separate accounts. Only Admins can change user roles. Ask your organization's administrator to update your role in the [User Management](/user-guide/admin/user-management) section. You may not have access to all resources. Agents and knowledge bases can be restricted to specific groups. Ask your administrator which groups you belong to and whether you need to be added to additional groups. # Agents & Chat FAQ Source: https://docs.neuralfactory.ai/help/faq/agents-and-chat Questions about agent behavior, citations, background tasks, and chat features. # Agents & Chat FAQ Citations appear only when the agent retrieves information from a knowledge base. If there are no citations: * The agent may not have a knowledge base connected * Your question may not have matched any documents * The agent answered from its general AI knowledge instead * The agent may be configured without knowledge search enabled Ask your administrator to verify the agent's knowledge base and tool configuration. 1. Click **thumbs down** on the response to flag it 2. If the information should be in a knowledge base, verify the source document is uploaded and indexed 3. Report the issue to your administrator — they can review the interaction in the analytics dashboard and adjust the agent's configuration See [Agent Issues](/help/troubleshooting/agent-issues) for more troubleshooting steps. Each conversation is with a single agent. To talk to a different agent, start a new chat and select the other agent. However, if your organization uses a [multi-agent orchestrator](/user-guide/agents/multi-agent-workflows), the orchestrator automatically routes your questions to the appropriate specialist behind the scenes. There's no strict character limit on messages, but very long messages may be truncated to fit the AI model's context window. For best results, keep messages focused and break complex requests into multiple messages. Your conversations are visible to you and to your organization's administrators (who can review them in the analytics dashboard). Other members cannot see your conversations. Currently, conversations are tied to individual users. If you need to share an answer, use the **Copy** button on a response to copy the text to your clipboard. Response speed depends on several factors: * **Model choice** — More capable models may be slower * **Tool usage** — Searching knowledge bases or external tools adds time * **Response length** — Longer answers take more time to generate * **Server load** — High usage periods may affect response times You don't have to watch it work — the task runs on our servers, so you can go do something else and come back to the finished answer. See [Agent Issues](/help/troubleshooting/agent-issues) for troubleshooting. Nothing is lost. Agent tasks run on our servers, not in your browser, so closing the tab, reloading, switching device, or dropping your connection doesn't cancel the work. Reopen the conversation and it reattaches to the task in progress, picking up the answer as it streams. If the task finished while you were away, the answer is already saved in the thread. Don't resend the message — that starts a second task, billed separately. While a task is running, the send button becomes a **Stop** button. Press it and the agent finishes the step it's on, then stops — you'll briefly see **Stopping...** while it settles. Stopping is real cancellation, not just hiding the output. Work completed before you stopped is still billed, so stopping early on a task that's heading the wrong way saves money. Agents can pause mid-task when they need a person. There are two kinds: * **A question** — Answer it with a normal chat message and the task continues from where it paused * **An approval request** — Approve or reject using the controls shown with the request A paused task uses no compute and isn't counted against your parallel-task limit. If nobody answers within 72 hours, the pause expires and the task is cancelled — just send the request again. Yes — type it and it's queued. Each conversation runs one agent task at a time, so your message is held and sent automatically as soon as the current task finishes. To send it right away, stop the running task first. To genuinely work in parallel, start a separate conversation — subject to your plan's limit on parallel agent tasks. Up to about an hour of active work, with a ceiling on the total tokens a single task may consume. A task that reaches either limit stops and reports **Run stopped at its execution limit.** rather than running indefinitely. Time spent paused waiting on you doesn't count toward the hour. If you hit the limit regularly, break the request into smaller tasks. Your plan allows a certain number of agent tasks running **at the same time**, and they're all currently busy. This isn't a monthly quota — it clears as soon as one of them finishes, usually within seconds or minutes. Wait for a task to finish, or stop one you no longer need. Tasks paused waiting on you don't count toward the limit. For a higher allowance, upgrade your plan (SaaS) or ask your administrator (Enterprise). # Billing FAQ Source: https://docs.neuralfactory.ai/help/faq/billing Questions about plans, payments, and cancellation (SaaS only). # Billing FAQ Billing questions apply to **SaaS deployments** only. Enterprise customers have license-based pricing — contact your account manager for billing inquiries. Neural Factory SaaS offers: * **Individual** — For single users, with basic limits on agents, knowledge bases, storage, and parallel agent tasks * **Organization** — For teams, with higher limits and multiple user support Visit the pricing page or the Billing section in the admin panel for current pricing and plan details. Billing is handled through **Polar**, our payment provider. You're billed monthly or annually depending on your plan selection. Usage is tracked against your plan limits throughout the billing cycle. Yes. Navigate to **Billing** in the admin panel and click **Upgrade Plan** or **Change Plan**. Upgrades take effect immediately. Downgrades take effect at the start of the next billing cycle. When you reach a plan limit: * **Message limit** — Users cannot send new chat messages * **Storage limit** — New document uploads are blocked * **API call limit** — API requests return rate-limit errors * **Parallel agent tasks** — Starting another agent task is refused until one of your running tasks finishes For the first three, upgrade your plan to increase the limit, or wait for the next billing cycle to reset it. The parallel-task limit works differently: it caps how many agent tasks you can run **at the same time**, so it clears within seconds or minutes as soon as a running task finishes — waiting for the billing cycle isn't necessary. Stop a task you no longer need, or upgrade for a higher allowance. Yes — and you don't lose the answer. Agent tasks run on our servers, not in your browser: closing the tab or losing your connection doesn't cancel the work. The task finishes, the answer is saved to the conversation for when you return, and it's billed once for what it consumed. Yes, for the work completed before it stopped or failed — model tokens already spent can't be reclaimed. Stopping still saves money compared with letting a task you don't need run to completion. Watching the same task from several tabs or reconnecting to it doesn't bill you more than once. Sending the same message a second time, however, starts a second task with its own charge. Navigate to **Billing** → **Cancel Subscription** and confirm. Your access continues until the end of the current billing period. After that, your organization enters a read-only state — you can still view your data but cannot send messages or upload documents. Refund policies are handled through Polar. Contact [support@neuralfactory.ai](mailto:support@neuralfactory.ai) for refund requests. Contact [support@neuralfactory.ai](mailto:support@neuralfactory.ai) or visit our website for current trial availability and promotional offers. # General FAQ Source: https://docs.neuralfactory.ai/help/faq/general Frequently asked questions about Neural Factory. # General FAQ Neural Factory is an enterprise AI platform that lets organizations create intelligent AI assistants (agents) grounded in their own data. Agents search your documents, use connected tools, and provide cited answers through natural conversation. Neural Factory agents are grounded in **your organization's data**. Unlike general-purpose chatbots, NF agents: * Search your internal documents and cite specific sources * Respect your organization's access controls and permissions * Connect to your existing tools (Jira, Confluence, Outlook, etc.) * Can be customized with specific instructions, knowledge, and behavior * Keep your data private — it's not used to train AI models Neural Factory supports multiple AI models including: * **Azure OpenAI**: GPT-4o, GPT-4.1, o-series reasoning models, GPT-5 * **Azure Anthropic**: Claude models Administrators choose which model each agent uses based on the task requirements. Yes. Neural Factory is designed for enterprise security: * Your documents are stored in your organization's isolated environment * Data is encrypted at rest and in transit * Access controls ensure only authorized users see sensitive information * Your data is never used to train AI models * Enterprise deployments can be hosted on your own infrastructure * **SaaS** — Hosted on Neural Factory's cloud infrastructure, pay-as-you-go * **Enterprise** — Dedicated deployment with Azure AD integration, can be on-premise or dedicated cloud See [Organizations](/user-guide/concepts/organizations) for details on deployment modes. Neural Factory's AI models support many languages. The quality of responses depends on the underlying model's capabilities for each language. The platform interface is currently in English. # Knowledge Bases FAQ Source: https://docs.neuralfactory.ai/help/faq/knowledge-bases Questions about supported formats, indexing, sync, and data handling. # Knowledge Bases FAQ Neural Factory supports: * **PDF** (`.pdf`) — Text-based and scanned (with OCR) * **Word** (`.docx`, `.doc`) * **Excel** (`.xlsx`, `.xls`) * **PowerPoint** (`.pptx`) * **Text** (`.txt`) * **CSV** (`.csv`) Indexing time depends on file size, type, and queue depth: * Small text files: seconds * Standard PDFs (1–10 MB): 10–60 seconds * Large documents (10–50 MB): 1–5 minutes * Bulk uploads (100+ files): 10–30 minutes Monitor progress on the knowledge base detail page. Sync frequency depends on the datasource configuration: * **Manual** — Only when you click "Sync Now" * **Automatic** — Periodically checks for changes (frequency depends on configuration) You can trigger a manual sync at any time from the datasource settings. No. Password-protected or encrypted PDFs cannot be processed. Remove the password protection before uploading. When you delete a document: 1. The file is removed from storage 2. All indexed chunks are removed from the vector store 3. The agent can no longer find or cite content from that document Deletion is permanent and cannot be undone. File size limits depend on your deployment: * **Enterprise**: Configured per deployment * **SaaS**: Varies by subscription plan If you encounter a file size error, try splitting large documents into smaller files. Yes. A knowledge base can be connected to multiple agents. This is common when different agents need access to the same underlying documents but with different system prompts or tools. Neural Factory uses **hybrid retrieval**: 1. **Semantic search** finds content that is conceptually similar to the query 2. **Keyword search** finds content containing the exact terms 3. **Reranking** re-scores results using a dedicated reranker model for optimal relevance This combination delivers better results than either approach alone. # Help & Support Source: https://docs.neuralfactory.ai/help/index Find answers, troubleshoot issues, and get in touch with the Neural Factory team. # Help & Support Welcome to the Neural Factory support center. Find answers to common questions, troubleshoot issues, or reach out to our team for help. Answers to the most frequently asked questions about Neural Factory. Step-by-step guides to resolve common issues. Reach our support team for help with your specific situation. ## FAQ topics What is Neural Factory, how it works, and pricing overview. Sign-in, SSO, organization setup, and invitations. Agent behavior, citations, conversation limits, and features. Supported formats, indexing, sync frequency, and data handling. Plans, payments, cancellation, and usage limits (SaaS only). ## Troubleshooting guides Error codes and what they mean. Agent not responding, slow, or giving wrong answers. Upload failures and indexing problems. Datasource and toolkit connection failures. # Agent Issues Source: https://docs.neuralfactory.ai/help/troubleshooting/agent-issues Troubleshoot agents that aren't responding, are slow, or give wrong answers. # Agent Issues This guide helps you diagnose and resolve common agent-related problems. ## Agent not responding **Symptoms**: You send a message and nothing happens, or you see an error message. Don't resend the message as a first step. Each send starts a **separate agent task** that is billed independently and occupies one of your parallel-task slots. Reopen the chat first to see whether the original is still running. **Possible causes and fixes**: 1. **The task is still running** — Agent tasks run on the server, not in your browser. If your connection dropped or you reloaded the page, reopen the conversation: it reattaches to the task in progress and continues showing the answer. Nothing was lost. 2. **The task is queued** — If you see **Queued...**, you're at your plan's limit for parallel agent tasks. Wait for one to finish, or stop one you no longer need. 3. **AI model service issue** — The underlying AI model may be temporarily unavailable. Wait a minute, then send again. 4. **Agent configuration error** — The agent may have an invalid configuration. An administrator should check the agent's settings in the Agents page. 5. **Tool failure** — A tool the agent is trying to use may be failing. Check toolkit connections in the admin panel. ## Agent responding slowly **Symptoms**: The agent takes a long time before text starts appearing. **Possible causes and fixes**: 1. **Complex tool usage** — If the agent is searching knowledge bases, calling external tools, or executing code, each step adds time. This is normal behavior. You don't have to wait on the page — the task keeps running if you navigate away, and the answer is saved to the conversation either way. 2. **Large context** — Long conversations with many messages create a larger context for the model to process. If the current conversation has become very long, **stop the running task first**, then start a new conversation — otherwise the old task keeps running and keeps consuming a parallel-task slot. 3. **Model selection** — More capable models (reasoning models, larger models) can be slower. An administrator can try a faster model if speed is a priority. 4. **Server load** — During peak usage, response times may increase. ## Task stopped at its execution limit **Symptoms**: The turn ends with **Run stopped at its execution limit.** instead of an answer. An agent task has an upper bound on how long it can actively run (one hour by default) and on how many tokens it may consume in total. A task that reaches either limit is stopped and reported rather than left running indefinitely. **Possible causes and fixes**: 1. **The task was too broad** — Split it into smaller requests ("summarize these five documents" → one document at a time). 2. **A loop** — An agent repeatedly retrying a failing tool can burn the budget without progressing. Check whether the toolkit it depends on is healthy. 3. **Very large sources** — Narrow the knowledge base or the attached files so each step handles less material. Work already done up to the limit is billed, so prefer stopping a task you know is going nowhere over letting it run to the cap. ## The agent is waiting on you **Symptoms**: The task pauses and the agent asks a question, or asks you to approve an action. This is intentional — agents can pause mid-task for a human decision, and no compute is used while paused. 1. **A question** — Answer it with a normal chat message; the task continues from where it paused. 2. **An approval request** — Use the approve or reject control shown with the request. 3. **It expires** — A pause left unanswered for 72 hours is cancelled automatically. Send the request again if that happens. ## Stop is stuck on "Stopping..." **Symptoms**: You pressed Stop and the task shows **Stopping...** for a few seconds. Stopping is cooperative: the agent finishes the step it is on (an in-flight model or tool call) and then stops cleanly, rather than being killed mid-write. It normally settles within a few seconds. Work completed before the stop is billed. ## A follow-up message hasn't been sent **Symptoms**: You typed a message while the agent was working and it hasn't been sent. A conversation runs one agent task at a time. A message typed during an active task is held and sent automatically when that task finishes. To send it sooner, stop the running task. ## Agent giving wrong or irrelevant answers **Symptoms**: The agent provides incorrect information, ignores your question, or goes off-topic. **Possible causes and fixes**: 1. **Missing knowledge** — The relevant documents may not be in the connected knowledge base. Check that the KB contains the information and that it's been indexed. 2. **Poor system prompt** — The agent's instructions may not be clear enough. An administrator should review and refine the system prompt. 3. **Wrong agent** — You may be chatting with an agent that isn't designed for your question type. Try selecting a different agent. 4. **Strict mode** — If the agent is in [strict mode](/user-guide/agents/strict-mode) and can't find relevant documents, it will decline to answer rather than guess. 5. **Outdated documents** — The knowledge base may contain outdated information. Verify documents are current. ## Agent not using knowledge base **Symptoms**: The agent responds but doesn't cite any sources, even for questions that should match documents. **Possible causes and fixes**: 1. **Knowledge search not enabled** — Verify the agent has the knowledge search tool enabled. 2. **No knowledge base connected** — Verify at least one KB is connected to the agent. 3. **KB not indexed** — Check the knowledge base's indexing status — documents may still be processing. 4. **KB access control** — You may not have access to the KB. Check your group memberships. 5. **Query mismatch** — Your question may not match the documents well. Try rephrasing. ## Reporting persistent issues If issues persist after troubleshooting: 1. Note the agent name, your message, and the error/behavior 2. Note when the turn ran — support can trace the individual agent task from the conversation and time 3. Check the [Analytics](/user-guide/admin/analytics) dashboard for the interaction details 4. Contact [support@neuralfactory.ai](mailto:support@neuralfactory.ai) with this information # Common Errors Source: https://docs.neuralfactory.ai/help/troubleshooting/common-errors Error codes and messages you might encounter, and what they mean. # Common Errors This page lists the most common error messages in Neural Factory and how to resolve them. ## Authentication errors ### "Session expired" / "Please sign in again" Your authentication session has timed out. Sign out and sign back in. If this happens frequently, clear your browser cookies for the Neural Factory domain. ### "Unauthorized" (401) Your request was not authenticated. Possible causes: * You're not signed in * Your API key is invalid or expired * Your session token has expired **Fix**: Sign in again, or verify your API key is correct and active. ### "Forbidden" (403) You don't have permission to perform this action. Possible causes: * You're trying to access an admin feature as a Member * The agent or knowledge base is restricted to groups you don't belong to * Your API key doesn't have the required permissions **Fix**: Contact your administrator to check your role and group memberships. ## Resource errors ### "Not found" (404) The requested resource doesn't exist. Possible causes: * The agent, knowledge base, or conversation was deleted * The URL is incorrect * You're trying to access a resource in a different organization ### "Rate limited" (429) You've exceeded the request rate limit. Wait for the time specified in the `Retry-After` header before retrying. If you consistently hit rate limits, consider upgrading your plan (SaaS) or contact your administrator (Enterprise). ### "You've reached your limit of parallel agent tasks" (429) A different limit that returns the same status code. This one is about how many agent tasks you may run **at the same time**, not how fast you send requests — so it clears as soon as a running task finishes, not at the end of a billing cycle. Over the API the message names the numbers, for example: "You already have 10 agent runs in progress (your limit is 10)." **Fix**: Wait for a task to finish, or stop one you no longer need. Tasks paused waiting on you don't count toward the limit. If you hit this routinely, raise the limit by upgrading your plan (SaaS) or ask your administrator (Enterprise). See [Billing](/user-guide/admin/billing) for the per-plan allowance. ## Server errors ### "Internal server error" (500) Something went wrong on the server. This is usually temporary. Steps: 1. Wait a moment and try again 2. If the error persists, check if the issue is specific to one agent or feature 3. Contact [support@neuralfactory.ai](mailto:support@neuralfactory.ai) if the error continues ### "Service unavailable" (503) The platform is temporarily unavailable, usually due to maintenance or high load. Try again in a few minutes. ## Chat errors ### "Agent failed to respond" The agent encountered an error while processing your message, and the failure is reported on the turn itself. Possible causes: * The AI model service is temporarily unavailable * The agent's configuration has an issue * A connected tool or datasource is failing **Fix**: Reopen the conversation first — if the task is still running, the answer is still coming and resending would start a second task that is billed separately. Once the turn has actually failed, send the message again; if it keeps failing, try a different agent or contact your administrator. A failed task is billed for the work it completed before failing. ### "Run stopped at its execution limit." The task hit its maximum active running time (one hour by default) or its total token ceiling, and was stopped. Split the request into smaller tasks, or narrow the documents and tools it has to work through. See [Agent Issues](/help/troubleshooting/agent-issues) for the full walkthrough. ### "Message too long" Your message exceeds the maximum allowed length. Shorten your message or break it into multiple messages. # Connection Problems Source: https://docs.neuralfactory.ai/help/troubleshooting/connection-problems Troubleshoot datasource and toolkit connection failures. # Connection Problems This guide helps you resolve issues connecting to external services like SharePoint, Google Drive, Jira, Confluence, and other toolkit integrations. ## OAuth authentication failures ### "Authentication failed" during connection * **Browser popups blocked** — OAuth flows open a popup window. Ensure your browser allows popups for the Neural Factory domain. * **Third-party cookies** — Some browsers block third-party cookies by default. Allow cookies for the authentication provider's domain. * **Account permissions** — The account you're authenticating with must have the necessary permissions in the external service. * **Network restrictions** — Corporate firewalls or VPNs may block the OAuth redirect. Try on a different network if possible. ### Connection worked before but stopped OAuth tokens expire periodically. To fix: 1. Navigate to **Toolkits** and find the affected connection 2. Click **Reconnect** or **Re-authorize** 3. Complete the OAuth flow again with your credentials ## SharePoint connection issues ### "Access denied" when connecting SharePoint * Verify the authenticated account has at least **Read** access to the target SharePoint site * Your Azure AD administrator may need to grant consent for the Neural Factory application * Check if the site has specific access policies that restrict external applications ### SharePoint site not appearing in browser * The site may be a private or restricted site — ensure the authenticated account has access * Try entering the site URL directly instead of browsing ## Google Drive connection issues ### "Permission denied" when connecting Google Drive * The Google account must have at least **Viewer** access to the target folder * Google Workspace administrators may need to allow the Neural Factory application * Check if the folder is in a Shared Drive with restricted sharing settings ## Jira / Confluence connection issues ### "Connection test failed" * Verify the Jira/Confluence instance URL is correct * Ensure the authenticated account has API access enabled * Check if the Atlassian instance has IP allowlisting that blocks Neural Factory's servers ## General troubleshooting steps 1. **Re-authorize the connection** — Token expiry is the most common cause 2. **Check the external service** — Verify the service itself is accessible and not experiencing downtime 3. **Review permissions** — Ensure the authenticated account has the required access level 4. **Check network/firewall** — Corporate networks may block connections to external services 5. **Contact support** — If none of the above resolves the issue, contact [support@neuralfactory.ai](mailto:support@neuralfactory.ai) with the error details # Document Processing Source: https://docs.neuralfactory.ai/help/troubleshooting/document-processing Troubleshoot document upload failures and indexing issues. # Document Processing Issues This guide helps you resolve problems with uploading, processing, and indexing documents in knowledge bases. ## Upload failures ### File upload doesn't start * **Check file size** — The file may exceed the maximum allowed size for your plan * **Check file format** — Ensure the file is in a supported format (PDF, DOCX, XLSX, TXT, PPTX, CSV) * **Browser issues** — Try a different browser or clear your browser cache * **Network issues** — Check your internet connection; large files need a stable connection ### Upload starts but fails midway * **Network instability** — A network interruption during upload. Try again with a stable connection. * **File corruption** — The file may be damaged. Try opening it locally to verify, then re-upload. * **Server timeout** — Very large files may time out. Try splitting the document into smaller files. ## Indexing issues ### Document stuck in "Processing" If a document stays in "Processing" status for an unusually long time: 1. **Wait** — Large documents or bulk uploads may take longer. Allow up to 30 minutes for large batches. 2. **Check the queue** — If many documents were uploaded simultaneously, they're processed sequentially. 3. **Retry** — Delete the document and upload it again. 4. **Contact support** — If it's still stuck after retrying, there may be a backend issue. ### Document status is "Failed" Common reasons for processing failures: | Cause | Solution | | - | - | | Unsupported format | Convert to a supported format (PDF, DOCX, etc.) | | Corrupted file | Repair or re-export the file from its source application | | Password-protected PDF | Remove password protection before uploading | | Encrypted document | Decrypt the document before uploading | | Empty file | Ensure the file has actual content | | Unreadable scan | For scanned PDFs, ensure the scan quality is adequate for OCR | ### Documents indexed but not found in search If documents show "Indexed" status but the agent can't find them: 1. **Wait a moment** — There may be a brief delay between indexing and searchability 2. **Check your query** — Try different phrasings; the content may not match your exact wording 3. **Check access control** — You may not have access to the knowledge base 4. **Verify content** — Open the original document and confirm the information you're looking for is actually in the text (not just in images or headers) ## SharePoint / Google Drive sync issues ### Sync not picking up new files * Verify the files are in the folder/library that was selected during datasource configuration * For auto-sync, wait for the next sync cycle * Trigger a manual sync from the datasource settings * Verify the connection credentials haven't expired (re-authorize if needed) ### Previously synced files missing * The file may have been moved or deleted in the source system * The connection may need re-authorization * Check the datasource sync status for error messages # Analytics Source: https://docs.neuralfactory.ai/user-guide/admin/analytics Monitor platform usage with interaction logs and usage charts. # Analytics The Analytics section gives administrators visibility into platform usage — conversations, agent performance, and usage patterns. ## Interactions log The interactions log records all conversations: * **User** — Who initiated the conversation * **Agent** — Which agent was used * **Timestamp** — When the conversation happened * **Message count** — Number of messages * **Feedback** — User ratings (thumbs up/down) Analytics interactions log Click any interaction to open its record: the request and the response, the person and the agent version behind it, and a step-by-step timeline of what the agent did — model calls, tools, delegated sub-agents, and human decisions — with each step's input and output. The record is sealed when the turn ends and checked for changes every time it is opened. ### Filtering interactions Use filters to narrow the log: * **Date range** — View interactions from a specific time period * **Agent** — Filter by specific agent * **User** — Filter by specific user * **Feedback** — Show only positively or negatively rated interactions ## Usage charts Visual dashboards showing platform usage trends: * **Conversations over time** — Daily/weekly/monthly conversation volume * **Messages per conversation** — Average conversation length * **Agent usage distribution** — Which agents are used most * **Active users** — Unique users per time period * **Token usage** — AI model token consumption over time Analytics usage charts ## Using analytics to improve * **Identify popular agents** and those that need attention * **Find low-rated interactions** to diagnose configuration issues * **Track adoption** as you roll out new agents or knowledge bases * **Monitor costs** through token usage trends * **Justify investment** with usage data showing platform value # API Keys Source: https://docs.neuralfactory.ai/user-guide/admin/api-keys Create and manage API keys for programmatic access. # API Keys API keys allow your applications to access Neural Factory programmatically via the REST API. Administrators can create, manage, and revoke API keys from the **API Keys** section. ## Creating an API key Open **API Keys** from the sidebar (admin section). Click the **Create API Key** button. * **Name** — A descriptive name to identify this key (e.g., "Production Backend", "CI/CD Pipeline") * **Permissions** — Select what the key can access (varies by deployment) The API key is displayed once after creation. **Copy it immediately** — you won't be able to see it again. Store your API key securely. Do not commit it to version control, share it in chat, or include it in client-side code. ## Managing API keys The API Keys page shows all active keys: * **Name** — The descriptive name you gave the key * **Created** — When the key was created * **Last used** — When the key was last used for an API call * **Status** — Active or Revoked ### Revoking a key To revoke an API key: 1. Find the key in the list 2. Click **Revoke** 3. Confirm the action Revoked keys immediately stop working. Any application using the key will receive authentication errors. ## Using API keys Include the API key in your API requests as a Bearer token in the Authorization header: ```bash theme={null} curl -H "Authorization: Bearer your-api-key" \ https://app.neuralfactory.ai/api/v1/chat ``` Agent work is asynchronous: `POST /chat` starts a task and returns a handle, which you then poll, stream, or receive by webhook. See [The durable-run model](/api-reference/introduction#the-durable-run-model) for the request format and the three ways to collect a result. See the [API Reference](/api-reference/introduction) for full documentation on available endpoints. ## Best practices * Create separate keys for each application or environment * Rotate keys periodically — revoke old keys and create new ones * Monitor the "Last used" column to identify unused keys * Revoke keys immediately if they may have been compromised * Send an `idempotency_key` when retrying a request, so a network retry re-attaches to the original task instead of starting — and billing — a second one * Expect `429` responses: keys are subject to the same [parallel-task limits](/api-reference/introduction#concurrency-limits) as the UI, counted against the key's owner, so back off on `Retry-After` rather than retrying immediately # Billing Source: https://docs.neuralfactory.ai/user-guide/admin/billing Manage your subscription, plans, and usage limits (SaaS only). # Billing Billing is only applicable to **SaaS deployments**. Enterprise deployments use license-based pricing without in-app billing. The Billing section lets administrators manage their organization's subscription, view usage against plan limits, and update payment information. ## Plans Neural Factory SaaS offers two plan types: | | Organization | Individual | | - | - | - | | **Users** | Multiple users | Single user | | **Agents** | Unlimited agents | Limited agents | | **Knowledge bases** | Unlimited KBs | Limited KBs | | **Storage** | Higher storage limits | Basic storage | | **Parallel agent tasks** | Higher per-user allowance, plus an organization-wide ceiling | Lower per-user allowance | | **Support** | Priority support | Standard support | ## Viewing usage The billing dashboard shows: * **Current plan** — Your active subscription plan * **Billing period** — Current billing cycle dates * **Usage** — How much of your plan limits you've used: * Messages sent * Documents indexed * Storage consumed * API calls made * Tokens consumed by agent tasks ## Agent task billing Each turn you send runs as an agent task on the server, and it is billed for the model tokens and tools it actually consumed. Three consequences are worth knowing: * **Closing the tab doesn't stop the meter — or lose the answer.** The task keeps running server-side, its result is saved to the conversation, and it is billed once. Leaving the page neither cancels the work nor avoids the charge. * **Stopped and failed tasks still bill for work already done.** Stopping is the right move when a task is going nowhere, but it refunds nothing already spent. * **A task is billed exactly once.** Reconnecting, reloading, or watching the same task from several places doesn't multiply the cost. Sending the same message *again*, however, starts a second task with its own bill. ## Managing your subscription ### Upgrading your plan 1. Navigate to **Billing** in the sidebar 2. Click **Upgrade Plan** 3. Select the new plan 4. Confirm and update payment if needed Upgrades take effect immediately. Usage limits are increased right away. ### Updating payment 1. Navigate to **Billing** 2. Click **Payment Method** 3. Update your card or payment details Payment is processed through Polar, our payment provider. ### Cancelling 1. Navigate to **Billing** 2. Click **Cancel Subscription** 3. Confirm the cancellation Your access continues until the end of the current billing period. After that, your organization enters a read-only state. ## Usage limits When you approach or reach a plan limit, you'll see warnings in the interface. If a limit is reached: * **Message limit** — Users cannot send new messages until the next billing cycle or an upgrade * **Storage limit** — New document uploads are blocked * **API limit** — API calls return rate-limit errors * **Parallel agent tasks** — Starting another task is refused until one of the running tasks finishes The first three are **quota** limits: they measure consumption over the billing period and reset when it rolls over. The last is a **concurrency** limit — a ceiling on how many agent tasks one user (and, for organizations, one organization) may have running simultaneously. It doesn't accumulate and it doesn't wait for the billing cycle: it clears the moment a running task finishes. Tasks paused waiting on a person don't count toward it. Because a concurrency limit is hit at the moment of sending rather than approached gradually, users see it as an error on send — "You've reached your limit of parallel agent tasks" — with no advance warning. If your users hit it often, raise the allowance with an upgrade rather than treating it as a fault. Monitor the billing dashboard regularly and upgrade proactively to avoid disruptions. # User Management Source: https://docs.neuralfactory.ai/user-guide/admin/user-management Invite users, manage roles, and organize groups. # User Management Administrators manage users and groups from the **User Management** section in the sidebar. ## Users tab ### Viewing users The Users tab shows all users in your organization: * **Name** and **email** * **Role** (Admin or Member) * **Status** (Active, Invited, Deactivated) * **Last active** date ### Inviting users (SaaS) In SaaS deployments, administrators invite users manually: 1. Click **Invite User** 2. Enter the user's email address 3. Select their role (Admin or Member) 4. Click **Send Invitation** The user receives an email invitation to join the organization. ### Enterprise user provisioning In enterprise deployments, users are provisioned automatically via Azure AD. When a user signs in with their corporate credentials for the first time, they are automatically added to the organization. Role assignments are mapped from AD groups or directory roles. ### Managing roles To change a user's role: 1. Find the user in the list 2. Click the role indicator or edit action 3. Select the new role 4. Save the change ### Deactivating users To remove a user's access: 1. Find the user in the list 2. Click the deactivate or remove action 3. Confirm Deactivated users can no longer sign in or access any resources. Their conversation history is preserved. ## Groups tab ### Creating groups 1. Switch to the **Groups** tab 2. Click **Create Group** 3. Enter a group name and optional description 4. Click **Create** ### Managing group membership 1. Click on a group to open its details 2. Click **Add Members** 3. Search for and select users 4. Click **Save** To remove a member, click the remove action next to their name in the group detail view. ### Enterprise: Azure AD sync In enterprise deployments, groups are synced from Azure AD. Manually created groups can supplement AD groups, but AD-synced groups and their memberships are managed in Azure AD. # Agent Access Control Source: https://docs.neuralfactory.ai/user-guide/agents/agent-access-control Control which users and groups can access specific agents. # Agent Access Control The agent's creator and organization administrators can restrict which users and groups can see and interact with specific agents. This ensures that sensitive or specialized agents are only available to the right people. ## Who can manage access * **Agent creator and organization admins** — set visibility and pick the allowed users and groups, on the create form and on the edit page * **Anyone else with access** — can chat with the agent but cannot change who else has access * **Viewers** — read-only: can chat with agents shared with them, cannot change any settings A member who creates a private agent shares it directly with the colleagues or groups who need it — no admin involvement is required. ## Visibility settings Each agent has a visibility configuration: * **All users** (default) — Everyone in the organization can see and chat with the agent * **Specific groups** — Only members of selected groups can access the agent * **Specific users** — Only individually selected users can access the agent ## Setting access restrictions 1. Navigate to **Agents** and edit the agent you want to restrict (you must be its creator or an admin) 2. Scroll to the **Access Control** section 3. Choose the visibility mode: * Select **Groups** and choose the groups that should have access * Select **Users** and pick individual users 4. Click **Save** Users who don't have access will not see the agent in their agent picker and cannot start conversations with it. ## How group-based access works When an agent is restricted to specific groups: * A user must be a member of **at least one** of the allowed groups to access the agent * If the user is in multiple groups, they only need one to match * Administrators always have visibility into all agents regardless of group restrictions ## Enterprise: Azure AD groups In enterprise deployments, groups are synced from Azure AD. You can use your existing AD group structure to control agent access without creating separate groups in Neural Factory. For example: * Restrict the "HR Assistant" agent to the "HR Department" AD group * Restrict the "Engineering Docs" agent to the "Engineering" AD group ## Best practices * Start with **all users** visibility while testing a new agent, then restrict once it's ready * Use **groups** rather than individual users for easier maintenance * Document which agents are available to which groups for your team's reference # Agent Types Source: https://docs.neuralfactory.ai/user-guide/agents/agent-types Understand the different agent architectures available in Neural Factory. # Agent Types Neural Factory supports different agent architectures to handle varying levels of task complexity. ## Standard agent (ReAct) The default agent type. A standard agent handles requests directly using a **ReAct (Reasoning + Acting)** loop: 1. The agent receives your message 2. It reasons about what to do next 3. It optionally uses a tool (search, code execution, etc.) 4. It observes the tool result 5. It repeats steps 2–4 as needed 6. It generates a final response Standard agents are ideal for: * Answering questions from knowledge bases * Simple tool-based tasks (web search, code execution) * Single-domain Q\&A with well-defined scope ## CodeAct agent A specialized agent that follows a **plan-code-execute-validate** workflow: 1. Analyzes the request and creates a plan 2. Generates code to accomplish the task 3. Executes the code in a sandboxed environment 4. Validates the output and iterates if needed CodeAct agents excel at: * Data analysis and transformation tasks * Generating reports from structured data * Complex calculations and computations ## Orchestrator (Multi-Agent) An orchestrator is a **lead agent that delegates tasks to specialized subagents**. Instead of handling everything itself, it: 1. Analyzes the incoming request 2. Determines which subagent(s) are best suited 3. Delegates to the appropriate subagent(s) 4. Synthesizes results from subagent responses 5. Returns a unified answer to the user Orchestrators are ideal for: * Organizations with many specialized knowledge domains * Complex requests that span multiple areas of expertise * Workflows where different tools or knowledge sources need to be coordinated Learn more about setting up orchestrators in [Multi-Agent Workflows](/user-guide/agents/multi-agent-workflows). ## Choosing the right type | Scenario | Recommended type | | - | - | | Single knowledge domain, simple Q\&A | Standard agent | | Data analysis, code-heavy tasks | CodeAct agent | | Multiple domains, complex routing | Orchestrator + subagents | | General-purpose assistant with tools | Standard agent | # Configuring Agents Source: https://docs.neuralfactory.ai/user-guide/agents/configuring-agents Fine-tune agent behavior with advanced configuration options. # Configuring Agents Fine-tune how your agents behave, respond, and interact with users through advanced configuration options. ## Model settings ### Model selection Each agent can use a different AI model. Consider: * **Speed vs. quality** — Faster models are better for simple Q\&A; more capable models handle complex reasoning * **Context window** — Larger context windows allow longer conversations and more tool outputs * **Cost** — More capable models typically cost more per request ### Temperature Not all deployments expose this setting, but when available, temperature controls response randomness: * **Lower values (0.0–0.3)** — More deterministic, factual responses * **Higher values (0.7–1.0)** — More creative, varied responses For knowledge-grounded agents, lower temperature is usually preferred. ## System prompt best practices The system prompt is the single most impactful configuration. Guidelines: * **Be specific** — "You are an HR assistant that answers questions about the Employee Handbook" is better than "You are helpful" * **Define boundaries** — Tell the agent what it should NOT do: "Do not answer questions about compensation or salary" * **Set the tone** — "Respond in a professional but approachable tone. Use bullet points for lists." * **Handle edge cases** — "If you cannot find the answer in the knowledge base, say: I don't have that information. Please contact HR directly." ## Knowledge base connections Agents can search one or more knowledge bases. When multiple KBs are connected: * The agent searches across all connected KBs simultaneously * Results are ranked by relevance regardless of which KB they came from * Citations indicate which source document (and KB) each result came from ## Tool configuration Enable or disable individual tools per agent. Common configurations: | Agent type | Recommended tools | | - | - | | Knowledge Q\&A | Knowledge search | | Research assistant | Knowledge search + Web search | | Developer assistant | Knowledge search + Code execution | | Business operations | Knowledge search + External integrations (Jira, Outlook, etc.) | ## Saving changes Click **Save** to apply changes. Updates take effect immediately for new conversations. Existing conversations use the updated configuration on the next message. # Creating an Agent Source: https://docs.neuralfactory.ai/user-guide/agents/creating-an-agent Step-by-step guide to creating a new AI agent. # Creating an Agent Create a new AI agent in Neural Factory. You'll need an **Admin** role. ## Step-by-step Navigate to **Agents** in the sidebar. You'll see a list of all agents in your organization. Click the **Create Agent** button in the top right. This opens the agent configuration form. Fill in the required fields: * **Name** — A clear, descriptive name (e.g., "HR Policy Assistant", "Engineering Docs Bot") * **Description** — A brief summary of what the agent does, shown to users in the agent picker The system prompt is the most important configuration. It tells the agent who it is, how to behave, and what to do. Write clear instructions covering: * The agent's role and expertise area * Tone and communication style * What the agent should and shouldn't do * How to handle questions outside its scope **Example:** ``` You are the HR Policy Assistant for Acme Corp. Your job is to help employees find answers about company policies, benefits, and procedures. Always cite the specific policy document when answering. If you don't find relevant information in the knowledge base, say so clearly rather than guessing. Be professional but friendly. ``` Choose the AI model that powers the agent. Different models have different capabilities: * **GPT-4o / GPT-4.1** — Strong general-purpose models, good balance of quality and speed * **o-series** — Advanced reasoning models for complex analytical tasks * **Claude** — Alternative models with different strengths Your administrator may have specific models available based on your organization's configuration. Select one or more knowledge bases for the agent to search. The agent will retrieve relevant documents from these knowledge bases when answering questions. Choose which tools the agent can use: * **Knowledge search** — Search connected knowledge bases (enabled by default) * **Web search** — Search the internet for current information * **Code execution** — Run code in a sandboxed environment * **External integrations** — Connect to Jira, Confluence, Outlook, etc. See [Built-in Tools](/user-guide/toolkits/built-in-tools) for details on each tool. Click **Save** to create the agent. It will immediately appear in the agent list and be available for users to chat with (subject to access control settings). ## What's next After creating the agent, you may want to: * [Configure advanced settings](/user-guide/agents/configuring-agents) like strict mode or custom error messages * [Set up access control](/user-guide/agents/agent-access-control) to restrict who can use the agent * Test the agent by starting a conversation from the chat interface # Multi-Agent Workflows Source: https://docs.neuralfactory.ai/user-guide/agents/multi-agent-workflows Set up orchestrator agents that delegate to specialized subagents. # Multi-Agent Workflows Multi-agent workflows allow a single user-facing agent (the **orchestrator**) to delegate tasks to multiple specialized **subagents**. This is useful when your organization has distinct knowledge domains or toolsets that benefit from dedicated agents. ## How it works ``` User → Orchestrator Agent ├── HR Subagent (HR knowledge base, HR tools) ├── Engineering Subagent (technical docs, code execution) └── Finance Subagent (financial reports, spreadsheets) ``` 1. The user sends a message to the orchestrator 2. The orchestrator analyzes the request and determines which subagent can best handle it 3. The request is delegated to the appropriate subagent 4. The subagent processes the request using its own tools and knowledge bases 5. The orchestrator receives the subagent's response and returns it to the user The user only interacts with the orchestrator — they don't need to know about or select individual subagents. Delegations run as part of the orchestrator's own agent task, so the whole tree counts as **one** task against a user's parallel-task limit no matter how many subagents it calls. Each delegation is checkpointed individually: if a worker restarts mid-task, subagent work that already finished is not repeated. ## Setting up a multi-agent workflow First, create the individual specialized agents that will serve as subagents. Each should have: * A focused knowledge base for its domain * Tools relevant to its area * A clear system prompt defining its expertise Create a new agent and configure it as an orchestrator. In the agent configuration: * Select **Multi-Agent** as the agent type * Add the subagents you created in the previous step * Write a system prompt that describes when to delegate to each subagent The orchestrator's system prompt should clearly define routing logic: ``` You are the main assistant for Acme Corp. Route questions as follows: - HR, benefits, policies → delegate to HR Assistant - Technical documentation, code → delegate to Engineering Bot - Financial reports, budgets → delegate to Finance Assistant If a question spans multiple areas, consult the relevant subagents and synthesize their responses. ``` Start a chat with the orchestrator and test questions that should route to different subagents. Verify that: * Questions are routed to the correct subagent * Responses include citations from the right knowledge bases * Cross-domain questions are handled gracefully ## Best practices * **Keep subagents focused** — Each subagent should be an expert in one area * **Write clear routing instructions** — The orchestrator's system prompt should leave no ambiguity about which subagent handles what * **Limit the number of subagents** — 3–5 subagents is typically optimal; too many can confuse the routing. The platform also caps how many subagents run concurrently within a single task, so extra breadth queues rather than speeding things up * **Watch the time budget** — The whole delegation tree shares the parent task's limit of roughly an hour of active work. Orchestrators are the likeliest agents to reach it; prefer several focused requests over one sweeping one * **Test edge cases** — Try ambiguous questions that could go to multiple subagents # Agents Overview Source: https://docs.neuralfactory.ai/user-guide/agents/overview Understand what agents are and how they work in Neural Factory. # Agents Overview Agents are the core of Neural Factory. Each agent is a configured AI assistant with a specific purpose, knowledge, and set of tools — a specialized coworker for a particular domain. Agents list page ## What defines an agent Every agent is configured with: * **Name and description** — Identifies the agent to users * **System prompt** — Instructions that define behavior, tone, and expertise * **AI model** — The underlying language model (GPT-4o, GPT-4.1, Claude, etc.) * **Knowledge bases** — Document collections the agent can search * **Tools** — Capabilities like web search, code execution, or external integrations * **Access control** — Which users or groups can interact with the agent ## How agents work When a user sends a message, the agent: 1. **Reads the context** — Previous messages, system prompt, and any attached files 2. **Reasons about the task** — Determines what information or actions are needed 3. **Uses tools if needed** — Searches knowledge bases, executes code, calls APIs 4. **Generates a response** — Produces an answer with citations from retrieved sources This uses a **ReAct (Reasoning + Acting)** loop — the agent thinks step-by-step, deciding at each point whether to use a tool or respond directly. ### How a turn runs Each turn executes as an **agent task** on the platform's servers rather than inside the user's browser session. That gives every agent the same set of behaviors, whatever it is configured to do: * **It survives disconnection.** Closing the tab or losing the network doesn't cancel the task or lose the answer; reopening the conversation reattaches to it. * **It can pause for a human.** An agent can stop mid-task to ask a question or request approval, then continue from exactly where it paused — for up to 72 hours, using no compute while it waits. * **It can be stopped.** Users can cancel a running task; the agent finishes its current step and stops. * **It is bounded.** A task is capped on active running time (about an hour) and on total tokens, so a misbehaving loop stops and reports rather than running forever. * **It is billed once**, for what it actually consumed — including tasks that were stopped or failed partway. ## Agent types | Type | Description | | - | - | | **Standard agent** | Handles requests directly using its tools and knowledge | | **Orchestrator** | A multi-agent setup where a lead agent delegates to specialized subagents | Learn more in [Agent Types](/user-guide/agents/agent-types) and [Multi-Agent Workflows](/user-guide/agents/multi-agent-workflows). ## Managing agents Administrators create and configure agents from the **Agents** section in the sidebar: * [Creating an Agent](/user-guide/agents/creating-an-agent) * [Configuring Agents](/user-guide/agents/configuring-agents) * [Agent Access Control](/user-guide/agents/agent-access-control) # Strict Mode Source: https://docs.neuralfactory.ai/user-guide/agents/strict-mode Restrict agents to only answer from their connected knowledge bases. # Strict Mode Strict mode is a configuration option that constrains an agent to **only answer questions using information from its connected knowledge bases**. When enabled, the agent will not use its general training knowledge to fill in gaps. ## Why use strict mode By default, agents can supplement knowledge base results with information from their underlying AI model's training data. This is useful for general-purpose assistants but can be problematic when: * **Accuracy is critical** — You need answers grounded exclusively in your organization's documents * **Compliance matters** — Responses must be traceable to approved sources * **Domain specificity** — General AI knowledge could mislead users (e.g., legal or medical contexts) ## How it works When strict mode is enabled: 1. The agent searches connected knowledge bases for every question 2. If relevant results are found, the agent responds using only that information 3. If **no relevant results are found**, the agent returns a **custom "no answer" message** instead of guessing This ensures every answer is either sourced from your documents or clearly marked as unanswerable. ## Configuring strict mode 1. Navigate to **Agents** and edit the agent 2. Enable the **Strict Mode** toggle 3. Optionally, customize the **"no answer" message** — the response the agent gives when it can't find relevant information **Default no-answer message:** > I don't have enough information in my knowledge base to answer that question. Please try rephrasing your question or contact your administrator. **Custom example:** > I couldn't find information about that in our approved documents. For this type of question, please contact the Legal team directly at [legal@acme.com](mailto:legal@acme.com). ## When to use strict mode vs. standard | | Strict mode | Standard mode | | - | - | - | | Answers only from KB | Yes | No (can supplement with general knowledge) | | Handles unknown questions | Custom rejection message | Best-effort answer | | Best for | Compliance-critical, domain-specific | General-purpose assistants | | Citation coverage | 100% of answers are cited | Most answers are cited | # Chat History Source: https://docs.neuralfactory.ai/user-guide/chat/chat-history Browse, resume, and manage your past conversations. # Chat History Neural Factory saves your conversations so you can return to them later. The chat history sidebar organizes your past chats by date, making it easy to find and resume previous discussions. ## Browsing history Your conversation history appears in the left sidebar, grouped by time period: * **Today** — Conversations from the current day * **Previous 7 Days** — Last week's conversations * **Previous 30 Days** — Last month's conversations * **Older** — Conversations from more than 30 days ago Each entry shows the conversation title (typically derived from your first message) and the agent you were chatting with. ## Resuming a conversation Click on any conversation in the history sidebar to reopen it. The full message thread is restored, and you can continue the conversation where you left off. The agent retains context from the previous messages in that session. This works even if you left mid-answer. Agent tasks run on the server, so a turn that was still in progress when you closed the tab kept going: reopening the conversation **reattaches to the live task** and resumes showing it as it works. If it finished while you were away, the answer is already there in the thread. You never need to resend a message just because you lost your connection — and resending would start a second, separately billed task. ## Deleting conversations To delete a conversation: 1. Hover over the conversation entry in the sidebar 2. Click the delete icon that appears 3. Confirm the deletion Deleted conversations cannot be recovered. This removes the conversation from your history only — it does not affect the agent or any underlying documents. ## Search in history Use the search bar at the top of the sidebar to find specific conversations by keyword. This searches conversation titles and message content. # Citations & Sources Source: https://docs.neuralfactory.ai/user-guide/chat/citations-and-sources Understand how Neural Factory agents cite their sources. # Citations & Sources When an agent answers using information from your knowledge bases, it includes numbered citations so you can verify the information and trace it back to the original documents. ## How citations work Responses include numbered references like **\[1]**, **\[2]**, **\[3]**. Each number corresponds to a specific document chunk the agent retrieved. > Based on the Employee Handbook **\[1]**, full-time employees are entitled to 25 days of annual leave **\[2]**. Part-time employees receive a pro-rated allocation **\[1]**. Here, citations **\[1]** and **\[2]** point to specific sections the agent used to compose its answer. Agent response with citations expanded ## Viewing sources Below each response, expand the **"Sources used"** section to see: * **Document name** — The source file * **Chunk preview** — A snippet of the retrieved text * **Source type** — File upload, SharePoint, Google Drive, etc. ## Exploring a source Click any citation number to open the **source viewer**. This shows the full retrieved text chunk with document metadata, letting you: * Verify the answer against the original text * Read surrounding context for a fuller picture * Identify which document to consult for more detail Source viewer showing retrieved document chunk ## When citations appear Citations appear only when the agent searches a knowledge base. If the agent answers from general knowledge or an external tool, there won't be citations. Their presence signals that the answer is grounded in your organization's documents. ## No citations? If you expected citations but didn't see any: * The agent may not have a knowledge base connected — ask your administrator * The question may not have matched any indexed documents * The agent may have answered from its general training data instead # Feedback Source: https://docs.neuralfactory.ai/user-guide/chat/feedback Rate agent responses and help improve your AI assistants. # Feedback Feedback on agent responses helps administrators understand performance and identify areas for improvement. ## Rating responses Each response includes feedback controls: * **Thumbs up** — The response was helpful and accurate * **Thumbs down** — The response was unhelpful or inaccurate Click the appropriate icon to submit your rating. Feedback is recorded and visible to administrators in the [Analytics](/user-guide/admin/analytics) dashboard. Chat response with feedback and action buttons ## Additional actions Each response also offers: * **Copy** — Copy the response text to your clipboard * **Expand** — View the response in a larger panel for easier reading ## How feedback is used Administrators review feedback trends in [Analytics](/user-guide/admin/analytics) to: * Identify agents that consistently receive poor ratings * Find question types where agents struggle * Prioritize improvements to prompts, knowledge bases, or tools Your feedback is anonymous to other members but visible to administrators in aggregate interaction logs. # File Attachments Source: https://docs.neuralfactory.ai/user-guide/chat/file-attachments Attach files to your chat messages for agents to process. # File Attachments You can attach files to your chat messages so that agents can read, analyze, and reference them in their responses. ## Attaching a file 1. Click the **attachment icon** in the chat input bar (or drag and drop a file into the chat area) 2. Select the file from your device 3. Add your message or question about the file 4. Press **Enter** to send The agent will process the file and incorporate its content into the conversation context. ## Supported file types Neural Factory agents can process a variety of file formats: | Format | Extensions | | - | - | | Documents | `.pdf`, `.docx`, `.doc`, `.txt` | | Spreadsheets | `.xlsx`, `.xls`, `.csv` | | Presentations | `.pptx` | | Images | `.png`, `.jpg`, `.jpeg` | | Code | `.py`, `.js`, `.ts`, `.json`, `.yaml`, `.xml` | ## How agents use attachments When you attach a file, the agent can: * **Read and summarize** the document content * **Answer questions** about specific information in the file * **Extract data** from tables and spreadsheets * **Analyze images** (if the agent's model supports vision) * **Review code** and suggest improvements ## Tips * For best results, include a clear question or instruction along with your attachment * Large files may take a moment to process before the agent can respond — you don't have to wait on the page, since the task continues if you navigate away * File attachments are conversation-scoped — the agent can reference the file throughout the current conversation, across reloads and devices # Selecting an Agent Source: https://docs.neuralfactory.ai/user-guide/chat/selecting-an-agent Choose the right agent for your task using the agent picker. # Selecting an Agent Your organization may have multiple agents configured for different purposes — one for HR questions, another for technical documentation, a third for sales support. The agent picker lets you choose which agent to talk to. ## Using the agent picker The agent picker is located in the chat input bar. Click on it to see a list of all agents available to you. Each agent in the list shows: * **Name** — A descriptive name set by your administrator (e.g., "HR Assistant", "Engineering Docs") * **Description** — A brief summary of what the agent is designed to help with Select an agent to start chatting with it. You can change agents at any time by starting a new chat. ## What makes agents different Different agents may have: * **Different knowledge bases** — An HR agent searches HR documents, while an engineering agent searches technical docs * **Different tools** — Some agents can search the web, execute code, or connect to external systems like Jira or Outlook * **Different instructions** — Each agent has a custom system prompt that shapes its personality, tone, and behavior * **Different models** — Agents may use different AI models optimized for different tasks ## Favorites If you frequently use certain agents, they may appear at the top of your agent picker for quick access. Your most recently used agents are also prioritized in the list. ## Access restrictions You may not see all agents configured in your organization. Administrators can restrict agent visibility by [group](/user-guide/concepts/groups) or user, so you'll only see agents you have permission to access. # Starting a Conversation Source: https://docs.neuralfactory.ai/user-guide/chat/starting-a-conversation Learn how to start and interact with AI agents in Neural Factory. # Starting a Conversation The chat interface is where you interact with Neural Factory agents. It feels like a natural conversation while giving you access to your organization's knowledge and tools. Neural Factory chat interface with a conversation ## The chat interface * **Sidebar** (left) — Conversation history organized by date, plus navigation to other sections * **Message area** (center) — The conversation thread with your messages and agent responses * **Input bar** (bottom) — Where you type messages, select agents, and attach files ## Starting a new chat 1. Click **New Chat** in the sidebar 2. Select an agent from the agent picker (see [Selecting an Agent](/user-guide/chat/selecting-an-agent)) 3. Type your question in the input bar 4. Press **Enter** or click the send button ## Understanding responses When an agent responds, you may see: * **Plain text answers** — Direct responses based on the agent's instructions and general knowledge * **Cited answers** — Responses with numbered citations like **\[1]**, **\[2]** referencing documents from connected knowledge bases (see [Citations & Sources](/user-guide/chat/citations-and-sources)) * **Tool outputs** — Results from tools the agent used (web searches, code execution, external integrations) * **A question back to you** — The agent may pause and ask for a detail it needs before continuing * **An approval request** — For certain actions, the agent pauses until you approve or reject Responses stream in real-time — text appears progressively as the agent generates it. ## While the agent is working Sending a message starts an **agent task** that runs on our servers, not in your browser. The streaming text is a live view of that task, not the task itself — which changes what you can do while you wait. * **You can leave.** Close the tab, refresh, switch device, or lose your connection: the task keeps running. Reopen the conversation and it reattaches to the task in progress, or shows the finished answer if it completed while you were away. Nothing is lost. * **You can stop it.** While a task is running, the send button becomes a **Stop** button. Stopping is real — the agent finishes its current step and stops, showing **Stopping...** briefly. Work already done is still billed, so stop early if a task is heading the wrong way. * **You can queue the next message.** A conversation runs one task at a time. Type while a task is running and your message is held, then sent automatically when the task finishes. You'll see **Queued...** if a task is waiting for a free slot. * **The agent may pause for you.** If it asks a question, answer with a normal message and it picks up where it left off. If it asks for approval, use the approve or reject control. A pause uses no compute, and expires after 72 hours if nobody answers. Long tasks have an upper bound — about an hour of active work, plus a ceiling on total tokens. A task that reaches either limit stops and says so rather than running indefinitely. If you hit it, split the request into smaller pieces. Running several agent tasks at once is limited per user (and, for organizations, per organization). If you reach the limit you'll see **You've reached your limit of parallel agent tasks** — wait for one to finish, or stop one. Tasks paused waiting on you don't count. See [Billing](/user-guide/admin/billing) for the per-plan allowance. ## Following up Conversations are contextual. The agent remembers what you've discussed in the current session, so you can follow up naturally: > **You**: What is our parental leave policy? > > **Agent**: According to the Employee Handbook \[1], the company offers... > > **You**: How does that compare to the industry standard? > > **Agent**: Based on the policy I just described... ## Tips for effective conversations * **Be specific** — "What are the Q3 revenue targets for EMEA?" works better than "Tell me about targets" * **Ask one thing at a time** — Split complex multi-part questions into a sequence for better results * **Provide context** — Add details when needed: "I'm working on the Acme Corp proposal..." * **Use follow-ups** — Build on previous answers rather than starting fresh each time # Groups Source: https://docs.neuralfactory.ai/user-guide/concepts/groups Use groups for fine-grained access control over agents and knowledge bases. # Groups Groups provide **fine-grained access control** in Neural Factory. By assigning users to groups and then restricting agents or knowledge bases to specific groups, administrators can control exactly who sees what. ## How groups work 1. **Create groups** that represent teams, departments, or project scopes (e.g., "Engineering", "HR", "Finance") 2. **Add users** to the appropriate groups 3. **Assign groups** to agents and knowledge bases to control visibility When an agent or knowledge base is restricted to specific groups, only users who belong to at least one of those groups can access it. If no group restrictions are set, the resource is available to everyone in the organization. ## Creating and managing groups Administrators manage groups from the **User Management** section: 1. Navigate to **User Management** in the sidebar 2. Switch to the **Groups** tab 3. Click **Create Group** to add a new group 4. Give the group a name and optional description 5. Add members by searching for users in your organization ## Enterprise: Azure AD group sync In enterprise deployments, groups are **automatically synced from Azure Active Directory**. When a user signs in, their AD group memberships are mirrored in Neural Factory. This means: * Groups don't need to be created manually — they're imported from AD * User-group assignments stay in sync with your directory * Changes in AD (adding/removing users from groups) are reflected on next sign-in ## Groups in access control Groups are used in two places: * **Agent access control** — Restrict which groups can see and chat with an agent. See [Agent Access Control](/user-guide/agents/agent-access-control). * **Knowledge base access control** — Restrict which groups can have their queries search a knowledge base. See [KB Access Control](/user-guide/knowledge-bases/kb-access-control). # Organizations Source: https://docs.neuralfactory.ai/user-guide/concepts/organizations Understand the multi-tenant organization model in Neural Factory. # Organizations Neural Factory is a **multi-tenant platform** where each organization operates in its own isolated environment. An organization owns its agents, knowledge bases, toolkits, users, and all associated data. Nothing is shared across organizations. ## How organizations work When you sign in to Neural Factory, you belong to an organization. Everything you see — the agents available to you, the knowledge bases they search, the users in your team — all belongs to that organization. Administrators configure the platform for their organization, while members use the agents and tools that have been set up for them. ## Deployment modes Neural Factory supports two deployment modes, controlled by the deployment configuration: | | Enterprise | SaaS | | - | - | - | | **Authentication** | Azure Active Directory / SSO | Neural Factory native (email + password) | | **User provisioning** | Azure AD sync | Manual invite or self-signup | | **Group management** | Synced from Azure AD | Created manually in-app | | **Billing** | No usage limits (license-based) | Usage-based plans with limits | | **Hosting** | Dedicated or on-premise | Shared cloud infrastructure | ### Enterprise Designed for large organizations that need SSO, automatic user provisioning, and Azure AD group sync. Users sign in with their corporate credentials, and groups from Azure AD are automatically mirrored in Neural Factory for access control. ### SaaS Designed for teams and individuals who want to get started quickly. Users sign up with email and password, create or join an organization, and manage groups manually. Usage is tracked against plan limits. ## Organization setup * **Enterprise**: Your organization is provisioned during deployment. Users are automatically added when they sign in via Azure AD. * **SaaS**: The first user to sign up creates the organization during onboarding. Additional users are invited by an administrator. # Users & Roles Source: https://docs.neuralfactory.ai/user-guide/concepts/users-and-roles Understand user roles and permissions in Neural Factory. # Users & Roles Every person in a Neural Factory organization has a **role** that determines what they can do on the platform. Roles control access to administrative features while all users can chat with agents they have access to. ## Role types | Role | Description | | - | - | | **Admin** | Full access to all platform features including agent configuration, knowledge base management, user administration, and analytics. | | **Member** | Can chat with agents and view their own conversation history. Cannot access administrative features. | ## Permissions by role | Feature | Admin | Member | | - | - | - | | Chat with agents | Yes | Yes (agents they have access to) | | View chat history | Yes | Own conversations only | | Create/edit agents | Yes | Own agents only | | Manage knowledge bases | Yes | Own knowledge bases only | | Create/edit skills | Yes | Own skills only | | Share agents, knowledge bases and skills with specific users/groups | Yes (any) | Own resources only | | Configure toolkits | Yes | No | | Manage users & groups | Yes | No | | View analytics | Yes | No | | Manage API keys | Yes | No | | Manage billing (SaaS) | Yes | No | ## How roles are assigned * **Enterprise**: Roles are mapped from Azure AD groups or directory roles during sync. Your IT administrator configures which AD groups correspond to Admin or Member roles. * **SaaS**: The organization creator is automatically an Admin. Additional users receive roles when invited — an Admin can promote or demote users from the User Management page. ## Managing users Administrators can manage users from the **User Management** section in the sidebar. See [User Management](/user-guide/admin/user-management) for details on inviting users, changing roles, and removing accounts. # Introduction Source: https://docs.neuralfactory.ai/user-guide/index Welcome to Neural Factory — your enterprise AI coworker platform. Neural Factory platform overview # Welcome to Neural Factory Neural Factory turns your organization's knowledge into intelligent AI coworkers. Connect your data sources, configure specialized agents, and let your team get answers, automate workflows, and make better decisions — all through natural conversation. Unlike generic chatbots, Neural Factory agents are grounded in your actual documents. They cite their sources, respect your access controls, and integrate with the tools your team already uses. Import documents, SharePoint libraries, Google Drive folders, and FAQs. Neural Factory indexes your content so agents can search it intelligently. Build specialized agents with custom instructions, tools, and knowledge bases. Create single-purpose assistants or multi-agent workflows. Have natural conversations with agents that cite their sources. Attach files, browse history, and give feedback to improve responses over time. Track usage, review interaction logs, and understand how your organization leverages AI from a centralized dashboard. ## Who is this for? Chat with AI agents to find answers, generate content, and complete tasks using your organization's knowledge. Configure agents, manage knowledge bases, control access, and monitor platform usage. Integrate Neural Factory into your applications using the REST API. ## Get Started Sign in and start chatting with your first agent in minutes. Understand organizations, roles, and groups before diving deeper. # Creating a Knowledge Base Source: https://docs.neuralfactory.ai/user-guide/knowledge-bases/creating-a-knowledge-base Step-by-step guide to creating a new knowledge base. # Creating a Knowledge Base Create a new knowledge base to give your agents access to your organization's documents. You'll need an **Admin** role. ## Step-by-step Navigate to **Knowledge Bases** in the sidebar. You'll see a list of all existing knowledge bases. Click the **Create Knowledge Base** button. This opens the creation form. Fill in the required fields: * **Name** — A descriptive name (e.g., "Employee Handbook", "Product Documentation", "Sales Materials") * **Description** — A brief explanation of what this knowledge base contains Choose how you'll add content to this knowledge base: * **File upload** — Drag and drop files or browse your device * **SharePoint** — Connect to a SharePoint site or library * **Google Drive** — Connect to a Google Drive folder * **FAQ** — Add structured question-answer pairs You can add multiple datasources to a single knowledge base. See the individual datasource guides for details. Click **Save** to create the knowledge base. If you've added documents, indexing begins automatically in the background. You can monitor the indexing progress from the knowledge base detail page. ## After creation Once your knowledge base is created and indexed, you need to **connect it to an agent** before it's useful: 1. Navigate to **Agents** and edit the agent you want to connect 2. In the agent's knowledge base configuration, select your new knowledge base 3. Save the agent The agent will now search this knowledge base when answering questions. ## Tips * **Organize by topic** — Create separate knowledge bases for different domains (HR, Engineering, Sales) rather than dumping everything into one * **Keep it current** — Regularly update documents or set up auto-sync with SharePoint/Google Drive * **Test after indexing** — Ask the connected agent questions you know should be answerable from the documents # FAQ Datasource Source: https://docs.neuralfactory.ai/user-guide/knowledge-bases/faq-datasource Add structured question-answer pairs as a knowledge source. # FAQ Datasource The FAQ datasource lets you add structured **question-answer pairs** to a knowledge base. This is useful for common questions that have definitive answers, such as company FAQs, policy summaries, or support responses. ## Why use FAQ datasources Unlike document uploads where the system needs to find the right chunk of text, FAQ entries are already in question-answer format. This means: * **Higher precision** — The agent matches the user's question directly to an FAQ question * **Consistent answers** — Every user gets the same approved answer * **Easy to maintain** — Update individual Q\&A pairs without re-indexing entire documents ## Adding FAQ entries Navigate to **Knowledge Bases** and open the target knowledge base. Click **Add Datasource** and select **FAQ** from the datasource type options. For each FAQ entry, provide: * **Question** — The question as a user would naturally ask it * **Answer** — The complete, approved answer You can add entries one at a time or import them in bulk. Click **Save** to index the FAQ entries. They become searchable immediately. ## Best practices * **Write questions naturally** — Phrase questions the way users would ask them, not in formal language * **Include variations** — If a question can be asked different ways, consider adding multiple entries with the same answer * **Keep answers complete** — Each answer should be self-contained and not require additional context * **Use FAQs alongside documents** — Combine FAQ datasources with document uploads for the best coverage # File Uploads Source: https://docs.neuralfactory.ai/user-guide/knowledge-bases/file-uploads Upload documents directly to a knowledge base. # File Uploads The simplest way to add content to a knowledge base is by uploading files directly. Neural Factory supports a variety of document formats. ## Supported file types | Format | Extensions | Notes | | - | - | - | | PDF | `.pdf` | Text-based and scanned (with OCR) | | Word | `.docx`, `.doc` | Microsoft Word documents | | Excel | `.xlsx`, `.xls` | Spreadsheets — each sheet is processed | | Text | `.txt` | Plain text files | | PowerPoint | `.pptx` | Slide content is extracted as text | | CSV | `.csv` | Tabular data | ## Uploading files Navigate to **Knowledge Bases** and click on the knowledge base you want to add files to. Click **Upload Files** or drag and drop files into the upload area. You can upload multiple files at once. Each file goes through the processing pipeline: 1. **Uploaded** — File is received and stored 2. **Processing** — Content is extracted and split into chunks 3. **Indexed** — Chunks are embedded and added to the vector index 4. **Ready** — Document is searchable by agents Processing time depends on file size and type. Most documents are ready within seconds to a few minutes. ## File size limits * Individual file size limits depend on your deployment configuration * For SaaS plans, file size limits vary by subscription tier ## Best practices * **Use clear filenames** — Filenames are used as metadata and may appear in citations * **Prefer text-based PDFs** — Scanned PDFs work but text-based PDFs produce better results * **Update, don't duplicate** — If a document is updated, delete the old version and upload the new one * **Organize with multiple KBs** — Rather than uploading hundreds of files to one KB, split them by topic # Google Drive Source: https://docs.neuralfactory.ai/user-guide/knowledge-bases/google-drive Connect Google Drive as a datasource for your knowledge base. # Google Drive Integration Neural Factory can connect to Google Drive to index documents from your organization's Drive folders. Agents can then search and cite content stored in Google Drive. ## Prerequisites * A Google Workspace account with Drive access * An administrator must authorize the Google Drive connection * The Drive folder must be accessible with the configured credentials ## Connecting Google Drive Navigate to **Knowledge Bases** and open the knowledge base where you want to add Google Drive content. Click **Add Datasource** and select **Google Drive** from the datasource type options. Complete the Google OAuth flow to grant Neural Factory read access to your Google Drive. Browse your Google Drive and select the folder you want to index. All documents within the folder (including subfolders) will be indexed. Choose sync behavior: * **Manual** — Only syncs when you trigger it * **Automatic** — Periodically checks for new or updated files Click **Save** to create the datasource. The initial sync begins and indexes all documents in the selected folder. ## Supported content * Google Docs (exported as text) * Google Sheets (exported as structured data) * Google Slides (exported as text) * Uploaded files in standard formats (PDF, DOCX, XLSX, TXT, PPTX) ## Troubleshooting * **Authentication errors** — Re-authorize the Google Drive connection if credentials have expired. * **Missing files** — Ensure files are in the selected folder and in a supported format. Trashed files are not indexed. * **Permission issues** — The authenticated account must have at least read access to the folder. # Indexing Status Source: https://docs.neuralfactory.ai/user-guide/knowledge-bases/indexing-status Monitor document processing and indexing progress. # Indexing Status When documents are added to a knowledge base, they go through a processing pipeline before they become searchable. The indexing status lets you monitor this progress. ## Processing states Each document progresses through these states: | State | Description | | - | - | | **Uploaded** | File has been received and stored, awaiting processing | | **Processing** | Content is being extracted, split into chunks, and embedded | | **Indexed** | Successfully processed — the document is searchable by agents | | **Failed** | Processing encountered an error (see troubleshooting below) | ## Monitoring progress From the knowledge base detail page, you can see: * **Overall progress** — A summary of how many documents are indexed vs. pending * **Per-document status** — The current state of each individual document * **Datasource sync status** — For connected sources like SharePoint, the last sync time and result ## Processing time Processing time depends on several factors: * **File size** — Larger files take longer to process * **File type** — PDFs with complex layouts or scanned content take longer than plain text * **Queue depth** — If many documents are being processed simultaneously, individual documents may wait in the queue * **Content complexity** — Documents with tables, images, or mixed formatting require more processing Typical processing times: | Scenario | Expected time | | - | - | | Small text file (\< 1 MB) | Seconds | | Standard PDF (1–10 MB) | 10–60 seconds | | Large document (10–50 MB) | 1–5 minutes | | Bulk upload (100+ files) | 10–30 minutes | ## Troubleshooting failed documents If a document shows **Failed** status: * **Unsupported format** — Ensure the file is in a supported format (PDF, DOCX, XLSX, TXT, PPTX, CSV) * **Corrupted file** — Try opening the file locally to verify it's not corrupted * **File too large** — Check if the file exceeds your plan's size limits * **Extraction error** — Some heavily formatted or encrypted PDFs may fail. Try converting to a simpler format. You can retry a failed document by deleting it and re-uploading. # KB Access Control Source: https://docs.neuralfactory.ai/user-guide/knowledge-bases/kb-access-control Control which users and groups can access specific knowledge bases. # Knowledge Base Access Control Similar to agent access control, knowledge bases can be restricted to specific users or groups. This ensures sensitive documents are only searchable by authorized personnel. ## How it works When a knowledge base has access restrictions: * Only users in the allowed groups/users list can trigger searches against it * Agents connected to the KB will only search it when the requesting user has access * Documents in restricted KBs never appear in citations for unauthorized users ## Setting access restrictions The knowledge base creator and organization admins can change these settings; other users with access cannot. 1. Navigate to **Knowledge Bases** and edit the knowledge base 2. Scroll to the **Access Control** section 3. Configure visibility: * **All users** — Anyone in the organization can search this KB (default) * **Specific groups** — Only members of selected groups * **Specific users** — Only individually selected users 4. Click **Save** ## Who can edit a knowledge base Access to a knowledge base grants search and read rights only. Changing the knowledge base is limited by role: * **KB creator and organization admins** — edit KB settings (title, description, visibility, allowed users/groups), manage datasources (create, edit, delete, sync), delete any document, and delete the KB itself * **Anyone with access** (except Viewers) — upload documents and delete their own uploads * **Viewers** — read-only: search and browse, no changes of any kind ## Interaction with agent access control Access control is layered: 1. **Agent access** — The user must have access to the agent 2. **KB access** — The user must have access to the knowledge base If an agent is connected to multiple KBs, a user only searches the KBs they have access to. For example: * Agent "Company Assistant" is connected to both "General Docs" (all users) and "Finance Reports" (Finance group only) * A user in the Engineering group can chat with the agent but only searches "General Docs" * A user in the Finance group searches both "General Docs" and "Finance Reports" ## Best practices * Use **group-based restrictions** for easier management * Match KB access to the sensitivity of the documents it contains * Test access control by checking what citations appear for users in different groups # Managing Documents Source: https://docs.neuralfactory.ai/user-guide/knowledge-bases/managing-documents Upload, view, and remove documents in your knowledge bases. # Managing Documents Once a knowledge base is set up, you can manage individual documents — upload new files, check processing status, and remove outdated content. Document list within a knowledge base datasource ## Viewing documents Navigate to a knowledge base and click on a datasource to see its documents. Each entry shows: * **Filename** — The uploaded or synced document name * **Status** — Processing state (Uploaded, Processing, Indexed, Failed) * **Date added** — When the document was uploaded or synced * **Size** — File size ## Uploading new documents To add documents to an existing file-upload datasource: 1. Open the knowledge base and select the datasource 2. Click **Upload Files** or drag and drop new files 3. Wait for processing to complete New documents are indexed independently — adding files does not re-index existing ones. ## Removing documents 1. Open the knowledge base and navigate to the document 2. Click the **Delete** action 3. Confirm the deletion Removing a document deletes it from storage and removes its chunks from the vector index. Agents will no longer cite content from that document. ## Replacing documents To replace an outdated document: 1. Delete the old document 2. Upload the new version There is no in-place update — remove and re-upload to ensure the document is fully re-processed and re-indexed. ## Bulk operations For SharePoint or Google Drive datasources, document management is handled automatically by the sync process. Neural Factory detects additions, updates, and deletions during each sync cycle. # Knowledge Bases Overview Source: https://docs.neuralfactory.ai/user-guide/knowledge-bases/overview Understand how knowledge bases power agent responses with your organization's data. # Knowledge Bases Overview Knowledge bases are collections of your organization's documents that agents search to provide grounded, cited answers. Instead of relying on general AI knowledge alone, agents retrieve specific information from your documents. Knowledge bases list page ## How knowledge bases work 1. **Ingest** — Upload documents or connect data sources (SharePoint, Google Drive, etc.) 2. **Process** — Documents are split into chunks, embedded, and indexed in a vector store 3. **Search** — When a user asks a question, the agent searches using hybrid retrieval (keyword + semantic) 4. **Retrieve** — The most relevant chunks are returned to the agent 5. **Respond** — The agent generates an answer with citations back to the source documents This is called **Retrieval-Augmented Generation (RAG)** — combining AI language models with the accuracy of your actual documents. ## Supported source types | Source type | Description | | - | - | | **File uploads** | PDF, DOCX, XLSX, TXT, PPTX files uploaded directly | | **SharePoint** | Connected SharePoint document libraries and sites | | **Google Drive** | Connected Google Drive folders | | **FAQ** | Structured question-answer pairs | ## Key concepts * **Datasources** — Connections to external data (SharePoint, Google Drive) or upload containers within a knowledge base * **Documents** — Individual files or entries within a datasource * **Chunks** — Processed segments of documents stored in the vector index * **Indexing** — The background process of converting documents into searchable chunks Knowledge base detail page showing datasources ## Getting started * [Creating a Knowledge Base](/user-guide/knowledge-bases/creating-a-knowledge-base) * [File Uploads](/user-guide/knowledge-bases/file-uploads) * [SharePoint Integration](/user-guide/knowledge-bases/sharepoint) * [Google Drive Integration](/user-guide/knowledge-bases/google-drive) * [Managing Documents](/user-guide/knowledge-bases/managing-documents) # SharePoint Source: https://docs.neuralfactory.ai/user-guide/knowledge-bases/sharepoint Connect SharePoint as a datasource for your knowledge base. # SharePoint Integration Neural Factory can connect to Microsoft SharePoint to index documents from your organization's SharePoint sites and document libraries. This allows agents to search and reference content stored in SharePoint without manual file uploads. ## Prerequisites * Your organization must have SharePoint Online access * An administrator must authorize the SharePoint connection * The SharePoint site/library must be accessible with the configured credentials ## Connecting SharePoint Navigate to **Knowledge Bases** and open the knowledge base where you want to add SharePoint content. Click **Add Datasource** and select **SharePoint** from the datasource type options. Complete the OAuth authentication flow to grant Neural Factory read access to your SharePoint environment. Browse your available SharePoint sites and select the document library or folder you want to index. Choose how often Neural Factory should check for new or updated documents: * **Manual** — Only syncs when you trigger it * **Automatic** — Periodically checks for changes and re-indexes Click **Save** to create the datasource. The initial sync will begin, indexing all documents in the selected library. ## Supported content Neural Factory indexes the following from SharePoint: * Documents in standard formats (PDF, Word, Excel, PowerPoint, text files) * Documents in subfolders within the selected library * Updated documents are re-indexed automatically (if auto-sync is enabled) ## Troubleshooting * **Authentication failures** — Ensure the SharePoint connection has valid credentials. You may need to re-authorize. * **Missing documents** — Check that the documents are in the selected library/folder and in a supported format. * **Sync delays** — Large libraries may take time for the initial sync. Check the indexing status on the knowledge base detail page. # Quickstart Source: https://docs.neuralfactory.ai/user-guide/quickstart Sign in and start your first conversation with a Neural Factory agent. # Quickstart Get up and running in minutes. This guide covers signing in, navigating the interface, and having your first conversation with an AI agent. ## Prerequisites * An active Neural Factory account (via invitation or self-signup) * A modern web browser (Chrome, Edge, Firefox, or Safari) ## Step-by-step Navigate to your Neural Factory instance and sign in. * **Enterprise deployments**: Use your organization's Azure AD single sign-on (SSO) credentials. * **SaaS deployments**: Sign in with your email and password, or create a new account. After signing in, you'll land on the main chat interface. The left sidebar is your main navigation hub. From here you can access: * **New Chat** — Start a fresh conversation with an agent * **Chat History** — Return to previous conversations * **Agents** — Browse and manage available agents (admin) * **Knowledge Bases** — View and configure knowledge sources (admin) * **Toolkits** — Manage external tool integrations (admin) * **User Management** — Invite and manage users (admin) * **Analytics** — View usage and interaction data (admin) Click **New Chat** in the sidebar. You'll see the chat interface with a message input bar at the bottom. 1. Select an agent from the agent picker (if multiple agents are available) 2. Type your question in the message input — for example: *"What is our company's remote work policy?"* 3. Press **Enter** or click the send button The agent will process your question, search relevant knowledge bases, and respond with an answer. If the agent found information in your documents, you'll see numbered citations like **\[1]**, **\[2]** in the response that link back to the original sources. If you have an **Admin** role, explore the management sections in the sidebar: * Create and configure new agents * Add knowledge bases with your organization's documents * Connect external tools and integrations * Review analytics and interaction logs ## Next steps Learn about citations, chat history, feedback, and file attachments. Configure agent behavior, connect knowledge, and set up tools. Connect your organization's documents and data sources. Integrate Neural Factory into your own applications. # Search Source: https://docs.neuralfactory.ai/user-guide/search Use the search feature to find information across your organization's knowledge. # Search Neural Factory includes a search feature that lets you search across your organization's knowledge bases directly, without starting a conversation with an agent. ## Using search 1. Click the **Search** icon or use the search bar 2. Type your query 3. Review the results — each result shows: * A snippet of the matching content * The source document name * The knowledge base it belongs to * A relevance score ## How search works Search uses the same **hybrid retrieval** system that agents use: * **Semantic search** — Finds results that are conceptually related to your query, even if they don't contain the exact words * **Keyword search** — Finds results that contain the specific terms you used * **Reranking** — Results are re-scored and sorted by relevance This means you can search naturally ("What's our policy on remote work?") rather than needing to guess exact keywords. ## Search vs. chat | | Search | Chat | | - | - | - | | Returns | Document chunks | Synthesized answers | | Citations | Direct document links | Numbered references in response | | Interaction | One-shot query | Multi-turn conversation | | Best for | Finding specific documents | Getting answers to questions | ## Access control Search results respect knowledge base access control. You'll only see results from knowledge bases you have permission to access. # Built-in Tools Source: https://docs.neuralfactory.ai/user-guide/toolkits/built-in-tools Explore the tools that come built into Neural Factory. # Built-in Tools Neural Factory includes several built-in tools that agents can use out of the box. These tools are available to all agents and can be enabled or disabled per agent in the configuration. ## Knowledge search The default tool for every agent. When enabled, the agent searches connected knowledge bases to find relevant document chunks for answering questions. Results include citations back to the source documents. ## Web search Allows the agent to search the internet for current information. Useful when: * The question is about recent events not in your knowledge base * The agent needs to supplement KB results with public information * The user asks about something outside your organization's documents ## Code execution Runs Python code in a **secure, sandboxed environment** (Docker container or Azure Dynamic Sessions). The agent can: * Perform calculations and data analysis * Generate charts and visualizations * Process and transform data * Execute custom logic Code execution is completely isolated — it cannot access your organization's systems or data outside the sandbox. ## Bash Executes shell commands in the same sandboxed environment as code execution. Useful for: * File manipulation tasks * Running command-line tools * System-level operations within the sandbox ## Browser automation Navigates to web pages and extracts content. The agent can: * Visit a URL and read the page content * Follow links and navigate multi-page sites * Extract structured data from web pages ## File editor Reads and modifies files within the sandbox environment. Commonly used alongside code execution for tasks that involve creating or editing files. ## Image generation Generates images from text descriptions using AI image generation models. Useful for creating diagrams, illustrations, or visual content during conversations. ## Memory Allows the agent to store and recall information across conversations. The agent can: * Save important facts or preferences mentioned by the user * Recall stored information in future conversations * Build up knowledge about recurring topics or user preferences Memory is scoped to the user and agent — different users have separate memory stores. # External Integrations Source: https://docs.neuralfactory.ai/user-guide/toolkits/external-integrations Connect agents to third-party services via MCP-based toolkits. # External Integrations Neural Factory uses the **Model Context Protocol (MCP)** to integrate with external services. These integrations give agents the ability to interact with your organization's existing tools — creating Jira tickets, searching Confluence, sending Outlook emails, and more. ## Available integrations ### Jira * Search for issues by project, status, or keyword * Create new issues with title, description, and metadata * Update issue status, assignee, or comments * Read issue details and comments ### Confluence * Search pages by space, title, or content * Read page content * Useful for agents that need access to internal wikis and documentation ### Tempo Time tracking and team analytics on top of Jira. * Report logged time for a person, a team, or a project, grouped by person, issue, project, day, week, or month * Measure utilization against each person's real Tempo schedule, so holidays and part-time contracts are accounted for * Find the working days where someone logged less time than their schedule required * Check timesheet approval status per approval period * List Tempo teams, their members, and a person's schedule * Read individual worklog entries when a specific entry has to be inspected Tempo returns numeric issue ids and account ids rather than issue keys and names, so this integration reads Jira as well and needs both sets of credentials. The Tempo API token is generated in Tempo under **Settings → API Integration**, and it acts as the user who issued it: a report covering a whole team needs a user who can view all worklogs. The base URL has to match your Tempo data region. All Tempo tools are read-only — agents can report on time, not log or change it. **Structure by Tempo** is covered by the same integration, and is optional: add a Structure personal access token (generated in Jira under the Structure app's personal settings) and the agent can also: * List the structures the credentials can see, with a link to open each one in Jira * Read a structure's metadata, owner, and default view * Inspect a view's columns, including the Tempo logged-time and planned-time columns and the team, role, and billable filters behind them Structure's Cloud API exposes structures and view configurations only; it cannot return rows, hierarchy contents, or computed column values. An agent asked for the numbers in a structure reports what the view measures and gets the figures themselves from the Tempo tools. Without a Structure token, the Structure tools report that Structure is not configured and everything else keeps working. ### Outlook * Send emails on behalf of the authenticated user * Search the user's inbox * Read email content * Useful for agents that handle communication tasks ### SharePoint (Toolkit) * Search document libraries beyond what's in a knowledge base * Read document content directly * List files and folders ### Google Drive (Toolkit) * Search across Drive for files * Read document content * List files in folders ### Custom MCP servers Neural Factory supports dynamically loaded external MCP servers. This means your organization can build custom integrations for any internal tool or API and connect them as toolkits. A custom MCP server is reached over streamable HTTP, SSE, or a local stdio command, and can be protected in one of three ways: * **None** — access is controlled by the network alone, for example a server on a private VPN. * **API Key** — a shared key sent in a header of your choice on every request. * **OAuth2 Client Credentials** — for a server published behind an API gateway. You provide the gateway's token URL, a client ID, an optional scope, and the client secret. Neural Factory obtains an access token from the token URL, caches it until shortly before it expires, and sends it as a bearer token on every request. The client secret is used only to request tokens; it is never forwarded to the MCP server. Credential Values are separate from this: they are downstream secrets the MCP server itself needs (a database connection string, an internal API's client ID) and are forwarded to the server on every request. **Send user email to server.** When this is enabled on a custom MCP toolkit, every tool call carries the email and user ID of the person the agent is working for, in the MCP request metadata (`_meta`) under the keys `neuralfactory.ai/user_email` and `neuralfactory.ai/user_id`. The server can use them to return only that user's data, for example as a parameter of its database queries. The values are stated by Neural Factory on the user's behalf; the server knows Neural Factory authenticated itself, not that the user did. It is off by default: enable it only for servers you trust with this personal data. The integrations Neural Factory provides (SharePoint, Google Drive, Jira, Confluence, Tempo, Outlook) always receive it. The identity is sent the same way whether the agent is used in the web app or called through the API, and over every transport (streamable HTTP, SSE, stdio). ## How integrations work 1. An administrator configures the integration in the **Toolkits** section 2. Authentication is set up (OAuth, API keys, or other credentials) 3. The toolkit is enabled for specific agents 4. When a user interacts with the agent, the agent can call the integration's tools as needed ## Security * All external tool calls are authenticated and logged * Credentials are stored securely and never exposed to users or in conversation logs * Tool usage is visible in the analytics dashboard # Managing Connections Source: https://docs.neuralfactory.ai/user-guide/toolkits/managing-connections Set up and maintain toolkit connections and credentials. # Managing Connections Toolkit connections require authentication to access external services. This guide covers setting up, testing, and maintaining those connections. ## Setting up a connection Open the **Toolkits** section from the sidebar. Choose an existing toolkit to configure or create a new one. Each integration has its own authentication method: * **OAuth** (Jira, Confluence, Outlook, SharePoint, Google Drive) — Click "Connect" and complete the OAuth authorization flow in the popup window * **API key** — Enter the API key provided by the external service * **Custom credentials** — Provide the required credentials as specified by the integration After configuring credentials, use the **Test Connection** button (if available) to verify that Neural Factory can successfully communicate with the external service. Once the toolkit is connected, assign it to the agents that should be able to use it. This is done in the agent configuration under the tools section. ## Managing existing connections ### Refreshing credentials OAuth tokens may expire over time. If a toolkit stops working: 1. Navigate to the toolkit in the **Toolkits** section 2. Click **Reconnect** or **Re-authorize** 3. Complete the OAuth flow again ### Revoking access To disconnect a toolkit: 1. Navigate to the toolkit configuration 2. Click **Disconnect** or remove the credentials 3. Remove the toolkit from any agents that had it assigned ### Viewing connection status The Toolkits page shows the connection status for each configured toolkit — whether it's connected, requires re-authorization, or has errors. ## Troubleshooting * **OAuth flow fails** — Ensure your browser allows popups for the Neural Factory domain * **Connection test fails** — Verify that the external service is accessible and the credentials are correct * **Intermittent failures** — Check if the external service has rate limits or downtime * **Permission errors** — The authenticated account may lack the required permissions in the external service See [Connection Problems](/help/troubleshooting/connection-problems) for more detailed troubleshooting. # Toolkits Overview Source: https://docs.neuralfactory.ai/user-guide/toolkits/overview Extend agent capabilities with built-in and external tools. # Toolkits Overview Toolkits extend what agents can do beyond knowledge base Q\&A. With tools, agents can search the web, execute code, browse websites, send emails, create Jira tickets, and more. ## How tools work When an agent has tools enabled, it decides autonomously when to use them: 1. Recognizes that a tool would help answer the question 2. Calls the tool with appropriate parameters 3. Receives the tool's output 4. Incorporates the result into its response Tool usage is automatic — users don't need to explicitly request it. ## Tool categories ### Built-in tools These are tools provided natively by Neural Factory: | Tool | Description | | - | - | | **Knowledge search** | Search connected knowledge bases (enabled by default) | | **Web search** | Search the internet for current information | | **Code execution** | Run Python code in a secure sandbox | | **Bash** | Execute shell commands in a sandboxed environment | | **Browser** | Navigate and extract content from web pages | | **File editor** | Read and modify files in the sandbox | | **Image generation** | Generate images from text descriptions | | **Memory** | Remember information across conversations | See [Built-in Tools](/user-guide/toolkits/built-in-tools) for details. ### External integrations MCP-based integrations with third-party services: | Integration | Capabilities | | - | - | | **Jira** | Create issues, search tickets, update status | | **Confluence** | Search and read pages | | **Tempo** | Report logged time and utilization, find missing time logs, check timesheet status, browse Structure views | | **Outlook** | Send emails, search inbox | | **SharePoint** | Search and read documents | | **Google Drive** | Search and read documents | | **Custom MCP servers** | Dynamically loaded external tool servers | See [External Integrations](/user-guide/toolkits/external-integrations) for details. ## Managing toolkits Administrators configure toolkits from the **Toolkits** section in the sidebar. Once configured, tools are assigned to individual agents in the agent configuration.