Agent Configuration

Agent configuration controls everything about how an agent behaves — the model it uses, how it searches memory, what tools it can invoke, and how it handles cost limits.

Configuration is set when you create an agent and can be updated at any time from the agent’s Settings tab.

Configuration structure

A complete agent configuration has these top-level sections:

{
  "agent": { ... },        // Identity and display settings
  "model": { ... },        // LLM selection and fallback chain
  "memory": { ... },       // Memory search and storage behavior
  "tools": { ... },        // Tool access control
  "session": { ... },      // Session and context window settings
  "limits": { ... }        // Cost and rate limits
}

`agent`

Basic identity and display settings.

"agent": {
  "name": "Aria",
  "role": "Client Concierge",
  "description": "First point of contact for client inquiries"
}

Field	Type	Description
`name`	string	Display name shown in the dashboard and chat UI
`role`	string	Short role label (e.g., “Research Analyst”, “Ops Monitor”)
`description`	string	One-sentence description of what this agent does

`model`

Controls which LLM the agent uses and what happens if it’s unavailable.

"model": {
  "default": "claude-haiku-3.5",
  "fallbacks": [
    "claude-sonnet-4-20250514"
  ]
}

Field	Type	Description
`default`	string	Primary model ID to use for all requests
`fallbacks`	string[]	Ordered list of fallback models if the primary is unavailable

Available models (subset — see Models & Fallbacks for full list):

Model ID	Provider	Cost tier	Best for
`claude-haiku-3.5`	anthropic	Economy	Routine tasks, high-volume cron jobs
`claude-sonnet-4-20250514`	anthropic	Flagship	Most tasks — good balance of quality and cost
`claude-opus-4-20250514`	anthropic	Flagship	Complex reasoning, high-stakes output
`gpt-4o`	openai	Flagship	Broad capability, strong reasoning
`gpt-4o-mini`	openai	Economy	Lowest-cost option for simple tasks
`gemini-2.0-flash`	google	Economy	Ultra-low cost classification and routing
`mistral-large-latest`	mistral	Flagship	EU data residency, strong instruction following

See Models & Fallbacks for a full guide on model routing strategies.

`memory`

Controls how the agent searches and uses its long-term memory store.

"memory": {
  "search": {
    "enabled": true,
    "query": {
      "hybrid": {
        "vectorWeight": 0.7,
        "bm25Weight": 0.3,
        "mmr": true,
        "temporalDecay": true
      }
    },
    "topK": 5
  }
}

Field	Type	Default	Description
`search.enabled`	boolean	`true`	Whether the agent queries memory at the start of each turn
`search.query.hybrid.vectorWeight`	number	`0.7`	Weight given to semantic (vector) similarity
`search.query.hybrid.bm25Weight`	number	`0.3`	Weight given to keyword (BM25) matching
`search.query.hybrid.mmr`	boolean	`true`	Enables Maximal Marginal Relevance — reduces redundant results
`search.query.hybrid.temporalDecay`	boolean	`true`	Weights recent memories higher than old ones
`search.topK`	number	`5`	Number of memory results injected into context per turn

`tools`

Controls which tools the agent is allowed to invoke. Only list tools you want enabled — unlisted tools are unavailable by default.

"tools": {
  "allowed": [
    "web_search",
    "memory_search",
    "memory_store",
    "send_message"
  ]
}

Available tools:

Tool	Description
`web_search`	Search the web for current information
`memory_search`	Query the agent’s long-term memory
`memory_store`	Save information to long-term memory
`send_message`	Send a message via Telegram or Slack
`read_file`	Read files from the agent’s workspace
`write_file`	Write or update files in the agent’s workspace
`run_script`	Execute scripts in the agent’s container
`http_request`	Make HTTP requests to external APIs

See Tools & Integrations for tool-specific configuration options.

`session`

Controls context window behavior and session management.

"session": {
  "maxContextTokens": 50000,
  "systemPromptPath": "SOUL.md"
}

Field	Type	Default	Description
`maxContextTokens`	number	`50000`	Maximum tokens to include from session history per turn
`systemPromptPath`	string	`"SOUL.md"`	Path to the SOUL file, relative to the agent’s workspace

`limits`

Cost and rate guardrails.

"limits": {
  "dailyTokenBudget": 500000,
  "monthlyTokenBudget": 10000000,
  "alertThreshold": 0.8
}

Field	Type	Description
`dailyTokenBudget`	number	Maximum tokens per day. Agent pauses if exceeded.
`monthlyTokenBudget`	number	Maximum tokens per calendar month
`alertThreshold`	number	Fraction of budget (0–1) that triggers a cost alert notification

Example: full configuration

{
  "agent": {
    "name": "Pulse",
    "role": "Analytics Analyst",
    "description": "Monitors business metrics and surfaces weekly trends"
  },
  "model": {
    "default": "claude-haiku-3.5",
    "fallbacks": ["claude-sonnet-4-20250514"]
  },
  "memory": {
    "search": {
      "enabled": true,
      "query": {
        "hybrid": {
          "vectorWeight": 0.7,
          "bm25Weight": 0.3,
          "mmr": true,
          "temporalDecay": true
        }
      },
      "topK": 5
    }
  },
  "tools": {
    "allowed": [
      "memory_search",
      "memory_store",
      "http_request",
      "send_message"
    ]
  },
  "session": {
    "maxContextTokens": 40000,
    "systemPromptPath": "SOUL.md"
  },
  "limits": {
    "dailyTokenBudget": 200000,
    "monthlyTokenBudget": 4000000,
    "alertThreshold": 0.8
  }
}