Agent Studio Guide

The Agent Studio is the unified interface for creating, configuring, and managing AI agents in Datafi. It combines the Agent Builder (configuration) and Workflow Builder (visual orchestration) into a single workspace. This guide walks through every section of the Studio.

---

Opening the Agent Studio

Navigate to AI > Agent Catalog and either:

• Click New Agent to create a new agent, or
• Click an existing agent card and then Edit to open it in the Studio.

Two Creation Paths

Method	Description	Best For
Manual	Start with a blank agent or select a template. Fill in each tab yourself.	Experienced users who know exactly what they want.
AI-Assisted	Describe your agent in natural language. The conversational wizard gathers requirements and generates a workflow.	New users, rapid prototyping, complex workflows.

When creating manually, you provide a title (display name) and optional description. The system auto-generates a unique agent name (identifier) from the title.

---

Identity Tab

The Identity tab defines who the agent is and what it aims to accomplish.

Field	Description
Title	Human-readable display name shown in the catalog and UI.
Name	Unique identifier, auto-generated from the title. Used in API calls and references.
Version	Semantic version (e.g., 1.0.0). Increment when making changes.
Description	Summary of the agent's purpose, displayed in the catalog card.
Author	The user or team that created the agent.
Tags	Labels for categorization and discovery (e.g., sales, analytics, monitoring).
Icon	Visual identifier. Choose from Material Symbols icons or upload a custom logo image. Toggle between icon and upload modes.
Goals	List of objectives the agent pursues during each run.
Success Criteria	Measurable conditions that define a successful run (e.g., "Report generated in under 60 seconds").

---

Capabilities Tab

Capabilities define what tools and data sources the agent can use.

Tools

Add tools from the available tool library. For each tool, configure:

• Permissions -- Which operations the tool can perform: Read, Write, Execute, Delete.
• Database access -- Which data sources the tool can query.
• Row limits -- Maximum number of rows a query tool can return.
• Complexity constraints -- Limits on query complexity (joins, subqueries).
• Output format -- Expected output type (JSON, text, table).
• Channel/recipient restrictions -- For communication tools like email, restrict allowed recipients.
• TTL and size limits -- Time-to-live and maximum output size.

Available Tools

Tool	Category	Description
query	Data	Execute PRQL/SQL queries against connected data sources
search	Data	Semantic search across data catalog metadata
llm	AI	Call the configured LLM for reasoning or generation
vision	AI	Analyze images using GPT-4 Vision
vision_extraction	AI	Extract structured data from documents
web_search	External	Search the web for information
web_fetch	External	Fetch and parse content from a URL
http_api	External	Make HTTP requests to external APIs
email	Communication	Send email notifications
ftp	Communication	Upload/download files from FTP/SFTP servers
json	Transform	Parse, transform, and query JSON using JQ expressions
array	Transform	Map, filter, reduce, and sort array data
csv	Transform	Parse or generate CSV files
csv_writer	Transform	Generate CSV files from structured data
csv_formatter	Transform	Format and transform CSV data
markdown	Format	Generate formatted markdown documents
markdown_table_formatter	Format	Format data as HTML or markdown tables
regression	Analytics	Statistical linear regression analysis
summarize	AI	Summarize text with configurable length

Data Sources

Specify which connected data sources the agent can access. The agent can only query listed sources, and all queries are further restricted by ABAC policies.

Output Formats

Define the formats the agent produces: text, json, markdown, table, or any combination.

---

Behavior Tab

Behavior controls how the agent executes and reasons.

Setting	Description	Options
Execution Mode	How steps are processed.	Sequential, Parallel, Hybrid
Timeout	Maximum execution time per run.	1 -- 3600 seconds
Concurrency Limit	Maximum parallel executions.	1 -- 100

Retry Policy

Configure how the agent handles transient failures:

Setting	Description
Max Attempts	Number of retry attempts before failing.
Backoff Strategy	Fixed, Linear, or Exponential delay between retries.
Initial Delay	Wait time before the first retry.
Max Delay	Upper bound on retry delay.
Retry On	Error types that trigger a retry (e.g., network_error, timeout, rate_limit).
Do Not Retry	Error types that should fail immediately (e.g., validation_error, permission_denied).

Reasoning Strategy

Strategy	Best For
Step-by-step	Linear analysis, logical progression
Parallel exploration	Open-ended questions, multiple valid approaches
Hypothesis-driven	Investigative analysis, anomaly detection
Depth-first	Detailed root cause analysis
Breadth-first	Exploratory analysis, option comparison

---

Safety & Security Tab

Safety settings constrain the agent to keep it secure, efficient, and compliant.

Constraints

Free-text rules the agent must follow. Examples:

• "Never modify production data"
• "PII must be masked in email outputs"
• "Only read from approved data sources"

Validation Rules

Define rules with conditions and error handling behavior. Validation runs before tool execution.

Output Filters

Automatically redact or transform sensitive values in agent output.

Resource Limits

