AI Agent Configuration

Configure AI agents to assist with API mocking workflows. Agents can create routes, generate test data, suggest mock responses, and automate repetitive tasks based on your API patterns.

What Are AI Agents?

AI agents in SureStage are LLM-powered assistants that understand your API structure and help you build mocks faster. They integrate with the MCP Server to perform actions like:

• Generating mock responses from schemas
• Suggesting realistic test data
• Creating route variations for edge cases
• Automating repetitive mock creation

Per-Instance Agent Configuration

Each Sandbox has its own agent configuration, letting you customize behavior per environment.

Get Configuration

curl https://api.surestage.com/v1/simulations/sandbox_abc123/agent-config \
  -H "Authorization: Bearer $TOKEN"

Response 200 OK

{
  "sandboxId": "sandbox_abc123",
  "enabled": true,
  "model": "claude-3-5-sonnet",
  "temperature": 0.3,
  "maxTokens": 4096,
  "systemPrompt": "You are an API mocking assistant. Generate realistic, consistent mock data.",
  "capabilities": {
    "routeGeneration": true,
    "dataGeneration": true,
    "schemaInference": true,
    "edgeCaseDetection": false
  },
  "preferences": {
    "generateIds": "uuid",
    "timestampFormat": "iso8601",
    "emailDomain": "example.com"
  }
}

Update Configuration

curl -X PATCH https://api.surestage.com/v1/simulations/sandbox_abc123/agent-config \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-opus",
    "temperature": 0.5,
    "capabilities": {
      "edgeCaseDetection": true
    }
  }'

Configuration Options

Model Selection

Model	Use Case	Speed	Quality
claude-3-5-sonnet	Balanced performance	Fast	High
claude-3-opus	Complex scenarios	Slower	Highest
gpt-4-turbo	General purpose	Fast	High

Temperature

Controls response randomness:

• 0.0-0.3 - Deterministic, consistent output (recommended for mock generation)
• 0.4-0.7 - Balanced creativity and consistency
• 0.8-1.0 - Highly varied, creative output

Capabilities

Capability	Description
routeGeneration	Agent can create new routes
dataGeneration	Agent can generate test data
schemaInference	Agent can infer schemas from examples
edgeCaseDetection	Agent suggests edge case routes

Preferences

Customize data generation:

Preference	Options	Description
generateIds	uuid, sequential, short	ID format for generated data
timestampFormat	iso8601, unix, rfc3339	Timestamp format
emailDomain	string	Domain for generated email addresses

Agent Tool Backends

Agents can integrate with external tools and APIs. Configure tool backends per Sandbox.

List Tool Backends

curl https://api.surestage.com/v1/simulations/sandbox_abc123/agent-tool-backends \
  -H "Authorization: Bearer $TOKEN"

Response 200 OK

{
  "backends": [
    {
      "id": "backend_123",
      "name": "Schema Registry",
      "type": "http",
      "config": {
        "url": "https://schema-registry.example.com",
        "authHeader": "X-API-Key"
      },
      "enabled": true
    }
  ]
}

Add Tool Backend

curl -X POST https://api.surestage.com/v1/simulations/sandbox_abc123/agent-tool-backends \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Schema Registry",
    "type": "http",
    "config": {
      "url": "https://schema-registry.example.com",
      "authHeader": "X-API-Key"
    }
  }'

Response 201 Created

{
  "id": "backend_123",
  "name": "Schema Registry",
  "type": "http",
  "config": {
    "url": "https://schema-registry.example.com",
    "authHeader": "X-API-Key"
  },
  "enabled": true,
  "createdAt": "2026-03-21T11:00:00Z"
}

Backend Types

Type	Description	Use Case
http	REST API integration	Fetch schemas, external data
database	Direct DB query	Read production data samples
function	Custom code execution	Complex transformations

Agent Traces

Inspect agent activity with execution traces. Traces show what the agent did, why, and the results.

List Traces

curl https://api.surestage.com/v1/simulations/sandbox_abc123/agent-traces?limit=10 \
  -H "Authorization: Bearer $TOKEN"

Response 200 OK

{
  "traces": [
    {
      "id": "trace_abc123",
      "timestamp": "2026-03-21T12:00:00Z",
      "action": "route-generation",
      "input": {
        "userPrompt": "Create a route for fetching user profile"
      },
      "output": {
        "routeId": "route_789",
        "method": "GET",
        "path": "/profile/:userId"
      },
      "duration": 1234,
      "tokensUsed": 856,
      "model": "claude-3-5-sonnet"
    }
  ]
}

Get Trace Details

curl https://api.surestage.com/v1/simulations/sandbox_abc123/agent-traces/trace_abc123 \
  -H "Authorization: Bearer $TOKEN"

Response 200 OK

{
  "id": "trace_abc123",
  "timestamp": "2026-03-21T12:00:00Z",
  "action": "route-generation",
  "input": {
    "userPrompt": "Create a route for fetching user profile"
  },
  "output": {
    "routeId": "route_789",
    "method": "GET",
    "path": "/profile/:userId",
    "response": {
      "status": 200,
      "body": {
        "userId": "{{params.userId}}",
        "name": "John Doe",
        "email": "john@example.com"
      }
    }
  },
  "reasoning": [
    "Inferred REST pattern from user prompt",
    "Used path parameter for user ID",
    "Generated sample user data with realistic values"
  ],
  "duration": 1234,
  "tokensUsed": 856,
  "model": "claude-3-5-sonnet"
}

Traces include:

• Input: What the agent was asked to do
• Output: What the agent produced
• Reasoning: Step-by-step explanation of decisions
• Performance: Duration and token usage

Using Agents via MCP

Connect AI agents to SureStage via the MCP Server:

surestage mcp start \
  --sandbox-id sandbox_abc123 \
  --agent-mode interactive

The agent can now invoke tools like:

Generate Route from Schema

{
  "tool": "route-builder.create-from-schema",
  "schema": {
    "type": "object",
    "properties": {
      "orderId": { "type": "string" },
      "total": { "type": "number" }
    }
  }
}

The agent generates a route with realistic sample data automatically.

Security

• Agent configurations are scoped to Sandboxes — agents cannot access other Tenants' data
• All agent operations are authenticated and logged
• Tool backends require explicit enablement and credential configuration
• Traces include all agent actions for audit purposes

Common Issues

Problem: Agent generates unrealistic data

Solution: Lower the temperature setting (0.1-0.3) for more consistent output. Customize preferences to match your domain.

Problem: Agent cannot access tool backend

Solution: Verify the backend URL is reachable and credentials are correct. Check the backend is enabled in the configuration.

Problem: No traces appearing

Solution: Ensure agent operations are happening through the MCP Server with agent mode enabled.

Related

• MCP Server Integration - Connect AI agents to SureStage
• Routes & Responses - Manual route creation
• Environment Variables - Use variables in agent-generated routes