Skip to main content

​
Overview

Configure your agent’s API connection, business context, and knowledge base. These files tell the simulator how to connect to your agent and what to test.

​
Directory Structure

Create a configuration directory with the required JSON files: 
/path/to/input-setup-dir/
├── agent_config.json    # API and agent configuration
├── knowledge.json       # Business context and knowledge base
└── data/                # (Optional) Local knowledge files

​
Agent Configuration

The agent_config.json file configures how the framework connects to your conversational agent API.

​
Configuration Fields

FieldTypeDescription
agent_nameStringUnique identifier for your agent (lowercase, no spaces)
agent_capabilitiesList[Str]List of specific tasks your agent should handle
agent_typeEnumSee API Connection Types for supported types
agent_type_configDictSee API Connection Types for required fields

​
Writing Effective Agent Capabilities

Describe capabilities using a Verb + Object (+ Scope) structure. Each capability should state a specific, observable action. Good Examples:
  • Answer feature-specific questions about products
  • Provide pricing information and generate quotes
  • Process returns and refunds for orders
  • Schedule appointments and send confirmations
Avoid:
  • Be helpful
  • Answer questions
  • Handle customer requests
Vague descriptions don’t set clear expectations or guide implementation. Be specific about what your agent can do.

​
API Connection Types

The simulator supports three agent types for API connections:
Type: chat_completionsConnects to any OpenAI-compatible chat completions endpoint.

​
Features

  • Standard chat completions API format
  • Environment variable support for secrets
  • Optional chat ID placeholder support

​
Placeholders & Variables

  • {chat_id} - Can be included in body.messages[*].content and will be replaced at runtime
  • ${ENV_VAR} - Supported in header values for secrets

​
Basic Configuration

{
  "agent_type": "chat_completions",
  "agent_name": "chat_completions_example",
  "agent_capabilities": [
    "answer feature-specific queries about products"
  ],
  "agent_type_config": {
    "endpoint": "http://localhost:7050/chat/completions",
    "headers": {
      "Content-Type": "application/json",
      "Authorization": "Bearer ${OPENAI_API_KEY}"
    },
    "body": {
      "model": "gpt-5.1",
      "messages": [
        {
          "role": "system",
          "content": "You are being invoked by Arklex user simulator."
        }
      ]
    }
  }
}

​
Configuration with Chat ID Support

    {
      "agent_type": "chat_completions",
      "agent_name": "chat_completions_with_chat_id",
      "agent_capabilities": [
        "answer feature-specific queries about products"
      ],
      "agent_type_config": {
        "endpoint": "https://localhost:7050/chat/completions",
        "headers": {
          "Content-Type": "application/json",
          "Authorization": "Bearer ${OPENAI_API_KEY}"
        },
        "body": {
          "model": "gpt-5.1",
          "messages": [
            {
              "role": "system",
              "content": "You are being invoked with chat_id:{chat_id}"
            }
          ]
        }
      }
    }
The {chat_id} placeholder will be replaced with the actual chat ID during execution.

​
Environment Variable Support

Both chat_completions and a2a agent types support environment variable substitution using ${ENV_VAR} syntax. How it works:
  • At runtime, ${ENV_VAR} patterns are replaced with environment variable values
  • If not set, it will be replaced with an empty string
  • Mix static text with variables: "Bearer ${API_KEY}" → "Bearer sk-abc123..."
Security Best Practice: This approach keeps configuration files safe to commit while keeping credentials secure in environment variables.

​
Knowledge Configuration

The knowledge.json file defines your company overview, business type, and the knowledge your agent has access to.

​
Configuration Fields

FieldTypeDescription
corporate_overviewStringA comprehensive description of your company
business_typeEnumEither "b2b" or "b2c"
knowledgeList[Dict]Defines what information your agent has access to
user_eventsList[Str](Optional) Event descriptions that provide context for simulated conversations
user_goalsList[Str](Optional) Sample customer intents that guide the simulator in generating realistic test conversations

​
Knowledge Source Types

The simulator supports four knowledge source types:
Knowledge stored locally in the data folder.
{
	"source": "/path/to/input-setup-dir/data",
	"type": "local"
}
Knowledge crawled from web URLs.
{
	"source": "https://www.example.com",
	"type": "web"
}
Knowledge provided directly as text content.
{
	"source": "Direct text content about your company...",
	"type": "text"
}
Knowledge fetched from external APIs.
{
	"source": "https://api.example.com/v1/products",
	"type": "api",
	"request_method": "GET",
	"request_headers": {
		"Content-Type": "application/json",
        "Authorization": "Bearer ${API_KEY}"
      },
	"response_content_type": "json",
	"response_content_path": ["data", "products"],
	"response_content_extract_type": "array"
}
Environment variables (e.g., ${API_KEY}) are supported in request headers.

​
Complete Example

{
  "corporate_overview": "YourCompany Inc. is a leading provider of innovative software solutions...",
  "business_type": "b2b",
  "knowledge": [
    {
      "source": "/path/to/input-setup-dir/data",
      "type": "local"
    },
    {
      "source": "https://www.example.com",
      "type": "web"
    },
    {
      "source": "Direct text content about your company...",
      "type": "text"
    },
    {
      "source": "https://api.example.com/v1/products",
      "type": "api",
      "request_method": "GET",
      "request_headers": {
        "Content-Type": "application/json",
        "Authorization": "Bearer ${API_KEY}"
      },
      "response_content_type": "json",
      "response_content_path": ["data", "products"],
      "response_content_extract_type": "array"
    }
  ],
  "user_events": [
    "Recently involved in a minor car accident",
    "Buying a second property as an investment",
  ]
}

​
Data Folder

The data folder contains your knowledge base documents that power your agent’s responses. You can freely add, remove, or update files in this folder to match your use case.

​
Supported File Formats

CategoryFormats
Documents.md, .pdf, .doc, .docx, .txt, .html
Data Files.json, .xls, .xlsx
Presentations.ppt, .pptx
Images*.png, .jpg, .jpeg
*Image OCR requires MISTRAL_API_KEY environment variable to be set.