Skip to Content
Nextra 4.0 is released 🎉
User GuideSamplesWalkthrough

Research-Analysis-Creation Tutorial

Learn how to build a complete research workflow using ARK’s multi-agent capabilities through a hands-on, step-by-step tutorial. This tutorial follows an evaluation-driven methodology where each component is tested individually before progressing to the next step.

What You’ll Build

A sequential team of three specialized agents that work together to:

  • Researcher Agent: Searches the web for information using DuckDuckGo
  • Analyst Agent: Processes research data and generates insights
  • Creator Agent: Consolidates findings into professional documents

ARK Project Structure Best Practice

This tutorial follows ARK’s recommended project structure:

samples/walkthrough/
├── README.md (this tutorial)
├── agents/
│   ├── tests/
│   │   ├── queries/                          # Individual agent test queries
│   │   │   ├── analyst-query.yaml           # Query for analyst agent testing
│   │   │   ├── creator-query.yaml           # Query for creator agent testing
│   │   │   └── researcher-query.yaml        # Query for researcher agent testing
│   │   ├── chainsaw-analyst-test.yaml       # Individual analyst agent test
│   │   ├── chainsaw-creator-test.yaml       # Individual creator agent test
│   │   └── chainsaw-researcher-test.yaml    # Individual researcher agent test  
│   ├── README.md                            # Agent component guide
│   ├── analyst-agent.yaml
│   ├── creator-agent.yaml
│   └── researcher-agent.yaml
├── teams/
│   ├── tests/
│   │   └── chainsaw-test.yaml               # Test team creation
│   ├── README.md                            # Team component guide
│   └── research-team.yaml
├── tools/
│   ├── tests/
│   │   ├── queries/
│   │   │   └── web-search-query.yaml        # Query for tool testing
│   │   └── chainsaw-test.yaml               # Test tool functionality with query execution
│   ├── README.md                            # Tool component guide
│   └── web-search-tool.yaml
├── tests/                                   # End-to-end integration test
│   ├── chainsaw-test.yaml
│   └── manifests/...
├── kustomization.yaml                       # Declarative deployment
└── research-query.yaml                      # Sample query

Key Benefits:

  • Component isolation: Test each piece individually
  • Progressive complexity: Build from simple to complex
  • Evaluation-driven: Validate before proceeding
  • Maintainable: Clear organization and documentation

Prerequisites

Install ARK by following the quickstart guide:

# Quick installation (installs tools, sets up cluster, chainsaw, deploys controller)
make quickstart

Verify installation:

# Check ARK controller is running
kubectl get pods -n ark-system

Step 1: Create and Test Web Search Tool

What You’ll Learn

  • How to define ARK tools for external APIs
  • Tool schema definition and parameter configuration
  • Testing individual tools with chainsaw

Create the Tool

The web search tool uses DuckDuckGo’s API to search the web and return structured results.

# View the tool definition
cat samples/walkthrough/tools/web-search-tool.yaml

Key features:

  • DuckDuckGo API integration for web searches
  • Configurable number of results (default: 5)
  • Returns titles, snippets, and URLs in structured format

Test the Tool

# Run tool-specific tests with query execution
chainsaw test samples/walkthrough/tools/tests/
 
# Expected: Tool created and functionality validated through query execution

The tool test includes:

  • Tool resource creation and schema validation
  • Query execution from queries/web-search-query.yaml
  • Direct tool targeting to verify DuckDuckGo API integration
  • Response content validation for search results
  • Tool readiness verification for agent integration

Expected Results

  • Tool resource exists in cluster with correct schema
  • Tool successfully executes web searches via DuckDuckGo API
  • Query responses contain structured search results with titles, snippets, and URLs
  • Tool is validated and ready for agent use

Step 2: Create and Test Agents

What You’ll Learn

  • How to create specialized agents with different capabilities
  • Agent prompt engineering and structured output
  • Model references and tool integration

Create the Agents

Researcher Agent

Searches the web for information and structures findings:

# View the researcher agent
cat samples/walkthrough/agents/researcher-agent.yaml

Features:

  • Web search tool integration
  • Structured JSON output format
  • Research methodology in prompt

Analyst Agent

Processes research data and generates insights:

# View the analyst agent  
cat samples/walkthrough/agents/analyst-agent.yaml

Features:

  • Data validation and consistency checking
  • Insight generation and trend analysis
  • Recommendation synthesis

Creator Agent

Consolidates findings into professional documents:

# View the creator agent
cat samples/walkthrough/agents/creator-agent.yaml

Features:

  • Document generation capabilities
  • File system integration
  • Professional formatting

Test the Agents

Option 1: Test all agents together

# Run all agent tests together
chainsaw test samples/walkthrough/agents/tests/

Option 2: Test each agent individually with dedicated queries

# Test researcher agent with web search functionality
chainsaw test --test-file chainsaw-researcher-test.yaml samples/walkthrough/agents/tests/
 
# Test analyst agent with data analysis capabilities  
chainsaw test --test-file chainsaw-analyst-test.yaml samples/walkthrough/agents/tests/
 
