Workflow Configuration

The workflow configuration is the central JSON document that defines how your agentic workflow behaves: which language models run, what instructions agents follow, which tools they can call, and optional behaviors such as history trimming or custom UI labels for tools.

You edit this configuration when creating or updating a workflow—typically through the Chariot CLI—and Chariot stores it with the workflow record so every session for that workflow follows the same rules.

Minimal configuration

The smallest useful workflow configuration supplies a name, and an orchestrator with its own name, model_settings, and a system_prompt. Everything else is optional.

{
  "name": "Example Workflow",
  "orchestrator": {
    "name": "Example Workflow",
    "model_settings": {
      "ai_provider": "openai",
      "name": "gpt-5-mini",
      "api_key": {
        "owner_type": "project",
        "owner_id": "<your-project-id>",
        "path": "secret/Custom/<openai-api-key-secret-id>/value"
      }
    },
    "system_prompt": "You are a helpful assistant. Use tools when they improve accuracy."
  }
}

Expanded example (optional layers)

You can build on the minimal config by adding agents, models, tools, and advanced options as needed.

{
  "name": "Example Workflow",
  "orchestrator": {
    "name": "Example Workflow",
    "model_settings": {
      "ai_provider": "openai",
      "name": "gpt-5-mini",
      "api_key": {
        "owner_type": "project",
        "owner_id": "<your-project-id>",
        "path": "secret/Custom/<openai-api-key-secret-id>/value"
      }
    },
    "system_prompt": "You are a helpful assistant. Use tools when they improve accuracy.",
    "service_agents": [
      {
        "name": "Research Agent",
        "model_settings": {
          "ai_provider": "openai",
          "name": "gpt-5-nano",
          "api_key": {
            "owner_type": "project",
            "owner_id": "<your-project-id>",
            "path": "secret/Custom/<openai-api-key-secret-id>/value"
          }
        },
        "system_prompt": "Perform focused research on the topics provided to you."
      }
    ]
  },
  "message_processing": {
    "redacting": {
      "tools": ["exact_tool_name_from_config"]
    },
    "compacting": {
      "context_threshold": 0.9,
      "user_messages_to_keep": 10,
      "model_settings": {
        "ai_provider": "openai",
        "name": "gpt-5-mini",
        "api_key": {
          "owner_type": "project",
          "owner_id": "<your-project-id>",
          "path": "secret/Custom/<openai-api-key-secret-id>/value"
        }
      }
    }
  },
  "tool_display": {
    "templates": {
      "risky_action": {
        "executing": "Running risky_action…",
        "deferred": "Approve risky_action to continue"
      }
    },
    "generate_display_strings": false
  }
}

Top-level keys explained

name

The human-readable name for this workflow.

note

The workflow name must match the orchestrator.name in the configuration for it to be valid.

orchestrator

The primary agent for the workflow, including its name, model, and instructions. It optionally includes extra agents, tools, and MCP connections. See Agents, Models, and Tools.

message_processing (optional)

Trim and summarize conversation history over time to keep it from exceeding the agent's context window. See Message Processing.

tool_display (optional)

Attach human-readable strings to tool events for more user-friendly progress indicators. See Tool Display Templates.

Validation

Workflow configurations are validated automatically by Chariot. If required fields are missing or values are inconsistent, Chariot will flag them and prevent the workflow from being deployed. If this happens, simply fix the reported error and retry.

In This Section

• Agents: Orchestrator and service agents, prompts, and delegation.
• Models: model_settings and provider choice (OpenAI, Azure, Anthropic, Chariot hosted).
• Tools: MCP servers, Chariot tool packages, human approvals.
• Advanced Options: Message processing, artifacts, and tool display templates.