The POST /execute-skill RPC endpoint enables dynamic execution of persona skills within conversation contexts. This powerful system allows AI personas to access external systems, perform complex operations, and enhance conversations with real-time data and functionality beyond simple text responses.
POST https://your-api-name.mercury.ratiomachina.com/execute-skill Content-Type: application/json Authorization: x-mercury-api-key: YOUR_API_KEY
Execute a single skill with parameters to retrieve information or perform an action within a conversation context.
{
"skill_id": "uuid-skill-crm-lookup",
"conversation_id": "uuid-conv-123",
"parameters": {
"email": "john.smith@techcorp.com",
"include_history": true,
"enrich_social": false
},
"execution_options": {
"timeout_seconds": 30,
"retry_on_failure": true,
"return_raw_response": false,
"cache_results": true
},
"context": {
"persona_id": "uuid-persona-sales-alex",
"execution_reason": "customer_qualification",
"conversation_stage": "initial_contact"
}
}{
"execution_result": {
"status": "success",
"execution_id": "uuid-exec-456",
"skill_id": "uuid-skill-crm-lookup",
"execution_time_ms": 1850,
"cache_hit": false
},
"result": {
"contact_found": true,
"contact_details": {
"name": "John Smith",
"company": "TechCorp Solutions",
"title": "VP of Engineering",
"phone": "+1-555-0123",
"email": "john.smith@techcorp.com",
"last_interaction": "2024-01-10T15:30:00Z"
},
"interaction_history": [
{
"date": "2024-01-10",
"type": "email",
"subject": "Product demo request",
"outcome": "demo_scheduled"
},
{
"date": "2024-01-08",
"type": "website_visit",
"pages": ["pricing", "features", "integration"],
"duration": "12m 34s"
}
],
"lead_score": 85,
"confidence_score": 0.92
},
"metadata": {
"skill_name": "CRM Contact Lookup",
"data_sources": ["salesforce", "hubspot"],
"processing_steps": [
"email_validation",
"crm_search",
"history_retrieval",
"score_calculation"
],
"api_calls_made": 2,
"cached_until": "2024-01-15T17:30:00Z"
}
}Execute multiple related skills in sequence, where the output of one skill can be used as input for subsequent skills.
{
"execution_type": "workflow",
"conversation_id": "uuid-conv-789",
"workflow": {
"name": "lead_qualification_workflow",
"steps": [
{
"step_id": "contact_lookup",
"skill_id": "uuid-skill-crm-lookup",
"parameters": {
"email": "mary.davis@innovatetech.com",
"include_history": true
},
"output_mapping": {
"company_name": "$.contact_details.company",
"lead_score": "$.lead_score",
"industry": "$.contact_details.industry"
}
},
{
"step_id": "company_research",
"skill_id": "uuid-skill-company-intel",
"parameters": {
"company_name": "${contact_lookup.company_name}",
"include_financials": true,
"include_technology": true
},
"condition": "${contact_lookup.contact_found} === true",
"output_mapping": {
"company_size": "$.company_info.employee_count",
"annual_revenue": "$.company_info.revenue",
"tech_stack": "$.technology.primary_tools"
}
},
{
"step_id": "personalization_engine",
"skill_id": "uuid-skill-message-personalizer",
"parameters": {
"contact_info": "${contact_lookup.contact_details}",
"company_info": "${company_research.company_info}",
"lead_score": "${contact_lookup.lead_score}",
"message_type": "initial_outreach"
},
"final_step": true
}
]
},
"execution_options": {
"parallel_where_possible": true,
"stop_on_failure": false,
"return_intermediate_results": true,
"timeout_per_step_seconds": 20
}
}{
"execution_result": {
"status": "success",
"workflow_name": "lead_qualification_workflow",
"execution_id": "uuid-workflow-exec-123",
"total_execution_time_ms": 4200,
"steps_completed": 3,
"steps_failed": 0
},
"step_results": {
"contact_lookup": {
"status": "success",
"execution_time_ms": 1850,
"result": {
"contact_found": true,
"contact_details": {
"name": "Mary Davis",
"company": "InnovateTech Solutions",
"title": "VP of Engineering",
"industry": "fintech"
},
"lead_score": 78
}
},
"company_research": {
"status": "success",
"execution_time_ms": 1950,
"result": {
"company_info": {
"employee_count": 245,
"revenue": "$25M-50M",
"founded": 2018,
"growth_stage": "series_b"
},
"technology": {
"primary_tools": ["AWS", "React", "Node.js", "PostgreSQL"],
"cloud_provider": "AWS",
"development_stack": "modern"
}
}
},
"personalization_engine": {
"status": "success",
"execution_time_ms": 400,
"result": {
"personalized_message": "Hi Mary! I noticed InnovateTech is scaling rapidly (congrats on the growth!). With your AWS-based stack and 245+ person team, you might be interested in how we've helped similar Series B fintech companies streamline their development workflows. Our platform integrates seamlessly with React/Node.js environments and has helped teams like yours reduce deployment time by 40%. Worth a quick 15-minute conversation?",
"personalization_factors": [
"company_growth_stage",
"technology_stack_match",
"industry_specific_benefits",
"team_size_appropriate"
],
"estimated_relevance": 0.89
}
}
},
"workflow_outputs": {
"qualified_lead": true,
"qualification_score": 78,
"recommended_approach": "technical_value_proposition",
"next_best_action": "personalized_outreach",
"estimated_conversion_probability": 0.34
},
"metadata": {
"total_api_calls": 5,
"data_sources_accessed": ["salesforce", "clearbit", "builtwith"],
"cache_utilization": "45%",
"workflow_efficiency": 0.92
}
}Execute skills in real-time during active conversations to provide immediate, contextual responses with live data.
{
"execution_type": "real_time_integration",
"conversation_id": "uuid-conv-live-chat-001",
"trigger": {
"event": "customer_question",
"last_message": "What's the status of my order #ORD-123456?",
"customer_id": "uuid-customer-456"
},
"skill_chain": [
{
"skill_id": "uuid-skill-order-lookup",
"parameters": {
"order_id": "ORD-123456",
"customer_id": "uuid-customer-456",
"include_tracking": true
},
"max_execution_time_ms": 3000
},
{
"skill_id": "uuid-skill-response-generator",
"parameters": {
"response_type": "order_status_update",
"tone": "helpful_informative",
"include_next_steps": true,
"order_data": "${order_lookup.result}"
},
"condition": "${order_lookup.status} === 'success'"
}
],
"real_time_options": {
"typing_indicator": true,
"response_deadline_ms": 5000,
"fallback_on_timeout": true,
"stream_results": false
},
"context": {
"channel": "live_chat",
"customer_wait_time": "45s",
"conversation_urgency": "medium",
"business_hours": true
}
}{
"execution_result": {
"status": "success",
"execution_id": "uuid-realtime-exec-789",
"total_execution_time_ms": 2850,
"real_time_constraints_met": true,
"chain_completed": true
},
"skill_results": {
"order_lookup": {
"status": "success",
"execution_time_ms": 2100,
"result": {
"order_found": true,
"order_details": {
"order_id": "ORD-123456",
"status": "shipped",
"shipped_date": "2024-01-14T09:15:00Z",
"tracking_number": "1Z999E1234567890",
"carrier": "UPS",
"estimated_delivery": "2024-01-16T17:00:00Z"
},
"items": [
{
"name": "Enterprise Software License",
"quantity": 1,
"status": "shipped"
}
]
}
},
"response_generator": {
"status": "success",
"execution_time_ms": 750,
"result": {
"generated_response": "Great news! Your order #ORD-123456 shipped yesterday (Jan 14th) and is currently in transit with UPS. Your tracking number is 1Z999E1234567890, and it's scheduled to arrive by Tuesday, January 16th at 5:00 PM. \n\nYou can track your package in real-time at ups.com or I can send you tracking updates. Is there anything else I can help you with regarding your order?",
"response_elements": {
"status_confirmation": true,
"tracking_details": true,
"delivery_timeline": true,
"next_steps": true,
"follow_up_offer": true
},
"estimated_satisfaction": 0.91
}
}
},
"immediate_response": {
"message": "Great news! Your order #ORD-123456 shipped yesterday (Jan 14th) and is currently in transit with UPS. Your tracking number is 1Z999E1234567890, and it's scheduled to arrive by Tuesday, January 16th at 5:00 PM. \n\nYou can track your package in real-time at ups.com or I can send you tracking updates. Is there anything else I can help you with regarding your order?",
"response_type": "direct_answer",
"confidence": 0.95,
"contains_actionable_info": true
},
"follow_up_actions": [
{
"action": "schedule_delivery_reminder",
"timing": "day_before_delivery",
"parameters": {
"reminder_message": "Your order arrives tomorrow!",
"include_tracking": true
}
},
{
"action": "post_delivery_satisfaction_survey",
"timing": "2_days_after_delivery",
"condition": "delivery_confirmed"
}
],
"performance_metrics": {
"response_generated_in_sla": true,
"customer_wait_time_total": "3.85s",
"data_accuracy": 1.0,
"response_completeness": 0.94
}
}Execute skills across multiple conversations or contexts simultaneously for efficient bulk processing.
{
"execution_type": "batch",
"skill_id": "uuid-skill-lead-scoring",
"batch_executions": [
{
"execution_id": "batch-001",
"conversation_id": "uuid-conv-123",
"parameters": {
"contact_email": "john.smith@techcorp.com",
"interaction_count": 3,
"last_interaction": "demo_request"
}
},
{
"execution_id": "batch-002",
"conversation_id": "uuid-conv-456",
"parameters": {
"contact_email": "mary.davis@innovatetech.com",
"interaction_count": 5,
"last_interaction": "pricing_inquiry"
}
},
{
"execution_id": "batch-003",
"conversation_id": "uuid-conv-789",
"parameters": {
"contact_email": "robert.wilson@startup.com",
"interaction_count": 1,
"last_interaction": "initial_contact"
}
}
],
"batch_options": {
"parallel_processing": true,
"max_concurrent_executions": 5,
"continue_on_individual_failures": true,
"return_partial_results": true,
"batch_timeout_seconds": 60
}
}{
"execution_result": {
"status": "completed",
"batch_id": "uuid-batch-exec-456",
"total_executions": 3,
"successful_executions": 3,
"failed_executions": 0,
"total_processing_time_ms": 8400,
"average_execution_time_ms": 2800
},
"results": [
{
"execution_id": "batch-001",
"conversation_id": "uuid-conv-123",
"status": "success",
"execution_time_ms": 2650,
"result": {
"lead_score": 85,
"score_factors": {
"engagement_level": 0.9,
"company_fit": 0.8,
"budget_indicators": 0.85,
"timeline_urgency": 0.7
},
"recommended_priority": "high",
"next_best_action": "schedule_technical_demo"
}
},
{
"execution_id": "batch-002",
"conversation_id": "uuid-conv-456",
"status": "success",
"execution_time_ms": 3100,
"result": {
"lead_score": 92,
"score_factors": {
"engagement_level": 0.95,
"company_fit": 0.9,
"budget_indicators": 0.9,
"timeline_urgency": 0.85
},
"recommended_priority": "critical",
"next_best_action": "executive_demo_request"
}
},
{
"execution_id": "batch-003",
"conversation_id": "uuid-conv-789",
"status": "success",
"execution_time_ms": 2650,
"result": {
"lead_score": 45,
"score_factors": {
"engagement_level": 0.4,
"company_fit": 0.6,
"budget_indicators": 0.3,
"timeline_urgency": 0.2
},
"recommended_priority": "low",
"next_best_action": "nurture_sequence"
}
}
],
"aggregated_insights": {
"average_lead_score": 74,
"high_priority_leads": 2,
"immediate_follow_ups_needed": 2,
"leads_for_nurture": 1,
"total_potential_value": "$125,000"
},
"performance_summary": {
"batch_efficiency": 0.93,
"resource_utilization": "optimal",
"parallel_processing_benefit": "45% time_savings",
"api_calls_total": 9,
"cache_hit_rate": 0.33
}
}timeout_seconds - Maximum execution timeretry_on_failure - Automatic retry on errorsretry_count - Maximum retry attemptscache_results - Enable result cachingcache_ttl_seconds - Cache expiration timereturn_raw_response - Include unprocessed API responsesinclude_debug_info - Add execution debugging detailsinclude_performance_metrics - Add timing and efficiency datastream_results - Stream results as they become availablevalidate_output - Validate result against schema{
"execution_result": {
"status": "failed",
"execution_id": "uuid-failed-exec-123",
"skill_id": "uuid-skill-api-integration",
"execution_time_ms": 10000,
"error_type": "timeout"
},
"error": {
"code": "SKILL_EXECUTION_TIMEOUT",
"message": "Skill execution exceeded maximum timeout of 10 seconds",
"details": {
"timeout_seconds": 10,
"partial_results_available": true,
"retry_recommended": true,
"alternative_skills": [
"uuid-skill-cached-lookup",
"uuid-skill-fallback-data"
]
}
},
"partial_results": {
"steps_completed": 2,
"last_successful_step": "data_validation",
"incomplete_step": "external_api_call",
"available_data": {
"validation_passed": true,
"parameters_processed": true
}
},
"retry_guidance": {
"recommended_timeout": 15,
"suggested_parameters": {
"timeout_seconds": 15,
"use_cache": true,
"fallback_enabled": true
},
"alternative_approaches": [
"Use cached data if available",
"Execute with reduced parameter set",
"Try alternative skill with similar functionality"
]
}
}