# Test creator agent with document generation (requires MCP filesystem server)
chainsaw test --test-file chainsaw-creator-test.yaml samples/walkthrough/agents/tests/

Each individual test includes:

  • Complete environment setup (Azure model, RBAC permissions)
  • Agent creation and validation
  • Dedicated query file from queries/ folder for realistic testing
  • Query execution with agent-specific scenarios
  • Response content validation and functional capability verification
  • Proper cleanup after test completion

Query Files Structure:

  • queries/researcher-query.yaml: Kubernetes research scenario
  • queries/analyst-query.yaml: Data analysis with sample metrics
  • queries/creator-query.yaml: Document creation with analysis data

Expected Results

  • All agent resources exist in cluster
  • Agents reference the default model correctly
  • Agents are ready for team integration

Step 3: Create and Test Sequential Team

What You’ll Learn

  • How to create teams with sequential strategy
  • Team member configuration and execution flow
  • Team testing and validation

Create the Team

The sequential team orchestrates the three agents in order:

# View the team definition
cat samples/walkthrough/teams/research-team.yaml

Features:

  • Sequential execution: Researcher → Analyst → Creator
  • Automatic data passing between agents
  • Maximum 3 turns for completion

Test the Team

# Run team-specific tests
chainsaw test samples/walkthrough/teams/tests/
 
# Expected: Team created with correct members

Expected Results

  • Team resource exists in cluster
  • Team references all three agents correctly
  • Team strategy is configured as sequential

Step 4: Execute Complete Research Workflow

What You’ll Learn

  • How to deploy complete ARK applications
  • End-to-end workflow execution
  • Result monitoring and validation

Deploy the Complete Workflow

First, set up the MCP filesystem server for document storage:

# Deploy filesystem MCP server
helm install mcp-filesys mcp/filesys/chart/

Deploy all components together using Kustomize:

# Deploy the complete research workflow using kustomization.yaml
kubectl apply -k samples/walkthrough/
 
# This applies all resources defined in kustomization.yaml:
# - Web search tool
# - All three agents (researcher, analyst, creator)
# - Research team with sequential strategy
# - Sample research query

Execute a Research Query

# Run a research query on Kubernetes adoption
kubectl apply -f samples/walkthrough/research-query.yaml
 
# Monitor progress - from running to done
kubectl get queries research-query -w

Test the Complete Workflow

# Run end-to-end integration tests
chainsaw test samples/walkthrough/tests/
 
# Expected: Complete workflow executes successfully

Expected Results

  1. Research Phase: Web search results with sources and structured findings
  2. Analysis Phase: Validated insights, trends, and recommendations
  3. Creation Phase: Professional document saved to file system

The complete workflow typically takes 2-3 minutes depending on research complexity.

Step 5: Validate and Explore Results

View Query Results

# Get detailed query results
kubectl get queries research-query -o yaml
 
# Check response content
kubectl get queries research-query -o jsonpath='{.status.responses[0].content}' | jq '.'

Access Generated Documents

# Port forward to file browser
kubectl port-forward svc/mcp-filesys-filebrowser 8080:8080
 
# Open in browser (admin/admin)
open http://localhost:8080

Quick Start (Skip Tutorial)

If you want to deploy everything at once without the step-by-step tutorial:

# 1. Deploy MCP filesystem server
helm install mcp-filesys mcp/filesys/chart/
 
# 2. Deploy complete workflow using kustomization.yaml
kubectl apply -k samples/walkthrough/
 
# 3. Execute research query
kubectl apply -f samples/walkthrough/research-query.yaml

Customization

Modify Research Topic

Edit the query to research different topics:

# research-query.yaml
spec:
  input: "Artificial Intelligence trends in healthcare 2024"

Use Custom Models

Reference specific models for different agents:

# In agent YAML files
spec:
  modelRef:
    name: your-custom-model

Cleanup

# Remove the research workflow using kustomization.yaml
kubectl delete -k samples/walkthrough/
 
# Remove the MCP filesystem server  
helm uninstall mcp-filesys
 
# Remove any test resources
kubectl delete queries --all

Next Steps

  • Explore other ARK samples in the samples/ directory
  • Learn about different team strategies (round-robin, graph-based)
  • Integrate custom MCP servers for specialized tools
  • Build more complex multi-agent workflows

Troubleshooting

Common Issues

Agents not responding:

# Check agent status
kubectl get agents
kubectl describe agent researcher
 
# Verify model is ready
kubectl get models

If queries don’t complete:

# Check query status
kubectl describe query research-query
 
# Check agent and team status
kubectl get agents,teams
 
# View controller logs
kubectl logs -n ark-system deployment/ark-controller-manager

Team execution fails:

# Check team configuration
kubectl describe team research-analysis-team
 
# View query events
kubectl get events --field-selector involvedObject.name=research-query

MCP tools not working:

# Check tool status
kubectl get tools
kubectl describe tool web-search
 
# Verify MCP server connectivity
kubectl get pods | grep mcp
Last updated on
Tips on Building Agentic Use CasesTeam Strategies