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.

How an Agent is Organized

Agents are the main objects you create, operate, and share in Decisional. Dex can run agents and show details about their runs, while configuration changes happen in the Decisional web app. Think about an agent in three layers:

Workspace

The operating home for the agent. This is where you manage instructions, workflow, runs, outputs, inbox, state, activity, and context.

Context

The material the agent can use while working. This includes files, sources, uploaded skills, and platform skills loaded for the job.

Modes

The ways people operate the agent: Chat Mode for conversation, Operator Mode for configuration, and Run Mode for public execution.

Workspace Elements

The agent workspace is the control surface for a specific agent. The Agent Manager separates the agent’s configuration, execution history, generated artifacts, inbox, state, activity, and context.

Instructions

The plain-English operating spec for the agent. Instructions cover the job, success criteria, edge cases, triggers, tools, and runtime parameters.

Workflow

The inspectable graph of nodes the agent executes. The workflow shows the steps, tool calls, gates, branching, and generated outputs.

Runs

The execution history for the agent. Runs show status, logs, node activity, approvals, files, outputs, and failure details.

Outputs

Files, structured results, and other artifacts produced by the agent. Use outputs to inspect what a run created or download generated files.

Inbox

The agent’s email-style intake and response surface when an agent has an inbox. Use it to review inbound requests and outbound replies.

State Store

Durable state the agent keeps between runs, such as remembered values, counters, intermediate records, or configuration used by the workflow.

Activity

A recent timeline of actions, test runs, completed runs, and other agent events. Use it to jump back into the latest work.

Policy

Approval behavior, tool permissions, public access, and other operating controls that govern what the agent can do automatically.

Agent Context

Context is the knowledge and capability the agent brings into a run. Keep it focused so the agent can retrieve the right information and load the right skill for the job.

Context	What it is for
Files and sources	PDFs, documents, spreadsheets, links, and uploaded files the agent can search and use as reference material
Platform skills	Built-in skills for connected systems, such as listing files, downloading files, sending messages, or working with business records
User skills	Reusable instructions or API-specific guidance you upload to teach the agent a specialized task
Connected tools	Authorized tool instances and credentials the agent can call during a workflow
Run files and outputs	Files uploaded for a specific run and files generated by previous workflow steps

Agent 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 Modes

Learn how agents work across Chat Mode, Operator Mode, and Run Mode.

Agent Lifecycle

The app shows the public state of each agent:

State	What it means
Draft	The agent is still being configured, connected, built, or tested.
Ready	The agent has been tested and can be made live.
Live	The agent can run from manual starts, schedules, triggers, API calls, or public run links.
Paused	The agent is temporarily stopped. No scheduled or triggered runs execute until it is resumed.

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, such as PDFs, price lists, or templates.Example:

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

Answer Clarifying Questions

Your agent may ask follow-up questions to fill in gaps, such as which source 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 edit anything that’s off in the Decisional web app.

Connect Integrations

Your agent identifies the required tools and integrations. Open the connections panel to connect any apps it needs.

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 Operator Mode in the Decisional web app for configuration-level edits.

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 approved vendor source
Write the extracted data to the connected invoice system
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
- Output is saved to the connected system

Handle Edge Cases

Anticipate problems and tell your agent what to do:

Edge cases:
- If vendor is not found, flag it for review
- 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 |

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”

Connecting Integrations

Integrations let your agent take actions in the systems where work happens.

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

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 that source names, field names, and instructions match

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 CRM 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 context and generated outputs
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 a connected system

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 data 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 Sources

Learn how files and sources give agents context

Dex

Ask questions about agents, runs, and approvals

Workflows

Follow step-by-step guides for common workflows

​What Are Agents?

Core Principle

​How an Agent is Organized

Workspace

Context

Modes

​Workspace Elements

Instructions

Workflow

Runs

Outputs

Inbox

State Store

Activity

Policy

​Agent Context

​Agent Modes

Agent Modes

​Agent Lifecycle

​Creating Your First Agent

​Writing Effective Instructions

​Best Practices

​Adding Sources

​Types of Sources

PDFs

Spreadsheets

Documents

Images

Web Links

Text Files

​How to Add Sources

​Connecting Integrations

​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 Sources

Dex

Workflows

What Are Agents?

How an Agent is Organized

Workspace Elements

Agent Context

Agent Modes

Agent Lifecycle

Creating Your First Agent

Writing Effective Instructions

Best Practices

Adding Sources

Types of Sources

How to Add Sources

Connecting Integrations

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