Working with Agents - Decisional Documentation

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.

Core Principle

Agents combine your instructions + your tools + your sources + approval policy to automate workflows while keeping runs reviewable.

Agents as top-level objects

Agents are the main objects you create, operate, and share in Decisional. Dex can help you build or change them, but the agent is the durable worker that owns the process. Each agent has:

A plain-English job description
A workflow that carries out that job
Tools, sources, and triggers for the systems it can access
Runs and logs that show what happened
Approval policy that controls when the agent pauses, asks for review, bypasses eligible approvals, or blocks an action

Dex and Agent Modes

Learn how Dex works with agents across Chat Mode, Operator Mode, and Run Mode.

Operating modes

Use the mode picker to match the agent surface to the job:

Mode	Best for
Chat Mode	Conversational requests, one-off work, explanations, and follow-up questions
Operator Mode	Changing instructions, workflows, tools, triggers, sources, skills, and approval behavior
Run Mode	Sharing a public run page with people who should not edit the agent

Configuration changes belong in Operator Mode. Run Mode is for running or reviewing a public agent, not rebuilding it.

Agent Lifecycle

Internal statuses (backend workflow granularity):

init, active, inactive - platform-level flags, not part of the setup wizard flow
draft → connecting → connected → building → built → testing → tested → live ↔ paused - setup + execution lifecycle

External statuses (user-visible UI):

draft - any pre-tested state (draft/connecting/connected/building/built/testing)
ready - tested
live - agent is running
paused - agent paused; no runs execute until resumed

Internal state diagram:

Creating Your First Agent

Describe What You Want

From the home page, type what you want to automate in the prompt box. You can also upload files for context — spreadsheets, PDFs, price lists, or templates.Example:

I want to process incoming invoices from my email,
extract key details, and update my tracking spreadsheet

Answer Clarifying Questions

Your agent may ask follow-up questions to fill in gaps — like which spreadsheet to use, what format you want output in, or how to handle edge cases.

Review Instructions

Decisional writes up a set of instructions — a plain-English summary of exactly what your agent will do. Review them and tell the agent to change anything that’s off.

Connect Integrations

Your agent identifies the required tools and integrations. Open the connections panel to connect any apps it needs, or ask Dex to start the connection flow.

Build & Test

Build the workflow, then test it to make sure everything works. Action nodes can pause for approval depending on the agent and tool policy.

Start with a simple workflow, test it, then gradually add complexity. Use Dex for change requests and Operator Mode for configuration-level edits.

Agent Components

Every agent has six key components:

Instructions

Natural language description of what the agent should do

Workflow

The graph of nodes the agent executes to complete the work

Sources

Documents that provide context (PDFs, links, files)

Integrations

Connected services such as email, CRM, team chat, and spreadsheets

Triggers

How the agent gets activated (schedule, event, manual)

Approval Policy

Rules for review, bypass approvals, and blocked actions

The sections below cover the setup details you will tune most often.

Writing Effective Instructions

Instructions are the most important part of your agent. Write them like you’re training a smart new hire.

Best Practices

Be Specific and Clear

Bad Example:

Process invoices

Good Example:

You are an Invoice Processing Agent.

For each invoice PDF uploaded:
Extract: Invoice number, date, vendor, line items, total
Verify the total matches the sum of line items
Look up the vendor in the Vendors worksheet
Add a new row to the Invoices worksheet with extracted data
If total > $10,000, flag for manual review

Define Success Criteria

Tell your agent what “done” looks like:

Success means:
- All required fields are filled
- Total is verified
- Vendor is matched
- Row is added to the correct worksheet

Handle Edge Cases

Anticipate problems and tell your agent what to do:

Edge cases:
- If vendor is not found, add them to the Vendors worksheet
- If invoice is duplicate, skip it and log to Errors sheet
- If PDF is unreadable, flag for manual review
- If total doesn't match, recalculate and note discrepancy

Reference Sources

If you’ve uploaded context documents, tell your agent when to use them:

Reference the "Invoice Processing SOP.pdf" for formatting rules.
Use the "Vendor Catalog.xlsx" to validate vendor names.

Use Examples

Show your agent what good output looks like:

Example output row:
| Invoice # | Date | Vendor | Total | Status |
| INV-001 | 2025-01-15 | Acme Corp | $5,432.12 | Approved |

Instruction Template

Use this template as a starting point:

You are a [Job Title] Agent.

