> ## Documentation Index
> Fetch the complete documentation index at: https://docs.decisional.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Working with 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.
## 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:
The operating home for the agent. This is where you manage instructions, workflow, runs, outputs, inbox, state, activity, and context.
The material the agent can use while working. This includes files, sources, uploaded skills, and platform skills loaded for the job.
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.
The plain-English operating spec for the agent. Instructions cover the job, success criteria, edge cases, triggers, tools, and runtime parameters.
The inspectable graph of nodes the agent executes. The workflow shows the steps, tool calls, gates, branching, and generated outputs.
The execution history for the agent. Runs show status, logs, node activity, approvals, files, outputs, and failure details.
Files, structured results, and other artifacts produced by the agent. Use outputs to inspect what a run created or download generated files.
The agent's email-style intake and response surface when an agent has an inbox. Use it to review inbound requests and outbound replies.
Durable state the agent keeps between runs, such as remembered values, counters, intermediate records, or configuration used by the workflow.
A recent timeline of actions, test runs, completed runs, and other agent events. Use it to jump back into the latest work.
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.
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
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
```
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.
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.
Your agent identifies the required tools and integrations. Open the connections panel to connect any apps it needs.
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
**Bad Example:**
```
Process invoices
```
**Good Example:**
```
You are an Invoice Processing Agent.
For each invoice PDF uploaded:
1. Extract: Invoice number, date, vendor, line items, total
2. Verify the total matches the sum of line items
3. Look up the vendor in the approved vendor source
4. Write the extracted data to the connected invoice system
5. If total > $10,000, flag for manual review
```
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
```
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
```
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.
```
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
Contracts, invoices, forms, reports, SOPs
Price lists, catalogs, historical data
Policies, templates, procedures
Receipts, forms, diagrams (OCR enabled)
Company websites, documentation, APIs
Code, configs, raw text data
### How to Add Sources
In your agent page, click **Sources** in the left sidebar
Click **Add Source** → **Upload File**
Drag and drop multiple files at once (up to 50MB per file)
Click **Add Source** → **Add Link**
Paste a URL. Decisional will fetch and index the content.
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:
1. Send an email via Gmail to the customer
2. Update the deal stage in HubSpot to "Quote Sent"
3. Post a notification to the #sales Slack channel
4. 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
**Click the Run button**
Best for:
* Testing new agents
* One-off tasks
* Ad-hoc workflows
**How to use:**
Click **Run Agent** or start a manual run from Run Mode
**Time-based automation**
Best for:
* Daily reports
* Weekly summaries
* End-of-month processing
**Examples:**
* "Every day at 9 AM"
* "Every Monday at 8 AM"
* "First day of each month at 10 AM"
* "Every 6 hours"
**How to set:**
1. Click the calendar icon in Instructions tab
2. Choose frequency
3. Set time and timezone
**Triggered by external events**
Best for:
* Real-time automation
* Responding to user actions
* Integration-driven workflows
**Examples:**
* When a new record is created in a connected system
* When an email is received
* When a form is submitted
* When a webhook is called
* When a file is uploaded to Google Drive
**How to set:**
1. Connect the relevant integration
2. Go to Triggers tab
3. Select event type
4. Configure conditions (optional filters)
**Programmatic execution**
Best for:
* Custom applications
* External systems
* Developer workflows
**How to use:**
Make a POST request to the Decisional API:
```bash theme={null}
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
Create a small dataset (5-10 rows) with:
* Typical cases
* Edge cases
* Known error cases
Start a manual run and review the run details, node logs, outputs, and approvals
Check that:
* All expected columns are filled
* Data is accurate
* Formatting is correct
* Edge cases are handled
If results aren't perfect, refine your instructions and test again
### Common Issues & Fixes
**Problem:** Some columns are empty or incomplete
**Solutions:**
* 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"
**Problem:** Agent does something unexpected
**Solutions:**
* Break down complex steps into simpler ones
* Add more examples
* Use numbered steps instead of paragraphs
* Be more explicit about what NOT to do
**Problem:** Agent says it doesn't have the required data
**Solutions:**
* 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
**Problem:** Agent takes too long to run
**Solutions:**
* 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:
Collects and validates input data
Performs the core task
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:
1. Mark status as "Needs Review"
2. Send a Slack notification to @sales-manager
3. 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:
```
1. Fetch customer data from Salesforce API
2. Enrich with data from Clearbit API
3. Update the CRM with combined data
4. Send personalized email via Gmail
```
***
## Monitoring & Optimization
### View Run History
Click **Runs** in the left sidebar
See all past runs with:
* Status (Running, Completed, Failed, Needs Review)
* Duration
* Timestamp
* Inputs and outputs
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
* Upload only necessary sources
* Process in batches
* Use lighter file formats
* Cache reference data in a connected system
* Add more examples
* Upload better source documents
* Add validation rules
* Test with edge cases
* Increase schedule frequency
* Use event-based triggers
* Process in parallel (multiple agents)
* Optimize data structure
* 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
Learn how files and sources give agents context
Ask questions about agents, runs, and approvals
Follow step-by-step guides for common workflows