Skip to main content

​
Overview

Configure your agent’s API connection and business context. These files tell arksim how to connect to your agent and what context to use when simulating conversations.

​
Directory Structure

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

​
Agent Configuration

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

​
Configuration Fields

FieldTypeRequiredDescription
agent_nameStringYesUnique identifier for your agent (e.g. lowercase, no spaces)
agent_typeStringYesOne of chat_completions or a2a. See API Connection Types.
api_configObjectYesConnection details. See API Connection Types.
agent_capabilitiesList[Str]NoOptional list of tasks your agent can handle (for context/docs)

​
Writing Effective Agent Capabilities

When you use agent_capabilities, describe capabilities with 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. Be specific about what your agent can do.

​
API Connection Types

arksim supports two agent types for API connections:
Type: chat_completionsConnects to any OpenAI-compatible chat completions endpoint.

​
Required fields

  • endpoint: URL of the chat completions API
  • headers: HTTP headers (e.g. Content-Type, Authorization)
  • body: Request body; must include a messages array

​
Placeholders and variables

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

​
Example

{
  "agent_type": "chat_completions",
  "agent_name": "chat_completions_example",
  "agent_capabilities": [
    "answer feature-specific queries about products"
  ],
  "api_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 arksim user simulator."
        }
      ]
    }
  }
}

​
Example with Chat ID

{
  "agent_type": "chat_completions",
  "agent_name": "chat_completions_with_chat_id",
  "agent_capabilities": [
    "answer feature-specific queries about products"
  ],
  "api_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 with chat_id:{chat_id}"
        }
      ]
    }
  }
}
The {chat_id} placeholder is replaced with the actual chat ID during execution.

​
Environment variable support

Both chat_completions and a2a support environment variable substitution using ${ENV_VAR} in header values (and, for chat completions, in the endpoint URL where applicable). How it works:
  • At runtime, ${ENV_VAR} is replaced with the value of that environment variable
  • If the variable is not set, it is replaced with an empty string
  • You can mix static text with variables, e.g. "Bearer ${API_KEY}" → "Bearer sk-abc123..."
Security: Keep credentials in environment variables and out of committed config files.

​
Knowledge Configuration

The knowledge.json file defines business context used by arksim when building simulated user prompts (e.g. company overview).

​
Configuration fields

FieldTypeDescription
corporate_overviewStringA short description of your company/product used as context for simulation
knowledgeList[Dict]Optional. Defines knowledge sources (e.g. local data/ folder) for examples
corporate_overview is used by the simulator when generating the simulated user’s system prompt so conversations are grounded in your business context.

​
Local knowledge (optional)

You can point to a local folder of documents (e.g. for examples or future tooling): 
{
  "corporate_overview": "YourCompany Inc. is a leading provider of software solutions...",
  "knowledge": [
    {
      "source": "/path/to/agent-setup-dir/data",
      "type": "local"
    }
  ]
}
In open-source arksim, scenario building is not included. Pre-built scenarios already contain the knowledge used during simulation. The knowledge array in knowledge.json is optional and may be used by examples or custom scripts.

​
Minimal example

{
  "corporate_overview": "YourCompany Inc. is a leading provider of innovative software solutions. We help businesses automate workflows and improve customer engagement."
}

​
Data folder

The optional data folder holds knowledge documents (e.g. for your own agent or examples). You can add, remove, or update files 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 may require additional environment configuration (e.g. MISTRAL_API_KEY) depending on your setup.