AI Agent Integration Guide

{
  "code": "WARMUP_TOO_SHORT",
  "path": "strategyAst.Strategy.warmupPeriod",
  "field": "strategyAst",
  "severity": "warning",
  "message": "Warmup setting is shorter than this strategy's inferred lookback.",
  "suggestion": "Set warmupPeriod to at least 200 for more consistent behavior when prehistory is limited or after gaps."
}

export TRASEQ_BASE_URL="https://your-traseq.example.com"
export TRASEQ_API_KEY="trsq_live_<keyId>_<secret>"

curl -s \
  -H "x-api-key: $TRASEQ_API_KEY" \
  "$TRASEQ_BASE_URL/public/v1/capabilities"

curl -s \
  -H "Content-Type: application/json" \
  -H "x-api-key: $TRASEQ_API_KEY" \
  -X POST "$TRASEQ_BASE_URL/public/v1/strategies/validate" \
  -d '{
    "signalGraph": {
      "protocol": "traseq.signal-graph",
      "version": 2,
      "nodes": [
        {
          "id": "ema_fast",
          "kind": "indicator",
          "indicator": "ema",
          "args": { "length": 20 }
        },
        {
          "id": "close_price",
          "kind": "market",
          "field": "close"
        },
        {
          "id": "cross_up_fast",
          "kind": "cross",
          "op": "cross_up",
          "left": { "ref": "close_price" },
          "right": { "ref": "ema_fast" }
        }
      ],
      "strategy": {
        "kind": "strategy",
        "entry": {
          "kind": "entry",
          "trigger": { "ref": "cross_up_fast" },
          "action": {
            "side": "long",
            "sizing": { "mode": "fixed", "value": 1 }
          }
        }
      }
    },
    "settings": {
      "maxConcurrentPositions": 1,
      "warmupPeriod": 200
    }
  }'

const client = new TraseqPublicAgentClient(
  process.env.TRASEQ_BASE_URL!,
  process.env.TRASEQ_API_KEY!,
);

const capabilities = await client.getCapabilities();

const authoringPayload = await validateWithRepairLoop(
  client,
  {
    signalGraph,
    settings: {
      maxConcurrentPositions: 1,
      warmupPeriod: 200,
    },
  },
  async (currentPayload, context) => {
    return repairPayloadWithYourModel({
      capabilities,
      currentPayload,
      issues: context.issues,
    });
  },
);

const draft = await client.createStrategy({
  name: 'Agent-authored EMA breakout',
  description: 'Generated by an external AI agent',
  ...authoringPayload,
});

const ready = await client.finalizeStrategyVersion(draft.id, {
  version: draft.versions[0].version,
  ...authoringPayload,
});

const backtest = await client.runBacktest({
  strategyVersionId: ready.id,
  config: {
    timeframe: '1h',
    signalInstrument: { symbol: 'BTCUSDT' },
    initialBalance: 10000,
    execution: {
      feeModel: {
        kind: 'tiered_maker_taker',
        tiers: [
          {
            minCumulativeNotional: 0,
            makerRate: 0.001,
            takerRate: 0.001,
          },
        ],
      },
      slippage: {
        kind: 'fixed',
        unit: 'bps',
        value: 5,
      },
    },
  },
});

{
  "type": "object",
  "additionalProperties": false,
  "required": ["settings"],
  "properties": {
    "signalGraph": {
      "type": "object",
      "description": "Preferred AI authoring payload."
    },
    "strategyAst": {
      "type": "object",
      "description": "Canonical fallback payload."
    },
    "settings": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "maxConcurrentPositions": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100
        },
        "warmupPeriod": {
          "type": "integer",
          "minimum": 0
        }
      }
    }
  },
  "anyOf": [
    { "required": ["signalGraph"] },
    { "required": ["strategyAst"] }
  ]
}

You are an external AI strategy-authoring agent for Traseq.

Before composing any strategy:
1. Call get_workspace_context.
2. Call get_capabilities.
3. Use capabilities as the only source of truth for supported node kinds, bindings, indicators, operators, enums, and limits.

Authoring rules:
- Prefer signalGraph over strategyAst unless the user explicitly asks for canonical AST.
- Keep the first payload minimal and valid.
- Reuse simple, stable node ids such as close_price, ema_fast, entry_trigger.
- Do not invent unsupported fields, params, or operators.
- Do not use tokens as the primary write format.

Validation rules:
- Always call validate_strategy before create_strategy or finalize_strategy_version.
- Treat issue code, path, message, and suggestion as the repair source of truth.
- Modify the minimum subtree needed to resolve each blocking issue.
- Revalidate after every repair pass.

Execution rules:
- Create drafts before finalizing.
- Run backtests only after a ready version exists.
- Summarize backtest outcomes from summaryJson before inspecting large artifacts.

Inputs:
- user_intent
- current_payload
- capabilities
- blocking_issues[]

Task:
- Return a revised payload only.
- Preserve unchanged fields.
- Modify the minimum subtree needed to resolve the listed blocking issues.

Repair policy:
1. Read each issue.code and issue.path.
2. If suggestion is present, prefer it over freeform reinterpretation.
3. Do not rename unrelated node ids.
4. Do not introduce new node kinds unless capabilities allow them.
5. Keep strategy settings unless an issue directly points to settings.