AI Agent

The AI Agent is one of the primary ways you will interact with System Initiative. It allows you to express your intent in natural language and let the AI Agent take care of the implementation details.

Architecture

System Initiative ships a preconfigured version of Claude Code. It integrates with our MCP Server and it also contains a small amount of context to help the agent perform well.

No AI Agent is deterministic - ask it to perform the same task twice, and it is likely to perform it slightly differently each time. That's okay! System Initiative provides the deterministic layer to manage your infrastructure, and many tools to ensure you get precisely what you want out of the system.

Cost Model

System Initiative does not sit between you and the underlying model/agent provider. We do not mark up your token usage. It is up to you how you pay for the underlying model.

Installing the Agent

For detailed instructions, follow the instructions for installing our CLI.

Authentication to System Initiative

To authenticate to your System Initiative workspace, run:

bash

si login

This will open our login page and authenticate your CLI. It will then prompt you to choose a workspace:

bash

si login
✨ info    si              Starting local oauth callback webserver...

Listening on http://[::1]:9003/
Opening login page. If a browser does not open, open https://auth-api.systeminit.com/auth/login?cli_redir=9003 in a browser running on this machine

✨ info    si              Logged in as adam@systeminit.com. Setting as default user.
? Set current workspace 🔎
  GitHub Action CI Workspace - 01JJFCM02Y2Y0FDFH4Y3BTX6SQ - (https://api.systeminit.com)
  Technical Operations - 01J7PP420PHW97TJJB5BA0SQ9A - (https://api.systeminit.com)
  MissionControl Workspace - 01K4TW5QBT0KSAZ2T41YYD5W8M - (https://api.systeminit.com)

Select a workspace from the list:

? Set current workspace › MissionControl Workspace - 01K4TW5QBT0KSAZ2T41YYD5W8M - (https://api.systeminit.com)
✨ info    si              Workspace token expires at: Fri Jan 09 2026 23:24:33 GMT+0000 (Greenwich Mean Time)
✨ info    si              Set default workspace to: MissionControl Workspace

You are now authenticated against this workspace, and a workspace token has been generated.

Starting the Agent

To start the agent, firstly, run:

bash

si ai-agent init

This will use the previous workspace token and generate the correct CLAUDE.md, .mcp.json and .claude/settings.local.json files that are necessary for running the agent. The command will also tell you how to install Claude Code.

When the agent is configured, run:

bash

si ai-agent start

This will start Claude Code and connect it to the locally running MCP server.

TIP

After you switch workspaces e.g., si workspace switch, you will want to re-run the AI agent initialization command to populate the agent with the new workspace API token.

bash

si ai-agent init

Prompting the AI Agent

To prompt the AI Agent, you will write your request in plain language. The agent will then map your request to a series of commands to System Initiative. When you want a specific outcome, be as specific as possible.

Validating the Agent is Connected to System Initiative

Validate your credentials to ensure your AI Agent is connected to System Initiative.

prompt

> Validate my connection to System Initiative
● ✅ Connection validated successfully!

  - User: adam@systeminit.com
  - Workspace ID: 01K6GMC6X7WF066E45FYM7YY8G
  - Role: automation
  - Token expires: October 1, 2026

  Your credentials are working correctly and you have access
  to your System Initiative workspace.

Effective Agent Use

Be specific when it matters

If you want to be sure something happens, be specific. For example, if you ask the AI Agent to build a 'server in AWS' for you, it will make its best guess as to fields like InstanceType or ImageId. These will almost certainly not be the values you want.

Bad Prompt

prompt

> Make a server in aws

Good Prompt

prompt

> Make a server in AWS in us-east-1, with 1gb of memory, using ami-12345

When you want a specific outcome, be specific in your prompt.

TIP

The agent itself is quite effective at improving your prompt. Try asking it to improve your prompt before you run it!

Embrace Iteration

System Initiative makes it easy to iterate on your infrastructure. Change Sets ensure that nothing will change without your approval. Rather than trying to get everything done in one shot, work in iterations. For example, it's better to:

Ask the agent to create a best practices network layer
Configure a cluster
Deploy an application to the cluster

Than to try and have a single prompt that does all 3. It's easier to review the work of the agent, and it is more likely to generate a good outcome.

Clear your Context

The AI Agent has a context window that is quite large, and we try to provide tools that allow the agent to explore the data it needs from your infrastructure in a token-friendly way. That said, the longer the conversation chain in the agent, the more likely it is to start making mistakes.

When you finish a task, we recommend clearing your context and starting fresh on the next task. Let the LLM explore the information it needs, rather than relying on having it pick it out of a very long context window.

Repeatability and Policy

Do not come from the AI Agent. For example, if you want to lay down the exact same architecture every time (with small variations), you should be using a template and allowing the Agent to drive it. The same is true with policy - write qualifications and validations to ensure that components are correct, rather than relying on careful prompting or context to get it right.

Review the Agents' Work

When working with the AI Agent, review its work. Use the 'R' hot-key to bring up a review screen whilst on the web app, and ensure that all the correct attributes and actions are enqueued. While the Agent frequently gets everything right, it won't always - and that can matter when working with infrastructure.

TIP

This is why our pre-configured AI Agent does not allow the agent to apply or force-apply a change set without your permission. We recommend you keep this setting!

More Tips

For more tips on working with the AI Agent:

Using other Agents and Models

You can use the System Initiative MCP Server with your own agents and underlying models. We currently support OpenAI Codex, OpenCode.ai and Cursor. To use either of these tools, you can pass a --tool command when configuring and starting the agent:

bash

si ai-agent init --tool codex
si ai-agent start --tool codex

The configuration command will ensure that our AI Agnet is setup appropriately for the tool.

WARNING

Using other Agents or Models may result in unexpected behavior due to differences in how they support different features of the MCP Protocol and how effectively they utilize tools.

We are happy to work with you to make our MCP Server work well with your agent and model of choice, but only officially support our AI Agent and the tools it ships with.

Running the MCP Server Manually

To run the MCP server directly:

bash

export SI_API_TOKEN=DEADB33F
si ai-agent stdio

First, you need to set the SI_API_TOKEN environment variable, which is a valid workspace API token. Then you can run the MCP server directly.

Cursor

Cursor uses mcp.json to configure external MCP Servers. Here is a sample configuration:

json

{
  "mcpServers": {
    "system-initiative": {
      "type": "stdio",
      "command": "si",
      "args": ["ai-agent", "stdio"],
      "env": {
        "SI_API_TOKEN": "${env:SI_API_TOKEN}"
      }
    }
  }
}

TIP

Make sure your SI_API_TOKEN is set before you launch cursor, so that the MCP server can authenticate with System Initiative.

VS Code

Add a .vscode/mcp.json file to your workspace, following these instructions.

json

{
  "servers": {
    "systemInitiative": {
      "type": "stdio",
      "command": "si",
      "args": ["ai-agent", "stdio"],
      "env": {
        "SI_API_TOKEN": "${input:SI_API_TOKEN}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "SI_API_TOKEN",
      "description": "Your Workspace API Token",
      "password": true
    }
  ]
}

VS Code will prompt you to paste your API Token in, which it will store in its own 'secure secret storage'.

WARNING

This is a good example of an environment that may not work well with our MCP server. If you experience issues, let us know.

Functions

Architecture

Cloud Providers

AI Agent

Architecture

Cost Model

Installing the Agent

Authentication to System Initiative

Starting the Agent

Prompting the AI Agent

Validating the Agent is Connected to System Initiative

Effective Agent Use

Be specific when it matters

Bad Prompt

Good Prompt

Embrace Iteration

Clear your Context

Repeatability and Policy

Review the Agents' Work

More Tips

Using other Agents and Models

Running the MCP Server Manually

Cursor

VS Code

AI Agent ​

Architecture ​

Cost Model ​

Installing the Agent ​

Authentication to System Initiative ​

Starting the Agent ​

Prompting the AI Agent ​

Validating the Agent is Connected to System Initiative ​

Effective Agent Use ​

Be specific when it matters ​

Bad Prompt ​

Good Prompt ​

Embrace Iteration ​

Clear your Context ​

Repeatability and Policy ​

Review the Agents' Work ​

More Tips ​

Using other Agents and Models ​

Running the MCP Server Manually ​

Cursor ​

VS Code ​

AI Agent

Architecture

Cost Model

Installing the Agent

Authentication to System Initiative

Starting the Agent

Prompting the AI Agent

Validating the Agent is Connected to System Initiative

Effective Agent Use

Be specific when it matters

Bad Prompt

Good Prompt

Embrace Iteration

Clear your Context

Repeatability and Policy

Review the Agents' Work

More Tips

Using other Agents and Models

Running the MCP Server Manually

Cursor

VS Code