kai-platform

name	kai-platform
description	How to use Kai platform tools — LOAD THIS FIRST before running any audit, optimization, or repo management operation
version	1.0.0
author	Kai Agent
metadata	{"kai":{"tags":["kai","mcp","tools","platform","setup"]}}

Using the Kai Platform

Your kai_* tools are organized into categories. You start each session with base tools only. Specialized tools (optimization, audit, etc.) must be activated before use.

Step 1: Activate the category you need

Call this tool directly — it is in your tool list right now:

kai_activate_category(category="optimization")

After this call, new tools appear in your session immediately. You will see them in your next tool call.

Available categories:

optimization  — evaluators, code optimization, optimization agents
audit         — code audits, vulnerabilities, audit tiers
repo_management — add/remove GitHub repos
integrations  — create GitHub issues, Jira tickets
budget        — check credits, billing
artifacts     — generate and view reports

You can activate multiple categories in one session. Each call is instant.

Step 2: Use the unlocked tools

After activating "optimization", these tools become available:

kai_list_code_evaluators(workspaceId, repoId)
kai_create_evaluator_from_code(workspaceId, repoId, code, name)  — write evaluator code yourself and submit directly
kai_start_code_optimization(workspaceId, repoId, config, scopes, evaluatorId)
kai_get_code_optimization_progress(optimizationId)
kai_get_optimized_programs(optimizationId)

start_code_optimization — exact argument shape

This is where wrong field names waste runs. Copy this structure.

config = {
    "llm": {
        "models": [
            {"name": "openai/gpt-4o", "weight": 1.0},
        ],
        # temperature, maxTokens, timeout etc. are all optional
    },
    "prompt": {
        "systemMessage": "You are optimizing X for Y. Preserve the public API.",
        # numTopPrograms, numDiversePrograms optional
    },
    # maxIterations, checkpointInterval, earlyStopping etc. optional
}

scopes = [
    {"path": "src/foo.py", "fromLine": 42, "toLine": 87},
]

kai_start_code_optimization(workspaceId, repoId, config, scopes, evaluatorId)

Field names that trip up models — use these, not the ones on the right:

scopes[].path       NOT filePath
scopes[].fromLine   NOT startLine
scopes[].toLine     NOT endLine
config.llm.models   (array of {name, weight}), NOT config.llm.model (string)
config.prompt.systemMessage   NOT config.prompt.goal

After activating "audit", these tools become available:

kai_start_code_audit(workspaceId, repoId, tierId)
kai_get_code_audit_details(executionId)
kai_list_audit_tiers(workspaceId)
kai_list_vulnerabilities(executionId)
kai_get_vulnerability_details(vulnerabilityId)

After activating "repo_management":

kai_add_github_repository(workspaceId, owner, repo, branch)
kai_remove_repository(workspaceId, repoId)
kai_list_github_user_repos(workspaceId)

Common mistakes

• DO NOT use execute_code to call MCP tools. They are direct tool calls.
• DO NOT schedule a cron job as a workaround. Call the tools directly.
• DO NOT assume tools are unavailable. Activate the category first.
• DO NOT call find_tools before activate_category. Just activate directly.

Example workflow: code optimization

1. kai_activate_category(category="optimization")
2. kai_list_repositories(workspaceId) to find the repo
3. kai_read_repository_files(workspaceId, repoId, paths="target.py") to read code
4. Create a lifecycle action for user approval:
   • kai_lifecycle_actions_create(workspaceId, type="evolution", title="Optimize ...", description="...", repoId=repoId)
   • Wait for user to approve via kai_lifecycle_actions_execute
5. Write evaluator Python code (evaluate(program_path) function returning dict like {"correctness": 1.0, "score": value})
6. kai_create_evaluator_from_code(workspaceId, repoId, code=evaluator_code, name="My Evaluator") → get evaluatorId
7. kai_start_code_optimization(workspaceId, repoId, config, scopes, evaluatorId) to start
8. Monitor with kai_get_code_optimization_progress(optimizationId)
9. Review with kai_get_optimized_programs(optimizationId)

Example workflow: code audit

1. kai_activate_category(category="audit")
2. kai_list_audit_tiers(workspaceId) to see available tiers
3. kai_start_code_audit(workspaceId, repoId, tierId) to start
4. kai_get_code_audit_details(executionId) to monitor progress

Handling 402 errors

If any tool returns 402 "No agent subscription", the user's workspace doesn't have an active Kai Agent subscription. Tell them to subscribe from the dashboard — don't discuss tiers, plans, or limits. Keep it short: "This workspace needs a Kai Agent subscription. Visit the dashboard to subscribe."

Never proactively mention subscription tiers, usage counters, or rate limits to the user. Don't call kai_check_agent_subscription or kai_check_agent_usage unless explicitly asked.