Resource	Description	Default	Maximum
Tokens per request	LLM tokens per individual tool call.	10,000	100,000
API calls per run	Maximum external API calls.	100	500
Daily token budget	Total tokens across all runs per day.	50,000	500,000

Security Controls

Control	Description
PII Prevention	Scrub personally identifiable information before sending to LLMs.
SQL Injection Prevention	All generated queries pass through parameterized validation.
Database Access Control	Specify allowed and blocked databases for the agent.

---

Testing Tab

Test your agent before publishing to ensure it behaves correctly.

Test Scenarios

Define test cases with:

• Query/Input -- Sample input parameters for the test.
• Context -- Additional context data to provide.
• Expected Output -- What the agent should produce.
• Assertions -- Validation rules that must pass (e.g., execution_time_ms < 60000).

Evaluation Metrics

Track quality metrics across test runs:

• Accuracy -- How often the agent produces correct results.
• Latency -- Execution time percentiles (p50, p95, p99).
• Token efficiency -- Tokens consumed relative to output quality.

Regression Tests

Save test scenarios as regression tests that run automatically when the agent specification is modified.

---

Monitoring Tab

Configure observability for production agents.

Logging

Setting	Description
Log Level	Debug, Info, Warning, Error
Include Stack Traces	Capture full stack traces for errors.
Destination	Console, File, Syslog, or external logging service.

Tracing

Setting	Description
Enable Tracing	Turn on distributed tracing for execution flows.
Sampling Rate	Percentage of runs to trace (0.0 -- 1.0).

Metrics & Alerts

Define custom metrics to track (counters, histograms, gauges) and alert thresholds that trigger notifications.

Audit Trail

When enabled, all agent actions, tool invocations, and data access are recorded in the audit log.

---

Deployment Tab

Configure how and when the agent runs.

Trigger Types

Trigger	Description	Configuration
Manual	Run on demand from the UI or API.	No additional config needed.
Schedule	Run on a cron schedule.	Cron expression + timezone.
Polling	Check a condition at intervals, run when met.	Interval, initial delay, error backoff, max consecutive errors.
Event	Run when a platform event occurs.	Event type, filter conditions.
Webhook	Run when an HTTP request hits the agent's endpoint.	Webhook URL (auto-generated).

Schedule Configuration

Use standard cron expressions:

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-7, MON-SUN)
│ │ │ │ │
* * * * *

Examples:

• 0 8 * * MON -- Every Monday at 8:00 AM
• 0 */6 * * * -- Every 6 hours
• 30 9 1 * * -- First day of each month at 9:30 AM

Always specify a timezone (e.g., America/New_York) to avoid ambiguity.

Polling Configuration

Setting	Description
Interval	Time between polls (e.g., 5m, 1h).
Initial Delay	Wait time before the first poll.
Error Backoff	Multiplier applied to interval after consecutive errors.
Max Errors	Number of consecutive errors before stopping the poller.

---

Workflow Tab

The Workflow tab opens the visual workflow editor -- a drag-and-drop canvas for building execution graphs.

Canvas Basics

• Add nodes -- Drag node types from the palette or right-click the canvas.
• Connect nodes -- Click and drag from an output port to an input port.
• Configure nodes -- Click a node to open the properties panel on the right.
• Auto-layout -- Click the layout button to automatically arrange nodes in a clean hierarchy.

Node Types

Type	Icon	Description
Start	Play	Entry point, receives input parameters.
End	Stop	Terminal node, returns output.
Action	Gear	Executes a tool (query, email, LLM, etc.).
Condition	Diamond	Evaluates an expression and branches.
Loop	Refresh	Iterates over a collection or repeats until a condition.
Parallel	Fork	Splits into concurrent branches.
Transform	Shuffle	Applies data transformation.
HumanInput	Person	Pauses for user input or approval.
Wait	Clock	Pauses until a condition or timeout.
Retry	Repeat	Wraps a node with retry logic.

Variables

Nodes communicate through variables. Each node writes its output to a named variable that downstream nodes reference with ${variable_name} syntax.

Syntax	Example
${var}	${sales_data}
${var.property}	${recommendations.response}
${var[0]}	${customers[0].name}

Execution Trace Panel

When running a workflow, the Trace Panel shows:

• Real-time node execution status (pending, running, completed, failed)
• Output values for each completed node
• Token usage per LLM call
• Total execution time and resource consumption

---

Import & Export

Export

Click Export in the agent toolbar to download the complete agent specification as a JSON file. The export includes:

• All configuration tabs (identity, capabilities, behavior, safety, etc.)
• The complete workflow graph (nodes, edges, variables)
• Guard rails and policy settings

Import

Click Import (or New Agent > Import) to upload a JSON specification file. The system validates the specification and creates the agent. You can also import via the addAgent API endpoint.

---

Next Steps

• Agent Builder -- Detailed reference for agent specification fields.
• Workflow Builder -- Deep dive into workflow node types, edges, and error strategies.
• Agent Catalog -- Browse and run agents from the catalog.
• Tutorials -- Hands-on tutorials for building your first agent.