Skip to main content

Update Agent Profile

Overview​

The admin-update-agent-profile tool allows you to upsert new prompt and configuration versions for agents. It hashes the payload, expires the previous current row, increments the version, and returns the new record.

Tool ID: admin-update-agent-profile

The examples use the direct runtime/operator route. Replit/Admin UI browser code should call the Admin UI BFF instead: local /admin-api/*, testing /dashboard/admin-api/*.

Input Schema​

{
  agentId: string;           // Agent identifier (e.g., "k12-safety-agent")
  systemPrompt: string;      // New system prompt text
  llmOverrides?: {           // Optional LLM parameter overrides
    temperature?: number;
    topP?: number;
    frequencyPenalty?: number;
    presencePenalty?: number;
    maxOutputTokens?: number;
  };
  createdBy: string;         // User/system that created this version
}

Example Usage​

curl -s -X POST "${MASTRA_BASE_URL}/admin/tools/update-agent-profile" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -d '{
    "data": {
      "agentId": "k12-safety-agent",
      "systemPrompt": "You are a K12 safety analysis agent. Analyze student check-ins for safety concerns...",
      "llmOverrides": {
        "temperature": 0.3,
        "maxOutputTokens": 1000
      },
      "createdBy": "ops@example.com"
    }
  }'
const response = await fetch(`${MASTRA_BASE_URL}/admin/tools/update-agent-profile`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.BEARER_TOKEN}`,
  },
  body: JSON.stringify({
    data: {
      agentId: 'k12-safety-agent',
      systemPrompt: 'You are a K12 safety analysis agent...',
      llmOverrides: { temperature: 0.3 },
      createdBy: 'ops@example.com'
    }
  })
});

const result = await response.json();
console.log('New profile version:', result.version);

Output​

Returns the newly created profile record including:

  • agentId - Agent identifier
  • version - New version number
  • promptHash - Hash of the prompt content
  • systemPrompt - The stored prompt text
  • llmOverrides - LLM parameter overrides (if any)
  • createdAt - Timestamp
  • createdBy - Creator identifier

Use Cases​

  • Initial Setup: Seed agent prompts during deployment
  • Prompt Tuning: Update agent behaviors based on testing
  • Configuration Management: Manage different prompt versions across environments
  • Automated Updates: Deploy prompt changes via CI/CD

Database Schema​

Profiles are stored in Core.AgentProfiles with the following key fields:

  • Unique constraint on (agentId, promptHash) prevents duplicate versions
  • IsCurrent flag marks the active version (only one per agent)
  • Previous versions remain in the table for audit history