Optimize Prompt

Automatically improve system prompts based on test failures

POST /v1/optimize/prompt

cURL

curl -X POST https://api.playgent.com/v1/optimize/prompt \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_abc123",
    "optimization_type": "error_driven",
    "failure_window": "7d",
    "min_failures": 5,
    "include_examples": true,
    "max_examples": 5,
    "constraints": {
      "max_prompt_length": 2000,
      "preserve_sections": ["safety_guidelines"]
    }
  }'

Response

{
  "optimization_id": "opt_vwx234",
  "status": "completed",
  "original_prompt": "You are a helpful customer support agent...",
  "optimized_prompt": "You are a customer support agent for Acme Corp. Follow these guidelines:\n\n1. Always verify order information before discussing refunds...\n\n## Examples\n<example>\nUser: I want a refund\nAssistant: I'd be happy to help with your refund...\n</example>",
  "changes_made": [
    {
      "type": "added_instruction",
      "content": "Always verify order information before discussing refunds",
      "rationale": "12 failures were due to making claims about orders without verification"
    },
    {
      "type": "added_few_shot",
      "rationale": "Added 3 examples of successful refund conversations"
    }
  ],
  "predicted_improvement": {
    "faithfulness": { "from": 0.82, "to": 0.91 },
    "relevance": { "from": 0.85, "to": 0.88 }
  },
  "validation_run_id": "run_abc789"
}

Automatically analyze test failures and optimize your agent’s system prompt. Uses intelligent failure clustering and DSPy-inspired optimization.

agent_id · string · required

Agent to optimize

optimization_type · string · required

Optimization strategy: error_driven, metric_driven, or full

failure_window · string

Time window for failure analysis (e.g., “7d”, “30d”). Used with error_driven.

min_failures · integer

Minimum failures required to trigger optimization (default: 5)

target_metrics · object

Target metrics for metric_driven optimization

Show properties

[metric_name] · object

Show properties

target · number

Target score

current · number

Current score

include_examples · boolean

Include few-shot examples from successful tests (default: true)

max_examples · integer

Maximum few-shot examples to include (default: 5)

constraints · object

Optimization constraints

Show properties

max_prompt_length · integer

Maximum prompt character length

preserve_sections · array

Sections to keep unchanged (e.g., [“safety_guidelines”])

optimization_id · string · required

Optimization identifier

status · string · required

Status: running, completed, failed

original_prompt · string · required

Original system prompt

optimized_prompt · string · required

Improved system prompt

changes_made · array · required

List of changes with rationale

Show change object

type · string

Change type

content · string

Change content

rationale · string

Why this change was made

predicted_improvement · object · required

Predicted metric improvements

validation_run_id · string · required

ID of automatic validation run

cURL

curl -X POST https://api.playgent.com/v1/optimize/prompt \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_abc123",
    "optimization_type": "error_driven",
    "failure_window": "7d",
    "min_failures": 5,
    "include_examples": true,
    "max_examples": 5,
    "constraints": {
      "max_prompt_length": 2000,
      "preserve_sections": ["safety_guidelines"]
    }
  }'

Response

{
  "optimization_id": "opt_vwx234",
  "status": "completed",
  "original_prompt": "You are a helpful customer support agent...",
  "optimized_prompt": "You are a customer support agent for Acme Corp. Follow these guidelines:\n\n1. Always verify order information before discussing refunds...\n\n## Examples\n<example>\nUser: I want a refund\nAssistant: I'd be happy to help with your refund...\n</example>",
  "changes_made": [
    {
      "type": "added_instruction",
      "content": "Always verify order information before discussing refunds",
      "rationale": "12 failures were due to making claims about orders without verification"
    },
    {
      "type": "added_few_shot",
      "rationale": "Added 3 examples of successful refund conversations"
    }
  ],
  "predicted_improvement": {
    "faithfulness": { "from": 0.82, "to": 0.91 },
    "relevance": { "from": 0.85, "to": 0.88 }
  },
  "validation_run_id": "run_abc789"
}