**Your job:**
[1-2 sentence description of the agent's purpose]

**Inputs:**
- [What data the agent receives]
- [Where it comes from]

**Process:**
1. [First step]
2. [Second step]
3. [Third step]

**Outputs:**
- [What the agent produces]
- [Where it goes]

**Rules:**
- [Important constraints]
- [Quality standards]
- [Edge case handling]

**Success criteria:**
- [How to know it worked]

Configuring Your Worksheet

The worksheet is your agent’s data layer - where it reads inputs and writes outputs.

Worksheet Structure Tips

Clear Headers
Input vs Output
Use Formulas
Data Validation

Agents understand Excel formulas! Use them for calculations:

Total column: =Quantity * UnitPrice
Tax column: =Total * 0.08

The agent will respect your formulas and use calculated values.

Working with Multiple Sheets

You can have multiple sheets in one workbook:

Inputs: Raw data the agent processes
Outputs: Results the agent generates
Reference: Lookup tables (price lists, vendor catalogs)
Errors: Failed items that need manual review

Reference sheets in your instructions:

Read customer requirements from the "Requests" sheet.
Look up prices from the "Price List" sheet.
Write quotes to the "Generated Quotes" sheet.
Log any errors to the "Errors" sheet.

Adding Sources

Sources provide context to your agents so they can make informed decisions.

Types of Sources

PDFs

Contracts, invoices, forms, reports, SOPs

Spreadsheets

Price lists, catalogs, historical data

Documents

Policies, templates, procedures

Images

Receipts, forms, diagrams (OCR enabled)

Web Links

Company websites, documentation, APIs

Text Files

Code, configs, raw text data

How to Add Sources

Click Sources Tab

In your agent page, click Sources in the left sidebar

Upload Files

Click Add Source → Upload FileDrag and drop multiple files at once (up to 50MB per file)

Add Web Links

Click Add Source → Add LinkPaste a URL. Decisional will fetch and index the content.

Name Your Sources

Give each source a descriptive name so you can reference it in instructions:Example: “Q4 2024 Price List” instead of “pricelist_final_v3.xlsx”

RAG and Citations

Decisional uses Retrieval-Augmented Generation (RAG) to help agents understand your documents:

How RAG Works

Indexing: Your documents are processed and semantically indexed
Retrieval: When the agent needs info, relevant sections are retrieved
Reasoning: The agent uses retrieved context to make decisions
Citation: The agent cites specific pages/sections it referenced

Bounding Box Citations

For PDFs, Decisional highlights the exact location the agent read:

Page number
Paragraph or section
Bounding box showing the highlighted text

This makes it easy to verify the agent’s reasoning.

Source Quality Tips

Better sources = better agent performance:

Use text-based PDFs (not scanned images, unless you need OCR)
Organize documents clearly with headers and sections
Remove irrelevant pages (cover pages, blank pages)
Use descriptive filenames
Keep documents focused (one topic per file)

Connecting Integrations

Integrations let your agent take actions beyond the spreadsheet.

Available Integration Categories

Communication
CRM & Sales
Storage & Files
Databases
Other

Email:

Gmail
Outlook
SMTP

Messaging:

Slack
Microsoft Teams
Discord

Use cases:

Send quotes to customers
Notify team of errors
Post updates to channels

Using Integrations in Instructions

Once connected, reference integrations in your agent instructions:

When a quote is approved:
Send an email via Gmail to the customer
Update the deal stage in HubSpot to "Quote Sent"
Post a notification to the #sales Slack channel
Save the quote PDF to Google Drive

Make sure you’ve authorized the integration in Settings → Integrations before referencing it in instructions.

Setting Up Triggers

Triggers control when your agent runs.

Trigger Types

Manual
Schedule
Event-Based
API

Click the Run buttonBest for:

Testing new agents
One-off tasks
Ad-hoc workflows

How to use: Click Run Agent or start a manual run from Run Mode

Programmatic executionBest for:

Custom applications
External systems
Developer workflows

How to use: Make a POST request to the Decisional API:

curl -X POST https://api.decisional.com/v1/agents/{agent_id}/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "your input data"}'

Contact support if you need programmatic access for this workflow.

Testing Your Agent

Before going live, always test your agent thoroughly.

Testing Workflow

Prepare Test Data

Create a small dataset (5-10 rows) with:

Typical cases
Edge cases
Known error cases

Run Test

Start a manual run and review the run details, node logs, outputs, and approvals

Review Output

Check that:

All expected columns are filled
Data is accurate
Formatting is correct
Edge cases are handled

Check Citations

If using sources, verify the agent cited the right documents

Iterate Instructions

If results aren’t perfect, refine your instructions and test again

Common Issues & Fixes

Agent is missing data

Problem: Some columns are empty or incompleteSolutions:

Make it explicit in instructions: “You MUST fill all columns”
Provide examples of complete output
Add a validation rule: “If any required field is missing, flag for review”

Agent misunderstands instructions

Problem: Agent does something unexpectedSolutions:

Break down complex steps into simpler ones
Add more examples
Use numbered steps instead of paragraphs
Be more explicit about what NOT to do

Agent can't find information

Problem: Agent says it doesn’t have the required dataSolutions:

Check that sources are uploaded and indexed
Reference sources by name in instructions
Verify the information is actually in the documents
Check worksheet column names match instructions

Agent is too slow

Problem: Agent takes too long to runSolutions:

Reduce the number of sources (only upload what’s needed)
Process in smaller batches
Remove large, irrelevant documents
Simplify instructions (fewer steps)

Advanced Agent Patterns

Multi-Step Workflows

For complex workflows, break them into multiple agents:

Agent 1: Data Collection

Collects and validates input data

Agent 2: Processing

Performs the core task

Agent 3: Distribution

Sends results to stakeholders

Connect them with triggers: Agent 1’s completion triggers Agent 2, and so on.

Human-in-the-Loop

For high-stakes decisions, add manual review:

If the quote total exceeds $50,000:
Mark status as "Needs Review"
Send a Slack notification to @sales-manager
Wait for human approval before proceeding

Error Handling

Build resilience into your agents:

Error handling rules:
- If an error occurs, log it to the "Errors" sheet
- Send a notification to the admin
- Continue processing remaining items (don't stop)
- Retry failed items once before flagging

Chaining with APIs

Use agents to orchestrate API calls:

Fetch customer data from Salesforce API
Enrich with data from Clearbit API
Update the worksheet with combined data
Send personalized email via Gmail

Monitoring & Optimization

View Run History

Go to Runs Tab

Click Runs in the left sidebar

Review Executions

See all past runs with:

Status (Running, Completed, Failed, Needs Review)
Duration
Timestamp
Inputs and outputs

Click for Details

Click any run to see:

Full execution log
AI reasoning step-by-step
Source citations
Error messages (if failed)

Performance Metrics

Track your agent’s performance:

Success rate: % of runs that complete successfully
Average duration: How long runs take
Error patterns: Common failure reasons
Manual review rate: How often human intervention is needed

Optimization Tips

Reduce Run Time

Upload only necessary sources
Process in batches
Use lighter file formats
Cache reference data in worksheet

Improve Accuracy

Add more examples
Upload better source documents
Add validation rules
Test with edge cases

Handle More Volume

Increase schedule frequency
Use event-based triggers
Process in parallel (multiple agents)
Optimize worksheet structure

Reduce Errors

Add error handling rules
Validate inputs first
Use try-catch patterns
Log everything for debugging

Best Practices

Start simple, iterate: Don’t try to build a perfect agent on day one. Start with the core workflow and add features over time.

Test with real data: Use actual examples from your business, not synthetic test data.

Document your agents: Add comments in instructions explaining why certain rules exist.

Version control: Before making major changes, duplicate your agent so you can roll back if needed.

Monitor continuously: Check run history regularly, especially in the first few weeks.

Get feedback: Have actual users test your agent and report issues.

Next Steps

Working with Worksheets

Master spreadsheet operations and data management

Working with Sources

Learn advanced document processing and RAG

Dex

Use the chat interface to debug and iterate

Workflows

Follow step-by-step guides for common workflows

Documentation Index

​What Are Agents?

Core Principle

​Agents as top-level objects

Dex and Agent Modes

​Operating modes

​Agent Lifecycle

​Creating Your First Agent

​Agent Components

Instructions

Workflow

Sources

Integrations

Triggers

Approval Policy

​Writing Effective Instructions

​Best Practices

​Instruction Template

​Configuring Your Worksheet

​Worksheet Structure Tips

​Working with Multiple Sheets

​Adding Sources

​Types of Sources

PDFs

Spreadsheets

Documents

Images

Web Links

Text Files

​How to Add Sources

​RAG and Citations

​Connecting Integrations

​Available Integration Categories

​Using Integrations in Instructions

​Setting Up Triggers

​Trigger Types

​Testing Your Agent

​Testing Workflow

​Common Issues & Fixes

​Advanced Agent Patterns

​Multi-Step Workflows

​Human-in-the-Loop

​Error Handling

​Chaining with APIs

​Monitoring & Optimization

​View Run History

​Performance Metrics

​Optimization Tips

Reduce Run Time

Improve Accuracy

Handle More Volume

Reduce Errors

​Best Practices

​Next Steps

Working with Worksheets

Working with Sources

Dex

Workflows

What Are Agents?

Agents as top-level objects

Operating modes

Agent Lifecycle

Creating Your First Agent

Agent Components

Writing Effective Instructions

Best Practices

Instruction Template

Configuring Your Worksheet

Worksheet Structure Tips

Working with Multiple Sheets

Adding Sources

Types of Sources

How to Add Sources

RAG and Citations

Connecting Integrations

Available Integration Categories

Using Integrations in Instructions

Setting Up Triggers

Trigger Types

Testing Your Agent

Testing Workflow

Common Issues & Fixes

Advanced Agent Patterns

Multi-Step Workflows

Human-in-the-Loop

Error Handling

Chaining with APIs

Monitoring & Optimization

View Run History

Performance Metrics

Optimization Tips

Best Practices

Next Steps