Skip to main content

​
Execute Tool Endpoint

POST /v1/execute_tool Execute a tool with specified parameters and get results.

​
Request Body

{
  "tool_name": "create-pull-request",
  "params": {
    "repository": "owner/repo",
    "title": "Add new feature",
    "from_branch": "feature/x",
    "to_branch": "main"
  },
  "timeout": 30000
}

​
Parameters

ParameterTypeRequiredDefaultDescription
tool_namestringYes-Name of tool to execute
paramsobjectYes-Tool-specific parameters
timeoutintegerNo30000Timeout in milliseconds

​
Response

{
  "success": true,
  "data": {
    "tool_name": "create-pull-request",
    "status": "success",
    "result": {
      "pr_number": 123,
      "pr_url": "https://github.com/owner/repo/pull/123",
      "created_at": "2024-01-15T10:30:00Z"
    },
    "execution_time_ms": 245,
    "tokens_used": {
      "input": 150,
      "output": 200
    }
  },
  "meta": {
    "request_id": "exec_def456",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

​
Examples

​
Create GitHub PR

curl -X POST "https://api.agent-corex.com/v1/execute_tool" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "create-pull-request",
    "params": {
      "repository": "owner/repo",
      "title": "Fix critical bug",
      "from_branch": "hotfix/bug-123",
      "to_branch": "main",
      "body": "This PR fixes a critical production bug"
    }
  }'

​
Deploy to AWS

curl -X POST "https://api.agent-corex.com/v1/execute_tool" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "deploy-aws-lambda",
    "params": {
      "function_name": "my-function",
      "zip_file": "function.zip",
      "environment": "production"
    }
  }'

​
Using SDK

const result = await agent.executeTool({
  toolName: 'create-pull-request',
  params: {
    repository: 'owner/repo',
    title: 'New feature',
    from_branch: 'feature/x',
    to_branch: 'main'
  }
});

console.log(`PR created: ${result.result.pr_url}`);

​
Error Responses

​
Tool Not Found (404)

{
  "success": false,
  "error": {
    "code": "TOOL_NOT_FOUND",
    "message": "Tool 'create-pull-request' not found or not connected"
  }
}

​
Invalid Parameters (400)

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required parameter: repository",
    "details": {
      "parameter": "repository",
      "reason": "required"
    }
  }
}

​
Timeout (504)

{
  "success": false,
  "error": {
    "code": "TIMEOUT",
    "message": "Tool execution timed out after 30000ms"
  }
}

​
Execution Failed (500)

{
  "success": false,
  "error": {
    "code": "EXECUTION_ERROR",
    "message": "Failed to create PR: Branch does not exist",
    "details": {
      "tool_error": "Invalid branch name"
    }
  }
}

​
Best Practices

  1. Always handle errors 
    try {
  const result = await agent.executeTool({...});
} catch (error) {
  if (error.code === 'TOOL_NOT_FOUND') {
    // Guide user to connect tool
  }
}
  2. Set appropriate timeouts
    • Quick operations: 5-10 seconds
    • API calls: 15-30 seconds
    • Infrastructure tasks: 60+ seconds
  3. Validate parameters before executing
    • Check required fields
    • Validate formats (URLs, names, etc.)
  4. Implement retry logic 
    const executeWithRetry = async (toolName, params, maxRetries = 3) => {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await agent.executeTool({ toolName, params });
    } catch (error) {
      if (error.code === 'RATE_LIMITED' && i < maxRetries - 1) {
        await delay(1000 * Math.pow(2, i)); // Exponential backoff
      } else {
        throw error;
      }
    }
  }
};

​
Next Steps

Retrieve Tools

Find tools before executing.

Real Examples

See execution flows.

Error Handling

Common error codes.
Ready to execute tools? See sample queries for real workflows! 🚀