Working with Agents

This guide walks you through creating AI agents that can analyze data, delegate to specialists, and produce actionable outputs.

Prerequisites

VirtuousAI account with API access
At least one data connection configured
Understanding of AI Agents concepts

What You'll Build

A data analyst primary agent that:

Queries your connected data sources
Delegates complex SQL work to a SQL expert subagent
Builds flashboard dashboards from analysis results

Step 1: Create the Subagent

Start with the specialist. The SQL expert focuses on query generation and schema understanding.

curl -X POST https://vai-dev.virtuousai.com/api/v1/agents/specs \
  -H "Authorization: Bearer $VAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "---\nname: SQL Expert\nslug: sql-expert\nmode: subagent\ntools:\n  - generate_query\n  - explain_schema\n---\n\n# Goal\n\nYou are a SQL expert. Generate precise, efficient queries against connected data schemas.\n\n## Guidelines\n\n- Always use qualified table names\n- Prefer CTEs over subqueries for readability\n- Add comments explaining complex joins\n- Use QUALIFY for deduplication when needed"
  }'

---
name: SQL Expert
slug: sql-expert
mode: subagent
tools:
  - generate_query
  - explain_schema
---

# Goal

You are a SQL expert. Generate precise, efficient queries
against connected data schemas.

## Guidelines

- Always use qualified table names
- Prefer CTEs over subqueries for readability
- Add comments explaining complex joins
- Use QUALIFY for deduplication when needed

The mode: subagent setting means this agent won't appear in the user-facing agent picker. It can only be invoked by other agents via call_agent.

Step 2: Create the Primary Agent

Now create the user-facing data analyst that delegates to the SQL expert.

curl -X POST https://vai-dev.virtuousai.com/api/v1/agents/specs \
  -H "Authorization: Bearer $VAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "---\nname: Data Analyst\nslug: data-analyst\nmode: primary\ntools:\n  - generate_query\n  - explain_schema\n  - create_flashboard\n  - call_agent\nsub_agents:\n  - sql-expert\n---\n\n# Goal\n\nYou are a data analyst specializing in e-commerce metrics. Help users understand their business data through queries and visualizations.\n\n## Workflow\n\n1. Understand the user\u0027s question\n2. Explore the schema if needed\n3. For complex queries, delegate to the SQL expert\n4. Present results clearly\n5. Offer to build a flashboard for multi-metric analyses"
  }'

---
name: Data Analyst
slug: data-analyst
mode: primary
tools:
  - generate_query
  - explain_schema
  - create_flashboard
  - call_agent
sub_agents:
  - sql-expert
---

# Goal

You are a data analyst specializing in e-commerce metrics.
Help users understand their business data through queries
and visualizations.

## Workflow

1. Understand the user's question
2. Explore the schema if needed
3. For complex queries, delegate to the SQL expert
4. Present results clearly
5. Offer to build a flashboard for multi-metric analyses

Key points:

mode: primary — appears in the agent picker
call_agent in tools — enables delegation
sub_agents: [sql-expert] — explicitly allows calling the SQL expert

Step 3: Test the Agent

Select the "Data Analyst" agent in the chat picker and send a message:

"What were our top 10 products by revenue last month?"

The agent will:

Use explain_schema to discover available tables
Use generate_query (or delegate to sql-expert) to build the SQL
Execute the query and return results
Optionally offer to build a flashboard

Step 4: Review Runs

List recent runs for your agent:

curl https://vai-dev.virtuousai.com/api/v1/agents/specs/{spec_id}/runs \
  -H "Authorization: Bearer $VAI_API_KEY"

Each run includes:

Status — completed, failed, cancelled
Steps — Every tool call with parameters and results
Duration — Total execution time
Token usage — LLM tokens consumed

Check run details:

curl https://vai-dev.virtuousai.com/api/v1/agents/runs/{run_id} \
  -H "Authorization: Bearer $VAI_API_KEY"

Step 5: Crystallize (Optional)

If a run produced a valuable, repeatable workflow, crystallize it into an automation:

curl -X POST https://vai-dev.virtuousai.com/api/v1/agents/runs/{run_id}/crystallize \
  -H "Authorization: Bearer $VAI_API_KEY"

This creates a deterministic automation that replays the same tool calls without AI involvement. You can then add a schedule trigger to run it daily.

See Crystallization for details.

Managing Agent Specs

List All Agents

curl https://vai-dev.virtuousai.com/api/v1/agents/specs \
  -H "Authorization: Bearer $VAI_API_KEY"

Filter by mode:

# Only primary agents
curl "https://vai-dev.virtuousai.com/api/v1/agents/specs?mode=primary" \
  -H "Authorization: Bearer $VAI_API_KEY"

Update an Agent

curl -X PATCH https://vai-dev.virtuousai.com/api/v1/agents/specs/{spec_id} \
  -H "Authorization: Bearer $VAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "---\nname: Data Analyst\nslug: data-analyst\n..."
  }'

View Performance Stats

curl https://vai-dev.virtuousai.com/api/v1/agents/specs/{spec_id}/stats \
  -H "Authorization: Bearer $VAI_API_KEY"

Returns total runs, success rate, average duration, and crystallization count.

Delete an Agent

curl -X DELETE https://vai-dev.virtuousai.com/api/v1/agents/specs/{spec_id} \
  -H "Authorization: Bearer $VAI_API_KEY"

Composition Patterns

Common multi-agent patterns:

Pattern	Primary Agent	Subagents	Use Case
Specialist delegation	Operations Bot	SQL Expert, Schema Reader	Complex data questions requiring deep SQL knowledge
Research pipeline	Analyst	Web Researcher, Data Fetcher	Market research combining web and internal data
Report builder	Reporter	Data Analyst, Chart Builder	Automated reporting with visualizations
Customer ops	Support Bot	Order Lookup, Account Manager	Customer service with data access

Best Practices

One agent, one domain — Keep instructions focused on a single area of expertise
Start with subagents — Build specialist subagents first, then compose them
Test incrementally — Verify each agent individually before composing them
Grant minimum tools — Only give agents the tools they actually need
Write clear instructions — The markdown body is the agent's primary guidance
Monitor performance — Review stats regularly, iterate on instructions

Next Steps

Agents Primitive

Full API reference for agent specs, runs, and execution

Crystallization

Turn successful agent runs into repeatable automations

Building Flashboards

Create dashboards from agent analysis results

Working with Agents

Agents Primitive

Crystallization

Building Flashboards

On this page