# Approvals and Policy Source: https://docs.decisional.com/agents/approvals Control when agents pause, ask for review, bypass approvals, or block actions ## Overview Approvals are Decisional's human-in-the-loop control system. They let an agent prepare work, show the relevant context, and pause before a sensitive action proceeds. Approvals can appear during automated runs, Chat Mode write actions, Run Mode flows, and workflow gates. They are especially useful when an agent is about to send information, update a system, make a decision with business impact, or continue past a manual review point. ## Where approvals appear The agent pauses before an action that writes, sends, updates, creates, or deletes information. A workflow can pause at an explicit review step before moving to the next node. If an agent wants to take a write action during chat, it can ask for approval before executing. Stakeholders can review context and approve or reject without needing the full builder interface. ## What an approval contains An approval should give the reviewer enough context to make a decision without digging through logs. Approvals typically include: * The action the agent wants to take * The relevant run, node, or chat context * Inputs and generated outputs * Files or records involved in the decision * Approve and reject controls * Any notes the reviewer adds before continuing When an approval is accepted, the run continues. When it is rejected, the agent stops, routes to the configured rejection path, or asks for a correction depending on the workflow. See how Dex asks for approval in Slack before creating a Linear issue. ## Approval layers Approval behavior comes from multiple layers working together. | Layer | What it controls | Typical options | | ----------------------------------- | ---------------------------------------------------------- | ------------------------------------------- | | **Workspace default approval mode** | The account default used when a runner is set to Default | Ask approvals or Bypass approvals | | **Runner approval picker** | The approval mode for the current chat or run prompt box | Default, Ask approvals, or Bypass approvals | | **Tool approval policy** | How toolkit read/write tools and per-tool overrides behave | Always allow, Needs approval, or Blocked | | **Workflow gates** | Manual review points designed into the workflow | Approver list, quorum, approve, reject | Use these layers together. For example, a low-risk reporting agent might bypass eligible approval prompts, while a finance agent can keep write tools on **Needs approval** and add gate nodes for final review. ## Workspace default and runner picker The workspace default is the fallback approval mode. It is used only when the runner is set to **Default**. Workspace settings showing the default approval mode The prompt-box approval picker controls the runner you are about to use. The **Default** option shows the effective workspace default in parentheses. If the picker says **Default (Bypass approvals)**, choosing Default means eligible approval prompts will be bypassed. Chat prompt box permissions picker with Ask approvals selected For live runs, choose **Ask approvals** in the runner picker when you want the agent to pause before eligible sensitive actions. If the live runner is set to **Default** and the effective default is bypass, the run continues without approval prompts. Test runs are the best place to keep Ask approvals on while you review behavior. Live runs only pause for approval when the effective runner setting is Ask approvals, when tool policy requires approval, or when the workflow reaches an explicit gate. ## Ask approvals **Ask approvals** means the agent pauses before eligible sensitive actions. A reviewer sees what the agent wants to do and chooses whether to approve or reject. Use Ask approvals when: * The agent is new or still being tuned * Outputs leave your company or affect customers * The workflow changes records in important systems * A human needs accountability for the final decision * You want an audit trail of manual sign-off ## Bypass approvals **Bypass approvals** means eligible approval prompts are approved automatically so the run can continue without waiting for a human click. Bypass approvals are useful for stable, low-risk workflows where the agent's behavior is well understood. Bypass does not turn blocked tools into allowed tools. A blocked action remains blocked, and tool policy should still be used for actions that must never run. Use bypass carefully: * Start new agents with Ask approvals until the workflow is predictable * Keep destructive or externally visible actions behind tool policy or explicit review * Review run history after enabling bypass * Prefer bypass for repeatable internal tasks with clear inputs and low blast radius ## Settings and workspace policy The Settings page contains the workspace approval default that runners use when they are set to **Default**. From Settings, admins can manage: * The default approval mode used when a runner has no override * Toolkit defaults for read tools and write tools * Per-tool overrides for actions that should always be allowed, require approval, or be blocked * Team access and workspace configuration that affects who can approve or operate agents The effective behavior is the combination of the workspace default, the runner picker, tool policy, and any workflow gates. Bypass approvals should be treated as an operating policy, not a shortcut around governance. Keep blocked tools blocked, and keep human review on workflows where the business risk requires it. ## Recommended rollout Keep new agents in Ask approvals while you test the workflow, review outputs, and tune instructions. In the toolkit tools view, allow safe read actions, require approval for sensitive write actions, and block tools the workspace should not use. Put explicit workflow gates before final send, publish, payment, record update, or escalation steps. Once a workflow is stable, enable Bypass approvals for agents where waiting for human review is no longer necessary. Review run history, failures, and approval outcomes to keep the policy aligned with the workflow's risk. ## Related docs See how approvals behave across Chat Mode, Operator Mode, and Run Mode. Learn where action nodes and gate nodes fit inside a workflow. # Inbox Source: https://docs.decisional.com/agents/inbox Give an agent a dedicated email address and review its conversations ## Overview Inbox gives an agent a dedicated Decisional-managed email address. It is useful when the agent should send from its own identity or receive email threads that can be reviewed from Operator Mode, instead of using a person's Gmail or Outlook mailbox. Inbox setup for creating a dedicated email address for an agent ## Create an inbox Open **Inbox**, enter a unique name for the address, and wait for Decisional to confirm that it is available. The product adds the displayed email domain. Select **Create inbox**. The address is attached to this agent and can be copied from the Inbox header. Add the AgentMail tool when the workflow needs to send from this inbox. An inbox is Decisional-managed and does not require Gmail or Outlook OAuth. ## Review email threads After messages arrive, Inbox groups them into threads and shows inbound and outbound messages together. Filter the list by **All**, **Received**, **Unread**, or **Sent**. Open a thread to read the full history, inspect attachments, and see message status. New and updated threads appear in real time, and you can also refresh the list manually. ## Manage inbox access Inbox settings let you enable or disable the address, set its sender policy to **Anyone** or an allowed list, and delete the inbox. Individual threads can also be deleted from the review surface. Deleting an inbox or email thread is permanent. Confirm that the history is no longer needed before deleting it. ## Related docs Learn how Inbox fits into the complete agent workspace. Learn how tools and credentials are connected to an agent. # Instructions Source: https://docs.decisional.com/agents/instructions Understand how instructions connect integrations, tools, credentials, and agent versions ## What Are Agent Instructions? Instructions are the operating guide for an agent. They explain the goal, the order of work, the rules to follow, and what a successful result looks like. Instructions also connect the written process to the exact tools the agent can run. An instruction can say “enrich this person,” but the tool declaration tells Decisional to use a specific Apollo operation with a specific credential. Kriyaculture Email Outreach Agent instructions showing Apollo and Exa platform integrations, connected Gmail, Google Sheets, and Slackbot integrations, and an Apollo tool mapped to the platform credential In this example: * The instruction body explains the daily outreach process in plain English * The chips above the instructions show the integrations used by the agent * **Apollo** and **Exa** use Decisional's platform credentials * **Gmail**, **Google Sheets**, and **Slackbot** use connected accounts * The right panel shows the exact Apollo tool, **Enrich person with Apollo**, and the credential assigned to it * The lock beside the agent name shows that the Live version is read-only ## Integrations An **integration** is the connection layer for an app or service, such as Apollo, Gmail, Google Sheets, or Slack. The integration chips above the instructions give you a quick connection summary: | Label | What it means | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Platform** | The selected tools use a Decisional-managed credential. No provider account is needed for those tools. Usage may be metered through workspace credits. | | **Connected** or a check mark | The tools are mapped to an account connected by you or your workspace. | | **Connect** | At least one required tool does not have a usable credential yet. | Click an integration chip to open **Connect Integrations** in the right-hand panel over the chat. The panel lists the credentials, tools, and triggers attached to that integration without taking you away from the instructions. With the panel open, hover over an integration chip or integration row to highlight its matching location on the other side. Adding an integration does not give the agent every action in that app. The agent receives only the tools declared for its instructions and workflow. ## Tools Declared in Instructions A **tool** is one specific operation inside an integration. Gmail is an integration; **Create email draft** and **Send email** are two different Gmail tools. Apollo is an integration; **Enrich person with Apollo** is one Apollo tool. Dex declares the exact tool where it is needed in the instructions. The editor displays that declaration as an inline tool chip. Hover over an inline tool chip to highlight the same tool in the right-hand connection panel. Hover over a tool in the connection panel to highlight the exact place it is declared in the instructions. Both locations receive a visible outline, making it easy to follow the tool from the written step to its credential mapping. Click an inline tool chip to open its integration in the right-hand panel over the chat. The matching tool is shown with the credential it will use, such as a specific Gmail account or the Decisional **Platform** credential. ### Find Where a Tool Is Used Click an integration chip above the instructions. The connection panel opens on the right while the instructions remain visible. Open the integration to see every tool declared for this agent and the credential selected for each one. Hover over a tool in the right-hand panel. Decisional highlights the matching inline declaration in the instructions, showing exactly where that tool is used. Read the credential selector directly below the tool. It shows whether that instruction uses a platform credential, a connected account, a simulated credential, or no credential. For example, an outreach agent might use these declarations: | Instruction step | Declared tool | | --------------------------- | ----------------------------- | | Enrich the selected contact | **Enrich person with Apollo** | | Create a personalized draft | **Create Gmail draft** | | Mark the row as drafted | **Update Google Sheets row** | | Post the completion summary | **Send Slackbot message** | Behind the editor, each tool has a stable tool name such as `APOLLO_PEOPLE_ENRICHMENT`. Dex resolves that name into an inline tool chip and a tool instance for the agent. You normally do not need to type tool names yourself—tell Dex which action the instructions should perform. Be precise about the action. “Use Gmail” is ambiguous. “Create a Gmail draft and do not send it” tells Dex which tool and safety behavior the workflow needs. ## Credentials Mapped to Tools A **credential** authorizes a tool to use a particular account. Credentials are mapped to tools, not pasted into the written instructions. Each tool declaration has its own mapping: | Tool | Possible credential mapping | | ------------------------- | ----------------------------------- | | Enrich person with Apollo | Decisional **Platform** credential | | Create Gmail draft | `ravi@company.com` Gmail connection | | Read leads sheet | Company Google Sheets connection | | Send completion message | Workspace Slackbot connection | This per-tool mapping matters when an integration has more than one connected account. Two Gmail tool declarations can use different mailboxes, even when both belong to the Gmail integration. When Dex adds a tool, Decisional tries to bind it in this order: 1. A compatible user or workspace credential that is already connected 2. A supported platform credential when the tool is platform-provided 3. No credential, which leaves the tool waiting for you to connect or select an account Use the dropdown beneath a tool in the connection panel to choose a different compatible account or switch between your own account and a platform credential when supported. An integration can look available while one of its tools still needs a credential. Review every tool in the connection panel before testing the agent. ## Multiple Credentials for the Same Tool An agent can use more than one credential from the same integration. Each tool declaration has its own credential mapping, even when two declarations use the same underlying tool. For example, one agent could use Gmail like this: | Instruction step | Tool | Credential | | ---------------------------------- | --------------------- | --------------------------- | | Read new support requests | Search Gmail messages | `support@company.com` | | Check conversations with prospects | Search Gmail messages | `sales@company.com` | | Create an approved reply | Create Gmail draft | `account-owner@company.com` | The first two steps use the same Gmail search tool, but they are separate declarations and can read from different mailboxes. Ask Dex to declare the tool separately for each purpose, then select the intended account beneath each tool in the connection panel. The same pattern works for other integrations—for example, reading from two Google Sheets accounts, posting to different Slack workspaces, or using a platform credential for one Apollo read while another Apollo tool uses your connected account. ### Swap a Credential Without Rewriting the Workflow A workflow node declares **which tool operation to call**. The credential mapping decides **which account performs that operation**. Because those are separate, you can change a tool's account without rewriting the instruction or changing the node's logic. If the agent is Live, Tested, or otherwise locked, click the lock beside its name to create an editable Draft. Click the integration or inline tool chip to open the right-hand connection panel. Hover over each tool in the panel to highlight where that instance is used in the instructions. Use the dropdown below that tool to select another compatible connected account or a platform credential when available. Run a small test to confirm the new account can access the expected data and perform the action. Build and publish the Draft when it is ready. Changing the mapping keeps the same tool, instructions, and workflow node. It can still change the result because accounts may contain different data, use a different sender identity, or have different permissions. Always verify the new mapping before publishing, especially for email, CRM, file, or messaging actions. Credentials are not stored inside the workflow node. The node keeps its tool declaration, while Decisional resolves the selected credential securely when the tool runs. ## Locking and Unlocking an Agent The lock protects a stable agent configuration from accidental edits. An agent is read-only when it is in a built, tested, Live, or Paused state. It is also temporarily locked while Decisional is building, patching, or testing it. While locked, you can still read the instructions and click tool chips to inspect their mappings, but you cannot edit the instructions, add integrations, or change credentials. ### Unlock an Agent 1. Open the **Instructions** tab in Operator Mode. 2. Click the lock icon beside the agent name. 3. The agent returns to **Draft**, where you can edit its instructions and connections. 4. Build and test the updated draft. 5. Publish it when the new version is ready. Unlocking a Live or Paused agent creates a draft from the deployed version. The previous version remains available in version history, but the agent itself returns to Draft while you edit. Rebuild, test, and publish the draft before expecting scheduled or triggered production work to use the changes. A temporary lock shown during **Building**, **Patching**, or **Testing** cannot be removed. Wait for the current operation to finish. ## How the Pieces Fit Together | Concept | Answers this question | | ---------------------- | ------------------------------------------------------------------------------ | | **Instructions** | What should the agent do, and what rules should it follow? | | **Integration** | Which app or service provides the capability? | | **Tool declaration** | Which exact operation can the agent perform at this point in the instructions? | | **Credential mapping** | Which authorized account will that tool use? | | **Lock** | Is this version protected from edits or open as a Draft? | Before publishing, read the instructions from top to bottom, open every integration, confirm each tool has the intended credential, and run a small test. ## Related Documentation Learn how Apollo, Exa, Agent Mail, and Linq SMS platform credentials work. Learn how accounts, tool bindings, and workspace access are managed. Learn how drafts, versions, testing, and publishing work together. See how instructions become an executable workflow graph. # Modes Source: https://docs.decisional.com/agents/modes Understand Chat Mode, Operator Mode, and Run Mode for agents ## Agent modes Agents can be used through different surfaces depending on the job: * **Chat Mode** is for conversation, one-off work, explanations, and follow-up questions. * **Operator Mode** is for changing how the agent works. * **Run Mode** is for public run links where someone can run or review the agent without the builder surface. Each agent owns instructions, a workflow, tools, sources, triggers, runs, and approval policy. The mode picker controls which surface you use for that agent. Switching between an agent's Chat, Operator, and Run surfaces ## Agent operating modes An agent can be used in different modes depending on who is using it and what they need to do. | Mode | Use it for | Who should use it | | ----------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | **Chat Mode** | Ask questions, run one-off tasks, inspect context, and iterate conversationally | Anyone collaborating with the agent | | **Operator Mode** | Configure instructions, workflow, tools, triggers, skills, sources, runs, and approval behavior | Owners and builders of the agent | | **Run Mode** | Share a public link where people can view and run a public agent | External stakeholders or internal users who do not need the builder surface | ## Chat Mode Chat Mode is the everyday conversational surface for an agent. It is best when you want to ask the agent to explain a result, process a small request, answer questions over its sources, or continue an existing thread. Chat Mode keeps configuration changes controlled. If a request requires editing integrations, workflow structure, triggers, or other operator-level settings, the agent will route you to Operator Mode. Chat Mode showing a conversation with an agent and its workflow panel open ## Operator Mode Operator Mode is the builder and control room for an agent. Use it when you need to change how the agent works, not just ask it to do work. Operator Mode includes: * Agent instructions and build context * Workflow viewer and node configuration * Connected tools and credentials * Triggers and schedules * Skills and sources * Runs, logs, failures, and pending reviews * Agent-level approval settings Use Operator Mode for setup, debugging, and policy changes. ## Run Mode Run Mode is the shareable run experience for an agent. When an agent is made public, anyone with the link can view and run that agent from the focused public surface. Run Mode is useful for: * Intake workflows * Customer-facing request flows * Vendor or partner review * Internal forms where most users should not edit the agent * Approval pages where a stakeholder only needs the context and decision controls Public access does not remove the agent's approval policy. Tool policies, approval requirements, and blocked actions still apply. ## Choosing a mode Use Chat Mode. Use Operator Mode. Use Run Mode after making the agent public. ## Related docs Learn how approval modes, bypass approvals, and global policy work. Build and manage agents end to end. # Outputs Source: https://docs.decisional.com/agents/outputs Find, preview, and download files created by agent runs ## Overview Outputs are files and artifacts created by agent runs. Examples include a generated PDF, spreadsheet, presentation, image, or exported report. Outputs tab with generated files grouped into folders by agent run ## Browse outputs The **Folders** view groups files by their virtual path, which commonly includes the run that created them. Select a folder to see its files, size, run, and creation time. Use **List** to scan all outputs in one table. ## Preview and download files Click a file to preview it. Spreadsheet files open in a workspace tab, while supported documents open in the document preview. Use the download button when you need a local copy. The run link helps you trace an artifact back to the execution that produced it. An output is a deliverable, not memory. Saving a file does not replace State Store when the next run needs a reliable de-duplication marker, counter, cursor, or status value. ## Related docs Learn where agents keep small pieces of durable operational memory. Trace an output back to the run that created it. # Sources Source: https://docs.decisional.com/agents/sources Give your agents context with documents, files, and web links ## What Are Sources? Sources are documents and files that give your agent the context it needs to do its job. Think of them as the reference materials you'd hand a new team member — price lists, SOPs, contracts, policies, or any document your agent needs to reason over. When you upload a source, Decisional indexes it using **Retrieval-Augmented Generation (RAG)**. Your agent can then search and retrieve relevant information from your documents at runtime. ## Supported File Types Contracts, invoices, forms, reports, SOPs (up to 50MB, OCR supported) Policies, templates, procedures (Word, PowerPoint) Receipts, forms, diagrams (PNG, JPG, TIFF up to 20MB with OCR) Code, configs, raw text, JSON, XML ## Adding Sources In your agent page, click **Sources** in the left sidebar. Click **Add Source** and choose: * **Upload File** — drag and drop files (up to 50MB each) * **Add Link** — paste a URL and Decisional will fetch and index the content Decisional indexes your source (usually 10 seconds to 3 minutes depending on size). Once indexed, your agent can use it. Tell your agent when to use specific sources: ``` Reference the "Q4 Price List.pdf" for current pricing. Use the "Vendor Catalog.xlsx" to validate vendor names. ``` ## How RAG Works When your agent runs, it doesn't read every document end to end. Instead, it uses RAG to find the most relevant sections: 1. **Indexing** — your documents are chunked and semantically indexed when uploaded 2. **Retrieval** — at runtime, the agent searches for sections relevant to the current task 3. **Generation** — the agent uses the retrieved context to reason and produce output 4. **Citation** — the agent cites the specific pages and sections it referenced ## Bounding Box Citations For PDFs, Decisional shows you the **exact location** the agent read — including the page number, paragraph, and a highlighted bounding box around the text. This makes it easy to verify your agent's reasoning. ## Tips for Better Source Quality * **Use text-based PDFs** — scanned images work (via OCR) but text-based PDFs are faster and more accurate * **Remove irrelevant pages** — cover pages, blank pages, and appendices add noise * **Use clear formatting** — documents with headers and sections are easier for agents to navigate * **Keep documents focused** — one topic per file works better than large catch-all documents * **Use descriptive filenames** — "Q4 2025 Price List" is better than "pricelist\_final\_v3.xlsx" * **10-20 sources is the sweet spot** — too many sources can slow retrieval Start with fewer, high-quality sources and add more as needed. Quality beats quantity. # State Store Source: https://docs.decisional.com/agents/state-store Inspect the durable state an agent keeps between runs ## Overview The State Store is the agent's durable memory for small pieces of structured data that must survive between runs. Workflows are otherwise stateless: if a later run needs to remember what an earlier run already processed, the workflow must save that information here. Good uses include: * de-duplication markers, such as IDs that were already processed * cursors, counters, flags, and last-run timestamps * short-lived locks or values that should expire automatically * progress that another node or future run needs to continue State is stored as JSON under a **namespace** and **key**. Namespaces keep unrelated data separate. Each entry also has a version, update time, and optional expiry. State Store showing namespaced key-value memory retained between agent runs ## Inspect saved state Open **State Store** from Agent Manager to inspect what the agent currently remembers. You can search keys and values, filter by namespace, refresh the list, and expand a row to read the full JSON value. This screen is an inspection surface. The workflow's state tools create, update, or delete entries while it runs. Use State Store for small operational memory, not reports or large files. Put documents, spreadsheets, images, and other deliverables in Outputs instead. ## Related docs Learn where files and other run deliverables are stored. Inspect the runs that read or update agent state. # Versioning Source: https://docs.decisional.com/agents/versioning Switch between versions, edit drafts safely, and restore previous configurations ## Why Versioning? When your agent is live and running, you don't want to break it while making changes. Agent versioning lets you edit a draft copy of your agent without affecting the live version. When you're happy with the changes, publish the new version. ## How It Works Every time you publish an agent, Decisional saves a snapshot of its configuration — instructions, workflow, integrations, and triggers. This becomes a **version**. * **Live version** — the version currently running in production * **Draft version** — your working copy where you make changes safely Changes to a live agent are always made in a draft first. Nothing goes live until you explicitly publish. ## Editing a Live Agent When you want to update a live agent: Navigate to the agent you want to edit. You'll see its current live version. Any edits you make — updating instructions, changing integrations, modifying the workflow — are saved as a draft. Your live agent keeps running the previous version untouched. Run a test on the draft version to make sure everything works as expected. When you're satisfied, hit **Build** and then **Publish** to push the new version live. Your agent immediately starts using the updated configuration. ## Switching Between Versions Use the **version selector** on the agent page to browse your version history. You can: * **View any past version** — see exactly what instructions, workflow, and integrations were active at that point * **Restore a previous version** — roll back to an earlier configuration if something goes wrong * **Compare versions** — understand what changed between versions If a new version causes issues, you can quickly restore the previous version to get your agent back to a working state. ## What Gets Versioned Each version captures a full snapshot of your agent: | Component | Versioned? | | -------------------------- | ---------- | | Instructions | Yes | | Workflow (nodes & edges) | Yes | | Integration connections | Yes | | Triggers & schedules | Yes | | Sources and attached files | Yes | ## Best Practices * **Test before publishing** — always run a test on your draft before pushing it live * **Make incremental changes** — small, focused updates are easier to debug than large rewrites * **Use versions as checkpoints** — before a major change, make sure your current working version is published so you can roll back * **Copy your Agent ID** — you can copy your agent ID from the page header for debugging and API integration # Core Concepts Source: https://docs.decisional.com/core-concepts The building blocks of Decisional ## Overview Decisional is built around a few core concepts. Understanding these will help you get the most out of the platform. The conversational operator for running agents and reviewing agent details Durable AI workers that own repeatable workflows The step-by-step plans your agents create and execute External services where your team and agents get work done Connections that expose app accounts, tools, and triggers Every time your agent executes its workflow Documents and files that give your agents context Human review controls for sensitive actions and workflow gates Where your team organizes agents and collaborates *** ## Dex Dex is the conversational operator for Decisional. Use Dex to run agents, ask what happened in a run, view agent details, review approvals, or complete one-off tasks against the tools and context you have authorized. Learn how Dex works across the web app, Slack, email, and mobile. *** ## Agents Agents are the core operating units in Decisional. Each agent is an AI worker that owns a specific workflow and runs it for you. You create an agent by describing what you want it to do in the Decisional web app. Once live, the agent runs from manual runs, schedules, triggers, or API calls, and you manage changes through the agent surfaces. ### What Makes Up an Agent * **Instructions** — what you told the agent to do, written in plain English * **Workflow** — the step-by-step plan the agent built to carry out your instructions * **Integrations** — connections that give the agent tools and triggers for apps such as email, CRM, team chat, and spreadsheets * **Sources** — documents and files that give your agent context * **Triggers** — how your agent gets activated (schedule, event, or manual) * **Approval policy** — when the agent pauses, asks for review, bypasses eligible approvals, or blocks an action ### Agent Operating Modes | Mode | Purpose | | ----------------- | --------------------------------------------------------------------------------------------- | | **Chat Mode** | Talk with the agent, ask questions, run one-off tasks, and inspect context | | **Operator Mode** | Configure instructions, workflow, tools, triggers, skills, sources, runs, and policy | | **Run Mode** | Share a focused run page with people who should run or review work without changing the agent | Understand Chat Mode, Operator Mode, and Run Mode for agents. ### Agent States Your agent moves through these states as you set it up: * **Draft** — still being configured or built * **Ready** — tested and ready to go live * **Live** — available for scheduled, triggered, API, or manual runs * **Paused** — temporarily stopped, can be resumed anytime *** ## Workflows When you describe what you want, your agent creates a workflow — a series of steps it follows to get the job done. Each step in the workflow is a **node**. Nodes can do things like: * Read data from a spreadsheet * Call an API or integration * Process a document * Run AI reasoning * Write results back You do not need to draw every workflow step by hand. Decisional generates the graph from your instructions, then you review and change it in Operator Mode. ### Workflow Viewer You can see your agent's workflow visually at any time. It shows every node, how they connect, and the status of each step during a run. *** ## Apps Apps are external services where your team already works, such as Gmail, Slack, HubSpot, Google Sheets, or your own internal software. Agents can read from apps, take actions in them, use app events to start runs, and send completed work back to them. In Decisional, you browse and manage apps through the **Integrations** catalog. Each catalog entry describes the app and shows its connection type, connected accounts, available tools, and triggers. ### Apps, Integrations, and Credentials * An **app** is the external system where the work or data lives * An **integration** defines how Decisional connects to the app and what agents can do * A **connected account** or **credential** authorizes which account the integration can use For example, Gmail is an app. The Gmail integration exposes tools for reading and sending email, triggers for sent or received messages, and connected accounts that determine which mailbox an agent can use. *** ## Integrations An integration is Decisional's connection layer for an app. It brings the parts an agent needs into one place: * **Connected accounts** — the authorized app accounts available in the workspace * **Tools** — actions an agent can call, classified as read or write operations * **Triggers** — app events that can start an agent, delivered by polling or webhook when supported * **Approval policy** — workspace defaults and per-tool overrides that control whether a tool runs automatically or needs review ### How Integrations Work 1. Find the app in **Integrations** or let Dex identify it while building an agent 2. Connect an account using the app's supported authentication method 3. Review its available tools, triggers, and approval policy 4. Add the integration to an agent so its workflow can use those capabilities The Integrations page also provides **Tool activity** for reviewing calls and a **Custom integrations** builder for apps that are not already in the catalog. Open **Integrations** in the sidebar to browse apps, manage connected accounts, and review tool policies. *** ## Runs Every time your agent executes its workflow, that's a run. You can see all your agent's runs from the **Runs** tab. ### Run Statuses * **Running** — your agent is executing right now * **Completed** — finished successfully * **Failed** — something went wrong * **Needs Approval** — your agent is waiting for you to approve an action ### What's in a Run Each run shows you: * A step-by-step breakdown of what happened at each node * The input and output data for each step * Files your agent produced * How long it took If a run fails, you can see exactly which step broke and why. *** ## Approvals Approvals let agents pause before sensitive actions or manual decision points. A reviewer can see the context, approve the action, reject it, or route the workflow back for changes. Approval behavior comes from: * **Global approval mode** in Settings * **Agent-level approval mode** for a specific agent * **Tool approval policy** for connected tools and actions * **Workflow gates** placed directly in a workflow Use **Ask approvals** when you want a human review step. Use **Bypass approvals** only for stable workflows where eligible approval prompts can continue automatically. Learn how approval modes, bypass approvals, tool policies, and global settings work. *** ## Sources Sources are documents and files you upload to give your agents context. Think of them as reference material your agent can look up when it needs to. ### What You Can Upload * **PDFs** — contracts, invoices, forms, statements * **Spreadsheets** — price lists, templates, historical data * **Word docs** — policies, procedures, playbooks * **Images** — forms and receipts (your agent can read these with OCR) ### How Agents Use Sources Decisional uses retrieval-augmented generation (RAG) to help your agent understand documents. When your agent needs information from a source, it retrieves only the relevant sections instead of trying to process the entire file. This works even across hundreds of pages. *** ## Workspaces Workspaces are where your team organizes agents, integrations, and credentials. ### What's in a Workspace * Your agents * Connected integrations and credentials * Team members and their permissions * Sources and documents ### Team Access Invite members from your organization into your workspace. Workspace owners control who can view, edit, and manage agents. If you sign up with a company email, you'll automatically join your organization's workspace. Personal email addresses get their own workspace. *** ## How It All Fits Together Describe what you want automated in the Decisional web app Decisional creates an inspectable step-by-step plan and identifies the required tools Upload any documents your agent needs to reference Run a test, review each step, and set approval policy Set a schedule, trigger, API call, public run link, or manual run path Need changes? Open Operator Mode in the Decisional web app *** ## Next Steps Build your first agent in minutes Understand Chat Mode, Operator Mode, and Run Mode Configure review, bypass, and global approval behavior Deep dive into agent configuration and management # Custom Integrations Source: https://docs.decisional.com/custom-integrations Turn API documentation and an API key into tools that Decisional agents can use ## Connect an API That Is Not in the Catalog A custom integration lets Decisional agents work with an API that does not already have a built-in integration. Give Dex the API documentation, explain what the agent needs to do, and provide a test credential when the API requires one. Dex builds and tests the tools for you. You do not need to write the integration code yourself. A clear API reference and a working way to authenticate are usually enough to get started. Decisional Custom Integrations page showing an active Plaud builder session and completed MyGeotab and Limitless sessions Use a custom integration for an internal system, partner API, or less common service when you can provide one of these: * A developer documentation URL * An OpenAPI or Swagger specification * A HAR export captured while using the service * A cURL example or other request details Custom integrations work best with documented HTTP APIs that Decisional can reach over the public internet. Private network addresses cannot be called from the builder. ## Build a Custom Integration Open **Integrations**, choose **Custom Integrations**, and select **New session**. Custom Integration Builder showing three steps: add API docs or files, describe how the integration should be used, and let Dex configure the integration Paste the developer documentation URL into the message box. If the documentation is in a file, use the **+** button to attach an OpenAPI specification or HAR export. Tell Dex what the agent should read, create, update, or send. Name the few API actions that matter to your workflow instead of asking for every endpoint at once. If the API requires authentication, provide a working test API key or the requested test account details. Dex uses it to replay a real request, confirm the authentication method, and test each tool. Dex starts with a useful read-only action, tests its response, and then adds the remaining actions. Each action becomes a named tool with clear inputs and outputs. When the integration card appears, select **Connect**. Enter the credential fields Dex configured, such as an API key, base URL, account ID, or region. This is the credential the agent will use after setup. Select **Finish session** when the tools and credential setup are correct. The integration remains available on your organization's Integrations page and can be added to agents. ## What Dex Creates Dex turns the API into the same building blocks used by other Decisional integrations: | Part | What it does | | -------------------------- | ------------------------------------------------------------------------------- | | **Integration card** | Gives the API a name, description, and icon in the Integrations catalog | | **Credential form** | Asks users for the values the API needs, such as an API key or account URL | | **Tools** | Gives agents specific operations such as “Find a customer” or “Create an order” | | **Validation check** | Checks whether a connected credential can reach the API | | **Authentication refresh** | Can refresh supported short-lived authentication when the API requires it | Read tools only look up information. Write tools create or change something in the external system and are marked separately so your normal approval policy can protect them. Start small. Build and test one important read action before adding write actions. It is easier to confirm the data and permissions before the integration can change anything. ## Tell Dex Exactly What You Need A useful request includes the documentation, authentication method, desired actions, and one safe example to test. ```text theme={null} Build a custom integration for Acme CRM. API docs: https://docs.example.com/api Authentication: API key in the X-API-Key header Create these tools: 1. Find a customer by email — read only 2. List open orders for a customer — read only 3. Add a note to a customer — write action Use the test account and API key I provide. Test reads with customer alex@example.com. Ask for approval before the write action. ``` If the documentation is incomplete, attach a HAR export recorded while you perform the action in the app. Dex can use the captured request to identify the endpoint, headers, and request body. Only capture traffic for the service you intend to connect. ## API Keys and Other Credentials The builder needs a working test credential to prove that the integration works. Use a separate, low-permission test key when possible. During the builder session, Dex uses the test value only to test requests and the authentication check. It does not place the secret in the tool code, the integration description, or the credential form definition. After the integration is created, connect the account through the generated **Connect** form. Do not paste API keys into agent instructions or workflow nodes. The tools read the selected credential securely when they run. Treat a HAR file as sensitive. It can contain cookies, authorization headers, and private request data. Use a test account, remove unrelated traffic, and revoke temporary credentials after setup when appropriate. ## Sessions and Sharing Each builder session creates one integration. | Session status | What it means | | -------------- | ----------------------------------------------------------------------------------- | | **Active** | You can select **Resume** and continue working with Dex | | **Completed** | The session is read-only; select **View** to review the work | | **Expired** | The builder workspace is no longer active; start a new session to continue building | The session history is private to its creator. The custom integration itself belongs to the organization, so other organization members can find it on the Integrations page, connect their permitted credentials, and add its tools to agents. ## Use the Integration in an Agent After connecting the integration: 1. Open an agent and unlock it to create an editable Draft if needed. 2. Ask Dex to add the custom integration and name the tools the workflow should use. 3. Open the integration in the right-hand panel and map a credential to each tool. 4. Test the agent with a small example. 5. Inspect the run and confirm each node received and returned the expected data before publishing. Learn how integrations, tools, and credentials are shown and mapped in an agent. Learn how connected accounts and tool credentials are managed. # Dashboards and Usage Source: https://docs.decisional.com/dashboards-and-usage Monitor agent health, troubleshoot tool calls, and understand credit usage ## Operate Agents After They Go Live Building an agent is only the beginning. Once agents are running on schedules, webhooks, or requests, use Decisional's dashboards to answer three different questions: | View | Main question | Scope | | ------------------- | ------------------------------------------------------------------ | ----------------- | | **Agent Dashboard** | Are my workspace agents running successfully and on schedule? | Current workspace | | **Tool Calls** | Which integration, toolkit, or tool is failing or taking too long? | Current account | | **Usage** | Where are credits being spent, and should I set a cap? | Current account | Start with the **Agent Dashboard** for overall health. Move to **Tool Calls** when an integration action is failing or slow. Use **Usage** to understand cost and control monthly agent spend. The AI Usage and Tool Stats summaries on the Agent Dashboard are workspace-scoped. The full Usage and Tool Calls pages are account-wide. Check the account badge and use the same date range before comparing numbers across pages. ## Agent Dashboard In **Agents** mode, select **Dashboard**. This is the day-to-day operating view for the selected workspace. Agent Dashboard showing total and live agents, upcoming runs, Fixer-assisted runs, completed and failed runs, an activity chart, and published agents ### What the Summary Cards Mean | Card | What it tells you | | ----------------------- | ------------------------------------------------------------------------------------------- | | **Total Agents** | Number of agents in the workspace, with the number currently Live in parentheses | | **Upcoming Runs** | Scheduled executions that are expected to start next | | **Fixer-assisted runs** | Runs where Decisional's Fixer helped recover or repair execution during the selected period | | **Completed Runs** | Runs that finished successfully during the selected period | | **Failed Runs** | Runs that ended in failure during the selected period | The **Agent Run Activity** chart shows completed, failed, and currently running executions over time. Use the 30-day, 14-day, 7-day, 24-hour, or custom date filter to separate a one-time problem from a repeated pattern. Below the chart: * **Published Agents** shows the Live and Paused agents in the workspace * **Upcoming Runs** lists scheduled executions and their expected start time * **Past Runs** links recent executions to their agent and run status * **AI Usage** summarizes workspace model and Agent Node usage * **Tool Stats** summarizes workspace tool volume and success A small number of Fixer-assisted runs is not the same as a failed run—the Fixer may have recovered the execution. Repeated Fixer assistance on the same agent is still worth investigating because it can reveal a fragile instruction, changing data, or an unreliable integration. ### When Something Looks Wrong 1. Open the affected run from **Past Runs**. 2. Select the run on the workflow graph. 3. Find the first failed, incomplete, or unusually slow node. 4. If it is an integration action, open **Tool Calls** to compare it with other calls to the same tool. 5. If it is an AI or Agent Node step, open **Usage** to review model, Agent Node, and per-agent activity. Learn how to inspect node execution, inputs, outputs, logs, and failures on the workflow run surface. ## Usage and Credits Open the full **Usage** page from the **AI Usage** section on the Agent Dashboard. The account badge shows whether the numbers belong to an organization or a personal account. Usage dashboard showing available, reserved, total, and spent credits, the Agent Spend Default, and a Daily Usage chart ### Balance and Spend | Metric | Meaning | | ----------------- | ----------------------------------------------------- | | **Available** | Current credits available after active reservations | | **Reserved** | Credits temporarily set aside for active metered work | | **Total Balance** | Available and reserved credits combined | | **Spent** | Credits actually charged during the selected period | The **Daily Usage** chart groups credit-equivalent activity by resource type. Depending on the work performed, it can include: * **AI / LLM Calls** for model requests * **Agent Node** for sandboxed agent execution, including supported Claude Code, Codex, or Cursor runtimes * **Platform Tools** for metered platform-provided integration calls * **Workflow Runs**, **Agent Builds**, and **Storage** when those resource types apply “Credit-equivalent” can include work paid for with a personal provider key. Personal-key usage is tracked so you can understand total activity, but it is not deducted from the Decisional credit balance. The **Spent** card and charged amounts exclude that personal-key portion. ### Understand What Is Driving Spend Scroll down to compare models and agents. Usage dashboard showing Spend by Model and Agent Spend and Caps tables with LLM spend, Agent Node spend, calls, averages, cap usage, remaining credits, and status Use **Spend by Model** to compare: * Credits attributed to each model * Number of model calls * Input and output tokens * Average credits per call Use **Agent Spend & Caps** to compare: * LLM spend and Agent Node spend for each agent * Total calls and average credit use per model call * Monthly cap usage, active reservations, and remaining credits * Whether an agent is Live, at its cap, or blocked by its cap You can search by agent name, UUID, or `agt_` public ID. The **All time** option changes the spend columns, but cap usage always represents the current UTC month. ### Set Monthly Agent Caps **Agent Spend Default** sets the account-wide monthly cap for workflow-run credits. Individual agents can inherit this default or use their own override. Enter a whole number of credits in **Monthly cap** and select **Save**. Leave the default clear when agents should be uncapped unless they have their own override. In **Agent Spend & Caps**, compare each agent's current-month usage with its effective cap and remaining credits. Check the agent's model calls, Agent Node activity, and recent runs. A sudden increase may come from more work, repeated retries, unexpectedly large inputs, or a workflow loop. Update the account default when the policy should change for many agents. Use an individual override when one agent has a different workload. The lower sections of the Usage page provide a full audit trail: * **Usage by Resource Type** summarizes where credits went * **Credit Grants** shows granted amounts, remaining balances, and expiration * **Active Reservations** shows credits currently held for work in progress * **Transaction Ledger** lists grants, debits, reservations, settlements, refunds, adjustments, and expirations ## Tool Calls Open the full **Tool Calls** page from **Tool Stats** on the Agent Dashboard or from the Integrations area. Use it when a workflow reaches an integration step but the result is slow, missing, or incorrect. Tool Calls dashboard showing total calls, success rate, average latency, provider count, calls over time, calls by provider, and top toolkits ### Read the Top-Level Metrics | Metric | Meaning | | -------------------- | ---------------------------------------------------------------------------------------- | | **Total tool calls** | Number of recorded tool operations in the selected period | | **Success rate** | Share of calls that completed successfully, with errors and timeouts shown underneath | | **Avg latency** | Average call duration; p95 shows the duration that 95 percent of calls completed within | | **Providers** | Number of tool providers with activity, with the busiest providers summarized underneath | The **Tool Calls Over Time** chart separates successful calls from errors and timeouts. A short error spike can indicate a provider incident. A steady error rate on one toolkit is more likely to point to credentials, permissions, inputs, or an API change. Continue down the page to compare: * Calls, errors, and average latency by provider * Top toolkits and individual tools * Agents generating the most tool activity * Recent individual tool calls Use the filters to narrow recent calls by provider, toolkit, status, caller, agent, thread, or search text. This lets you move from an account-wide spike to the exact agent and tool involved. Tool Calls covers recorded integration tools and supported Agent Node or orchestrator actions. Some internal workflow platform tools may be only partially represented, so the total is not necessarily the same as the number of workflow nodes executed. ## A Simple Weekly Review Open the Agent Dashboard for each active workspace. Look for failed runs, recurring Fixer assistance, paused agents, and missed or unexpected schedules. Open Tool Calls when errors increase. Narrow the data from provider to toolkit to tool, then identify the affected agent and recent call. Open Usage and compare the current period with the previous one. Check the resource, model, and agent tables for unexpected changes. Review the default monthly cap and individual agent overrides. Raise a cap only after confirming the higher usage is expected. These views work together: the Agent Dashboard shows **what changed**, Tool Calls helps explain **why an integration step changed**, and Usage shows **what the work cost**. # Working with Agents Source: https://docs.decisional.com/guides/agents Master agent creation, configuration, and optimization ## What Are Agents? **Agents are AI workers** that execute business workflows. They follow your instructions, use configured tools and sources, and produce runs you can inspect. Agents combine **your instructions** + **your tools** + **your sources** + **approval policy** to automate workflows while keeping runs reviewable.